# darafarm/risk-controlled-postgresql-planner-steering architecture

> Architecture diagram of the GitHub repository darafarm/risk-controlled-postgresql-planner-steering, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/darafarm/risk-controlled-postgresql-planner-steering
- Repository: https://github.com/darafarm/risk-controlled-postgresql-planner-steering

## Overview

RiskSteer is a PostgreSQL query-planner steering research system: it inspects a query plan, predicts a join-planner configuration, and applies steering only when predicted savings clear a risk threshold. The README documents this intended pre-execution workflow and its four planner arms. The sampled code primarily implements benchmark collection, model evaluation, analysis, and visualization; it does not show a deployed pre-execution policy or risk gate, so those relationships are documented rather than source-verified.

Main entry points: [`src`](https://github.com/darafarm/risk-controlled-postgresql-planner-steering/tree/main/src) (Plan Inspection), [`queries/job_queries_scaled`](https://github.com/darafarm/risk-controlled-postgresql-planner-steering/tree/main/queries/job_queries_scaled) (JOB Workload), [`src/job_runner_10queries.py`](https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/job_runner_10queries.py) (Arm Benchmark), [`src/train_model.py`](https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/train_model.py) (Model Evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_steering["Query Steering"]
  node_preexplain["Plan Inspection"]
  node_feature["Plan Features<br/>[untitled11.py]"]
  node_classifier["Arm Classifier<br/>[train_model.py]"]
  node_riskgate["Risk Threshold<br/>[train_model.py]"]
  node_armsettings["Planner Arms<br/>[untitled11.py]"]
end

subgraph group_experiments["Benchmark Experiments"]
  node_job["JOB Workload"]
  node_benchmark["Arm Benchmark"]
  node_dataset[("Run Dataset<br/>[ML_dataset.py]")]
end

subgraph group_modeling["Modeling and Analysis"]
  node_featureset["Feature Dataset<br/>[train_model.py]"]
  node_evaluation["Model Evaluation<br/>[train_model.py]"]
  node_oracle["Oracle Analysis<br/>[analysis_904.py]"]
end

subgraph group_reporting["Results and Reporting"]
  node_visualization["Result Plots<br/>[visualization.py]"]
end

node_analyst(("Query User"))
node_postgres[("PostgreSQL")]

node_analyst -.->|"submits query"| node_job
node_job -.->|"supplies query"| node_preexplain
node_preexplain -.->|"requests plan"| node_postgres
node_preexplain -.->|"returns plan"| node_feature
node_feature -.->|"provides features"| node_classifier
node_classifier -.->|"predicts arm"| node_riskgate
node_riskgate -.->|"selects or defaults"| node_armsettings
node_armsettings -.->|"sets planner options"| node_postgres
node_postgres -.->|"records outcomes"| node_dataset
node_job -->|"runs workload"| node_benchmark
node_benchmark -->|"executes EXPLAIN ANALYZE"| node_postgres
node_benchmark -->|"inserts run records"| node_dataset
node_dataset -.->|"provides samples"| node_featureset
node_featureset -->|"trains and evaluates"| node_evaluation
node_evaluation -.->|"compares outcomes"| node_oracle
node_evaluation -.->|"summarizes results"| node_visualization

click node_job "https://github.com/darafarm/risk-controlled-postgresql-planner-steering/tree/main/queries/job_queries_scaled"
click node_preexplain "https://github.com/darafarm/risk-controlled-postgresql-planner-steering/tree/main/src"
click node_feature "https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/untitled11.py"
click node_classifier "https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/train_model.py"
click node_riskgate "https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/train_model.py"
click node_armsettings "https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/untitled11.py"
click node_benchmark "https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/job_runner_10queries.py"
click node_dataset "https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/ML_dataset.py"
click node_featureset "https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/train_model.py"
click node_evaluation "https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/train_model.py"
click node_oracle "https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/analysis_904.py"
click node_visualization "https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/visualization.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_preexplain,node_feature,node_classifier,node_riskgate,node_armsettings,node_analyst toneBlue
class node_job,node_benchmark,node_dataset,node_postgres toneAmber
class node_featureset,node_evaluation,node_oracle toneMint
class node_visualization toneRose
```

## Components

### Query Steering

- [Plan Inspection](https://github.com/darafarm/risk-controlled-postgresql-planner-steering/tree/main/src): `src`
- [Plan Features](https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/untitled11.py): `src/untitled11.py`
- [Arm Classifier](https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/train_model.py): `src/train_model.py`
- [Risk Threshold](https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/train_model.py): `src/train_model.py`
- [Planner Arms](https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/untitled11.py): `src/untitled11.py`

### Benchmark Experiments

- [JOB Workload](https://github.com/darafarm/risk-controlled-postgresql-planner-steering/tree/main/queries/job_queries_scaled): `queries/job_queries_scaled`
- [Arm Benchmark](https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/job_runner_10queries.py): `src/job_runner_10queries.py`
- [Run Dataset](https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/ML_dataset.py): `src/ML_dataset.py`

### Modeling and Analysis

- [Feature Dataset](https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/train_model.py): `src/train_model.py`
- [Model Evaluation](https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/train_model.py): `src/train_model.py`
- [Oracle Analysis](https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/analysis_904.py): `src/analysis_904.py`

### Results and Reporting

- [Result Plots](https://github.com/darafarm/risk-controlled-postgresql-planner-steering/blob/main/src/visualization.py): `src/visualization.py`

### Other components

- **Query User**
- **PostgreSQL**

## Connections

- Query User → JOB Workload: submits query (evidence: `README.md`)
- JOB Workload → Plan Inspection: supplies query (evidence: `README.md`)
- Plan Inspection → PostgreSQL: requests plan (evidence: `README.md`)
- Plan Inspection → Plan Features: returns plan (evidence: `README.md`)
- Plan Features → Arm Classifier: provides features (evidence: `README.md`)
- Arm Classifier → Risk Threshold: predicts arm (evidence: `README.md`)
- Risk Threshold → Planner Arms: selects or defaults (evidence: `README.md`)
- Planner Arms → PostgreSQL: sets planner options (evidence: `README.md`)
- PostgreSQL → Run Dataset: records outcomes (evidence: `README.md`)
- JOB Workload → Arm Benchmark: runs workload (evidence: `src/job_runner_10queries.py`)
- Arm Benchmark → PostgreSQL: executes EXPLAIN ANALYZE (evidence: `src/job_runner_10queries.py`)
- Arm Benchmark → Run Dataset: inserts run records (evidence: `src/ML_dataset.py`)
- Run Dataset → Feature Dataset: provides samples (evidence: `README.md`)
- Feature Dataset → Model Evaluation: trains and evaluates (evidence: `src/train_model.py`)
- Model Evaluation → Oracle Analysis: compares outcomes (evidence: `README.md`)
- Model Evaluation → Result Plots: summarizes results (evidence: `README.md`)