Agentic Postgres DBA. No extension required.
pg_sage runs as a single Go binary alongside your PostgreSQL instance. It connects over the standard wire protocol, collects performance data from catalog views and pg_stat_statements, runs 20+ diagnostic rules, and optionally uses an LLM for deeper analysis. A trust-ramped executor applies fixes automatically -- starting in observation mode and graduating to autonomous actions only after a configurable burn-in period. Works on Cloud SQL, AlloyDB, Aurora, RDS, and self-managed Postgres.
# Binary (Linux amd64)
curl -fsSL https://github.com/jasonmassie01/pg_sage/releases/latest/download/pg_sage_linux_amd64.tar.gz | tar xz
./pg_sage --pg-url "postgres://sage_agent:pw@localhost:5432/mydb"
# Docker
docker run -e SAGE_DATABASE_URL="postgres://sage_agent:pw@host:5432/mydb" \
-p 8080:8080 -p 9187:9187 ghcr.io/jasonmassie01/pg_sage:latestDashboard at http://localhost:8080 -- API and Prometheus metrics at :8080/api/v1/ and :9187/metrics.
| Area | What You Get |
|---|---|
| Rules Engine | 20+ deterministic checks: duplicate/unused/missing indexes, slow queries, regressions, seq scans, vacuum & bloat, dead tuples, sequence exhaustion, replication lag, security audit, config drift |
| Index Optimizer | LLM-powered recommendations validated through 8 checks + HypoPG cost estimation, confidence scored 0.0--1.0 |
| Config Advisors | 6 LLM advisors: vacuum tuning, WAL/checkpoint, connections, memory, query rewrite, bloat remediation |
| Health Briefings | Periodic LLM-generated summaries of database state; interactive diagnose via ReAct loop |
| Trust-Ramped Executor | Observation (day 0--7) -> Advisory (day 8--30) -> Autonomous (day 31+). HIGH-risk actions always require confirmation. Full rollback SQL logged. Emergency stop endpoint. |
| Fleet Mode | Monitor N databases from one binary with per-database trust levels, token budgets, and health scores |
| Per-Query Tuner | EXPLAIN plan analysis with pg_hint_plan directives for disk sorts, hash spills, bad joins, missed index scans |
| Workload Forecaster | Predicts disk growth, connection saturation, cache pressure, sequence exhaustion, query volume spikes, checkpoint pressure |
| Alerting | Slack, PagerDuty, and webhook channels with per-severity routing, cooldown, and quiet hours |
| Dashboard & API | React SPA + 49 REST endpoints embedded in the binary -- nothing extra to deploy |
| Prometheus | Standard /metrics endpoint with findings, collector, LLM, executor, and database size gauges |
See the docs/ directory for guides and reference:
- Installation -- database user setup, binary and Docker deployment
- Configuration -- YAML, environment variables, hot reload
- Architecture -- component design, goroutine model, data flow
- Deployment -- production hardening, resource sizing
- Security -- permissions model, network, secrets management
- SQL Reference -- schema tables and diagnostic queries
- Findings Reference -- every rule, severity, and remediation
- Walkthroughs: Linux | Windows | Fleet
Requires Go 1.24+ and Node.js 20+. See docs/installation.md for details.
cd sidecar
cd web && npm ci && npm run build && cd ..
go build -o pg_sage ./cmd/pg_sage_sidecar/