Flags & config keys

What each flag/config key does, when to use it, and its safe default.

Every entry below is the exact text behind pgdba check --explain-flag <name> — one source of truth.

pooled · direct_dsn · dsn_env · statement_timeout · connect_timeout · default · state_dir · skip_heavy · only · extensions · warning · critical · fail_on_drift · journal · webhook_url · format · level · log_format · log_level · connection · config · apply · yes · dsn

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.

• When to use: Set it on any profile whose DSN points at PgBouncer or a hosted pooler endpoint.
• Safe default: false. Only set it when a pooler is actually in the path.
• Example: pooled = … under [connections.<name>] in pgdba-run.toml
• Try it: pgdba check --explain-flag pooled

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.

• When to use: Required whenever pooled = true and the profile must serve apply or migrate roles.
• Safe default: unset. Only pooled profiles carrying DDL need it.
• Example: direct_dsn = … under [connections.<name>] in pgdba-run.toml
• Try it: pgdba check --explain-flag direct_dsn

dsn_env

dsn_env (profile key)

Names an environment variable that holds the profile’s DSN, keeping credentials out of the file.

• When to use: CI and shared machines where pgdba-run.toml is committed but secrets are not.
• Safe default: unset; a literal dsn in the file is fine on a chmod 600 file.
• Example: dsn_env = … under [connections.<name>] in pgdba-run.toml
• Try it: pgdba check --explain-flag dsn_env

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.

• When to use: Raise it on profiles where legitimate DDL (index builds) exceeds 30s.
• Safe default: 30 seconds for checks; per-profile value for apply.
• Example: statement_timeout = … under [connections.<name>] in pgdba-run.toml
• Try it: pgdba check --explain-flag statement_timeout

connect_timeout

connect_timeout

Caps the TCP connect + auth handshake. A hung host cannot stall a run longer than this.

• When to use: Lower it for fast-failing cron probes; raise it only for high-latency links.
• Safe default: 10 seconds.
• Example: connect_timeout = … under [connections.<name>] in pgdba-run.toml
• Try it: pgdba check --explain-flag connect_timeout

default

default (config key)

Names which [connections] profile is used when no –connection flag is given.

• When to use: Set it to your most-used profile so zero-flag runs work.
• Safe default: unset; then –connection is required each run.
• Example: default = "prod" at the top of pgdba-run.toml
• Try it: pgdba check --explain-flag default

state_dir

–state-dir

Directory where pgdba-report.json/.md and trend history are written.

• When to use: Cron runs and containerized runs where the working directory is not writable.
• Safe default: the current directory.
• Example: pgdba check --state-dir
• Try it: pgdba check --explain-flag state_dir

skip_heavy

–skip-heavy

Skips the slow scan-everything checks (index bloat estimation and friends) for a fast pass.

• When to use: Cron, CI, and pre-deploy gates; run the full set weekly.
• Safe default: off (heavy checks run).
• Example: pgdba check --skip-heavy
• Try it: pgdba check --explain-flag skip_heavy

only

–only

Runs just the named check (repeatable), ignoring the default check set.

• When to use: Verifying one specific finding after a fix.
• Safe default: unset; the full check set runs.
• Example: pgdba check --only
• Try it: pgdba check --explain-flag only

extensions

–extensions

Comma-separated extension names the run should analyze for version/upgrade findings, in addition to what it detects.

• When to use: When an extension’s objects live in a schema pgdba does not auto-discover.
• Safe default: unset; extensions are auto-detected.
• Example: pgdba check --extensions
• Try it: pgdba check --explain-flag extensions

warning

–warning

Nagios-style threshold: exit 1 when warning-or-worse findings reach this count.

• When to use: Cron gating together with –critical.
• Safe default: unset; exit follows the worst finding severity.
• Example: pgdba check --warning
• Try it: pgdba check --explain-flag warning

critical

–critical

Nagios-style threshold: exit 2 when critical findings reach this count.

• When to use: Pageable alerting; combine with –webhook-url.
• Safe default: unset; exit follows the worst finding severity.
• Example: pgdba check --critical
• Try it: pgdba check --explain-flag critical

fail_on_drift

–fail-on-drift

Exits 1 when baseline drift of the named class exists (new, resolved, or any including severity changes), independent of severity thresholds. Requires a saved baseline, else a no-op.

• When to use: Cron alert-only-on-change gating after pgdba baseline save accepts the known set.
• Safe default: unset; exit follows thresholds and worst severity.
• Example: pgdba check --fail-on-drift
• Try it: pgdba check --explain-flag fail_on_drift

journal

–journal

Appends one zero-write audit line for the run to pgdba-audit.jsonl (state dir, else the current directory), recording the run id, check ids, statement classes, and the writes count. Never changes the exit code.

• When to use: Machine-verifiable read-only proof for auditors and agents; inspect with pgdba audit show.
• Safe default: off; no audit line is written.
• Example: pgdba check --journal
• Try it: pgdba check --explain-flag journal

webhook_url

–webhook-url

POSTs the alert payload to this URL when the run breaches its thresholds.

• When to use: Slack/Teams/webhook alerting from cron without a shell wrapper.
• Safe default: unset; no webhook is called.
• Example: pgdba check --webhook-url
• Try it: pgdba check --explain-flag webhook_url

format

–format

Output format for check’s console output (human table, json). The report files are always written.

• When to use: Machine-readable runs that parse stdout directly.
• Safe default: human.
• Example: pgdba check --format
• Try it: pgdba check --explain-flag format

level

–level

Minimum finding severity included in output (critical/warning/info).

• When to use: Quieter terminal output during triage.
• Safe default: info (everything).
• Example: pgdba check --level
• Try it: pgdba check --explain-flag level

log_format

–log-format

Run-log format: text (human) or json (structured, one event per line) for the run_id-annotated log lines.

• When to use: JSON in log shippers and CI; text in terminals.
• Safe default: text.
• Example: pgdba check --log-format
• Try it: pgdba check --explain-flag log_format

log_level

–log-level

Verbosity of the run log (debug/info/warning/error).

• When to use: Debug when investigating a surprising finding or error.
• Safe default: info.
• Example: pgdba check --log-level
• Try it: pgdba check --explain-flag log_level

connection

–connection

Named profile from the run-config file to use for this run.

• When to use: Multi-environment setups; –connection staging targets staging.
• Safe default: the file’s default key.
• Example: pgdba check --connection
• Try it: pgdba check --explain-flag connection

config

–config

Explicit path to the run-config file, overriding discovery.

• When to use: Multiple config files side by side (prod.toml, staging.toml).
• Safe default: discovery order: PGDBA_CONFIG env, then ./pgdba-run.toml.
• Example: pgdba check --config
• Try it: pgdba check --explain-flag config

apply

–apply

Executes the remediation SQL of the findings you approved, instead of only printing it. Still prompts per action.

• When to use: Deliberately, after reviewing the plan; never in cron.
• Safe default: off (advice-only).
• Example: pgdba check --apply
• Try it: pgdba check --explain-flag apply

yes

–yes

Skips per-action confirmation for –apply (blanket approval). Requires –apply; refused without a TTY.

• When to use: Scripted maintenance windows with a reviewed plan.
• Safe default: off (per-action prompts).
• Example: pgdba check --yes
• Try it: pgdba check --explain-flag yes

dsn

–dsn

Full connection string, overriding profile and env resolution.

• When to use: One-off runs against a connection not worth a profile.
• Safe default: unset; DATABASE_URL / PGDBA_DATABASE_URL / config profile are tried instead.
• Example: pgdba check --dsn
• Try it: pgdba check --explain-flag dsn