Connection profiles (pgdba-run.toml)

pgdba check and pgdba migrate read an optional TOML run-config file with named connection profiles so recurring and multi-environment runs need zero flags. Discovery order: --config PATH → PGDBA_CONFIG env → ./pgdba-run.toml.

# pgdba-run.toml
default = "prod"

[options]
log_format = "json"

[connections.prod]
dsn = "postgresql://user:password@prod-db.corp:5432/app"

[connections.staging]
dsn_env = "STAGING_DATABASE_URL"   # credentials stay out of the file

pgdba check                                        # prod (default)
pgdba check --connection staging                   # staging, zero DSNs retyped
pgdba migrate --source-name prod --target-name staging

Keys

• Profile keys: dsn, dsn_env, statement_timeout, connect_timeout, pooled, direct_dsn. Top-level keys: the run options plus default.
• Every value applies as flag > env > file > default — a flag or environment variable always beats the file, so DATABASE_URL-style CI overrides keep working.
• Unknown keys anywhere exit 3 before any connection (typos included — and with a did you mean: suggestion).
• pooled = true marks a target behind a transaction pooler (PgBouncer): the safety contract is enforced with transaction-scoped SET LOCAL instead of session SETs. DDL (--apply, migrate) refuses a pooled profile without direct_dsn (exit 3) and otherwise runs over the direct bypass.
• dsn_env names an environment variable holding the DSN. A credential-bearing profile in a group/world-readable file triggers a loud chmod 600 warning.
• When a file is loaded, the run log records config: <path> (N keys, connection: <name>) and pgdba-report.json gains a config field ({"path", "keys", "connection"}; null when no file used).

Diagnose the file

pgdba config doctor          # validate + probe every profile
pgdba config doctor --json   # CI-friendly

Doctor is strictly diagnostic: exit 0 valid and every profile connects, 1 a probe failed, 3 validation failed or the file is missing. See the full doctor guide for the migrate flow.