Postgres triage in one binary: read-only, baseline-aware, agent-ready

What it does

pgbot is a single static binary that connects to PostgreSQL 14–18 through a read-only pg_monitor role and prints a graded health report. It buckets findings into CRITICAL, WARNING, and GOOD lists so you see both what hurts and what was actually verified. After the first run it keeps a local baseline, so subsequent checks highlight what changed—queries that slowed, indexes that went idle, tables that started scanning sequentially.

The interesting bit

The tool treats AI as a translator, not a fortune-teller: every finding is computed deterministically in Go from Postgres’s own statistics views, and the optional ask/explain layer merely puts plain language on top. That discipline makes it safe to hand to agents—a versioned JSON contract and an MCP server expose the same structured, PII-free findings without scraping terminal output.

Key highlights

• Read-only by role, not by wishful thinking—pg_monitor, BEGIN READ ONLY, and session timeouts are defense in depth.
• Baseline memory: local snapshots let it report deltas (regressions, new bloat) rather than one-off snapshots.
• Fully offline core: deterministic inspection needs no API keys; the AI layer is strictly optional.
• Agent-native: versioned JSON schema and MCP interface for scripts and LLMs that need structured, stable data.
• CI-friendly exit codes and machine formats including SARIF and JUnit.

Caveats

• Explicitly beta. The human-readable report is not a stable API—rely on the versioned --json contract.
• PostgreSQL 14–15 support is best-effort; collectors degrade gracefully on older feature sets.
• Index-usage stats are per-node, so an “unused” index on a primary may still be active on a replica.

Verdict

Use it for fast, portable Postgres triage in CI, on a laptop, or inside an agent workflow. If you need long-term dashboards, alerting, or multi-host rollups, stay with a full monitoring platform like pganalyze or PMM.