Exit codes
The cron contract: what each exit code means for check, migrate, doctor, and verify-restore.
pgdba check
| Exit | Meaning |
|---|---|
| 0 | OK — no warning-or-worse findings (or thresholds set and not breached) |
| 1 | WARNING — warning threshold reached (also: non-TTY --apply refusal) |
| 2 | CRITICAL — critical threshold reached |
| 3 | UNKNOWN — config, connection, or apply error |
Threshold interaction: --critical N exits 2 when critical count ≥ N;
--warning M exits 1 when warning+critical count ≥ M. With either threshold
set and no breach, the exit is 0 even if findings exist; without thresholds,
the exit follows the worst finding severity.
Drift interaction: --fail-on-drift new|resolved|any exits 1 when drift of
that class exists (needs a saved baseline, else a no-op), independent of
thresholds; it never lowers an exit — a critical run still exits 2.
pgdba baseline
0 ok (including clear with nothing to clear) · 3 missing report (save /
update need a prior check), missing baseline (show), or save when a
baseline already exists (use update).
pgdba audit show
0 always (including an empty trail — “no audit lines” is a legitimate state).
pgdba self-scan
0 every scanned sink clean (a skipped contract check without --dsn is not
a failure) · 1 secret residue found or contract verification failed ·
3 config/connect errors.
pgdba fix
0 plan written (dry-run, including guidance-only manual plans) / applied /
reverted / nothing left to do · 1 --apply/--revert without --yes on a
non-TTY session · 3 unknown finding id, ambiguous id, --apply with
--revert, --apply/--revert on a manual plan, or execution failure.
pgdba fleet check
Worst per-target exit (0/1/2 by the same rules as check, drift gates
included) · 3 fleet config errors (missing file, unknown profile, bad
target) or any unreachable target when it is the worst outcome.
pgdba serve
--once: worst per-target exit, same rules as fleet check · 3 config
errors, pidfile held by a live instance, or remote --bind without the
unauthenticated ack. The daemon itself exits 0 on a clean SIGTERM/SIGINT
shutdown (in-flight checks finish first).
pgdba migrate
0 success · 1 verify/report failures · 2 CRITICAL findings on gate ·
3 preflight/confirm/config errors (non-TTY without --yes aborts here with
zero target writes).
pgdba config doctor
0 valid and every profile connects · 1 validation passed but a probe failed · 3 validation failed or the config is missing (names the discovery order).
pgdba verify-restore
0 verified · 1 rehearsal issues (report says which) · 3 config/fencing errors.
Note
Cron rule: alert on any non-zero exit; exit 3 usually means unreachable, not unhealthy — page on it separately.