pgdba

Your first check

What pgdba is, in three sentences

pgdba connects to your database, runs a registry of read-only health checks, and prints a ranked report: every finding says what is wrong, what it costs to ignore, and the exact SQL to fix it. You decide what to apply — fixes only run when you pass --apply and approve them. It also migrates databases server-to-server behind preflight gates, with verification.

The three commands you will actually use:

Command What it does
pgdba check The health report (read-only, always safe)
pgdba check --apply Execute the fixes you approved
pgdba migrate Server-to-server migration with gates

Everything else — profiles, thresholds, webhooks, doctor — hangs off these.

Install

Install

# from the repo
git clone <your-repo-url> && cd pgdba
uv sync

# check the CLI works
uv run pgdba --help

On-ramp: write a run-config once

pgdba config init asks for host, port, database, user, and password (hidden), probes the connection read-only before writing, and produces a pgdba-run.toml with chmod 600:

$ pgdba config init
probed: PostgreSQL 17.11 in 85.4ms (postgres@localhost:5436/postgres)
wrote pgdba-run.toml (chmod 600); loader re-validated the file

Non-interactive (CI/scripts):

pgdba config init --host prod-db.corp --port 5432 --dbname app \
  --user pgdba --password "$PGDBA_PASSWORD" --name prod

Tip

config init never writes a file it could not verify, refuses to overwrite an existing config without --force, and re-validates the written file through the same loader every later command uses.

Run your first check

$ pgdba check

Zero flags: the connection profile comes from pgdba-run.toml. You get ranked findings in the terminal plus pgdba-report.md / pgdba-report.json, with matching stable IDs, a duty-group triage view, and exit codes suitable for cron:

  • 0 OK — no warning-or-worse findings
  • 1 WARNING — warning threshold reached
  • 2 CRITICAL — critical threshold reached
  • 3 UNKNOWN — config, connection, or apply error

Where to next

Edit this page on GitHub