Flags & config keys
Every entry below is the exact text behind pgdba check --explain-flag <name> — one source of truth.
Flags and config keys
| Key | term | definition | when_to_use | safe_default |
|---|---|---|---|---|
pooled |
pooled (profile key) | Marks a run-config profile as living behind a transaction pooler. The safety contract is then enforced per-statement with SET LOCAL instead of session SETs. | Set it on any profile whose DSN points at PgBouncer or a hosted pooler endpoint. | false. Only set it when a pooler is actually in the path. |
direct_dsn |
direct_dsn (profile key) | The direct (non-pooler) DSN for a pooled profile. DDL operations (apply, migrate) route here because transaction poolers cannot carry them. | Required whenever pooled = true and the profile must serve apply or migrate roles. | unset. Only pooled profiles carrying DDL need it. |
dsn_env |
dsn_env (profile key) | Names an environment variable that holds the profile’s DSN, keeping credentials out of the file. | CI and shared machines where pgdba-run.toml is committed but secrets are not. | unset; a literal dsn in the file is fine on a chmod 600 file. |
statement_timeout |
statement_timeout | Caps how long any single statement may run before the server cancels it. pgdba defaults to 30 seconds; apply uses the profile’s value for DDL. | Raise it on profiles where legitimate DDL (index builds) exceeds 30s. | 30 seconds for checks; per-profile value for apply. |
connect_timeout |
connect_timeout | Caps the TCP connect + auth handshake. A hung host cannot stall a run longer than this. | Lower it for fast-failing cron probes; raise it only for high-latency links. | 10 seconds. |
default |
default (config key) | Names which [connections] profile is used when no –connection flag is given. | Set it to your most-used profile so zero-flag runs work. | unset; then –connection is required each run. |
state_dir |
–state-dir | Directory where pgdba-report.json/.md and trend history are written. | Cron runs and containerized runs where the working directory is not writable. | the current directory. |
skip_heavy |
–skip-heavy | Skips the slow scan-everything checks (index bloat estimation and friends) for a fast pass. | Cron, CI, and pre-deploy gates; run the full set weekly. | off (heavy checks run). |
only |
–only | Runs just the named check (repeatable), ignoring the default check set. | Verifying one specific finding after a fix. | unset; the full check set runs. |
extensions |
–extensions | Comma-separated extension names the run should analyze for version/upgrade findings, in addition to what it detects. | When an extension’s objects live in a schema pgdba does not auto-discover. | unset; extensions are auto-detected. |
warning |
–warning | Nagios-style threshold: exit 1 when warning-or-worse findings reach this count. | Cron gating together with –critical. | unset; exit follows the worst finding severity. |
critical |
–critical | Nagios-style threshold: exit 2 when critical findings reach this count. | Pageable alerting; combine with –webhook-url. | unset; exit follows the worst finding severity. |
webhook_url |
–webhook-url | POSTs the alert payload to this URL when the run breaches its thresholds. | Slack/Teams/webhook alerting from cron without a shell wrapper. | unset; no webhook is called. |
format |
–format | Output format for check’s console output (human table, json). The report files are always written. | Machine-readable runs that parse stdout directly. | human. |
level |
–level | Minimum finding severity included in output (critical/warning/info). | Quieter terminal output during triage. | info (everything). |
log_format |
–log-format | Run-log format: text (human) or json (structured, one event per line) for the run_id-annotated log lines. | JSON in log shippers and CI; text in terminals. | text. |
log_level |
–log-level | Verbosity of the run log (debug/info/warning/error). | Debug when investigating a surprising finding or error. | info. |
connection |
–connection | Named profile from the run-config file to use for this run. | Multi-environment setups; –connection staging targets staging. | the file’s default key. |
config |
–config | Explicit path to the run-config file, overriding discovery. | Multiple config files side by side (prod.toml, staging.toml). | discovery order: PGDBA_CONFIG env, then ./pgdba-run.toml. |
apply |
–apply | Executes the remediation SQL of the findings you approved, instead of only printing it. Still prompts per action. | Deliberately, after reviewing the plan; never in cron. | off (advice-only). |
yes |
–yes | Skips per-action confirmation for –apply (blanket approval). Requires –apply; refused without a TTY. | Scripted maintenance windows with a reviewed plan. | off (per-action prompts). |
dsn |
–dsn | Full connection string, overriding profile and env resolution. | One-off runs against a connection not worth a profile. | unset; DATABASE_URL / PGDBA_DATABASE_URL / config profile are tried instead. |
Tip
The safe_default column answers the real question: can I just not set this?