Installation

Install pgdba with uv in one line — Python 3.9+, any PostgreSQL 13–17.

Requirements

Python 3.9+ and uv.
A PostgreSQL 13–17 database — local, Docker, or managed (RDS, Cloud SQL). Anything else exits 3 at the version gate.

Install

uv tool install pgdba
pgdba --help

That’s the whole install. To hack on pgdba itself instead, clone the repo and uv sync — contributors should read the repo’s tests/README.md next, not this page.

Verify it works

pgdba config init        # probes your connection, writes pgdba-run.toml (chmod 600)
pgdba check              # read-only check, zero flags

config init asks for host, port, database, user, and password (hidden), probes the connection read-only before writing anything, and refuses to overwrite an existing config without --force. Non-interactive (CI/scripts):

pgdba config init --host prod-db.corp --port 5432 --dbname app \
  --user pgdba --password "$PGDBA_PASSWORD" --name prod

Tip

Running the test suite locally? It needs its own disposable database, never a shared instance:

docker compose -f devdb/compose.yaml up -d pg-test
pgdba config init --host localhost --port 5436 --dbname postgres \
  --user postgres --password postgres

Where to next

Run the guided tour: your first check
Zero-flag runs via profiles: connection profiles