Postgres Health Check (Free)

One read-only command that checks a PostgreSQL database for the problems that cause outages and slowdowns, and tells you what to do about each.

pip install -r requirements.txt
python3 health_check.py --dsn postgresql://reader@localhost:5432/mydb
python3 health_check.py --md > health.md            # Markdown report (paste into a ticket)
python3 health_check.py --json                      # for scripts and dashboards
python3 health_check.py --fail-on critical          # exit 1 in CI / cron when something critical is found
python3 health_check.py --schema app                # only objects in one schema

No --dsn? It uses $DATABASE_URL or the usual libpq variables (PGHOST, PGUSER, PGDATABASE, PGPASSWORD). Passwords are redacted in every report.

Every check runs in a READ ONLY transaction with a statement timeout. A check the user can't run (permissions, managed services) is listed as skipped instead of failing the report. A read-only role is enough; pg_monitor membership shows other users' queries.

./demo.sh plants one of each problem in schema demo_health of a scratch database (PGHC_DEMO_DSN) and checks it. ./run_tests.sh runs the unit tests anywhere, and the live tests when PGHC_TEST_DSN (and optionally PGHC_TEST_DSN14) point at scratch databases.

Tested against PostgreSQL 18.6 and 14.24 with Python 3.13 and 3.10: every planted problem found with the right severity, severity sorting, --fail-on exit codes, Markdown and JSON output, password redaction, and connection errors (exit 2).

• Statistics count since the last stats reset or restart; on a fresh server "unused" means little. Check replicas separately: an index unused on the primary may serve replica reads.
• It reports; it never changes anything. Drop or rebuild indexes yourself, preferably CONCURRENTLY.
• No table/index bloat estimate (those queries are estimates and often wrong); dead-row counts are used instead.