Recurring checks (cron)

Schedule pgdba with cron or systemd, gate on exit codes, and alert via webhook.

pgdba is a one-shot CLI — schedule it instead of running a daemon.

# light check every 5 minutes, full scan weekly
*/5 * * * *  pgdba check --dsn "$DATABASE_URL" --skip-heavy --warning 1 --critical 1 --log-format json
0 3 * * 0    pgdba check --dsn "$DATABASE_URL" --state-dir /var/lib/pgdba --webhook-url https://alerts.example.com/hook

# zero-flag run: everything (dsn, thresholds, webhook) lives in pgdba-run.toml
*/5 * * * *  cd /etc/pgdba && pgdba check

Or: gate the deploy pipeline itself

The same command doubles as a CI pre-deploy gate: run it in the deploy job after migrations, before traffic:

pgdba check --skip-heavy --warning 1 --critical 1 --log-format json

Exit 0 → pipeline proceeds; exit 1/2 → pipeline stops and the report names the findings; exit 3 → the database is unreachable (a different alert than “unhealthy”).

How the pieces fit

--state-dir persists snapshot.json between runs, so later runs report baseline / resolved / new / unchanged deltas instead of repeating a cold first scan. It also homes pgdba-baseline.json once saved (see below).
--warning M / --critical N turn findings into exit codes: exit 1 when warning-or-worse reaches M, exit 2 when critical reaches N. With either threshold set and no breach, the exit is 0 even if findings exist.
--webhook-url URL POSTs the alert payload when thresholds breach.
--skip-heavy drops the slow scan-everything checks (index bloat estimation and friends) so frequent runs stay fast; run the full set weekly.
--log-format json emits structured, run-id-annotated log lines for shippers.

Alert only on change (baselines)

Accept the known findings once, then page only when the set changes:

pgdba check --dsn "$DATABASE_URL" --state-dir /var/lib/pgdba
pgdba baseline save --state-dir /var/lib/pgdba   # accept current findings

pgdba check --dsn "$DATABASE_URL" --state-dir /var/lib/pgdba --fail-on-drift new

--fail-on-drift new|resolved|any exits 1 when drift of that class exists, independent of severity thresholds; without the flag the exit is unchanged. pgdba baseline show prints the accepted set, update re-accepts after a reviewed change, and clear drops it. The text report gains drift: lines, the Markdown report a “Since baseline” section, and the JSON report an agent-readable drift block (ids plus the baseline run provenance).

Cron contract

Alert only on non-zero exit:

pgdba check --dsn "$DATABASE_URL" --skip-heavy --warning 1 --critical 1 \
  || [ $? -ge 1 ] && notify

Exit 3 means config/connect trouble (not findings) — page on it separately, it usually means the target is unreachable.