pg_isready: Usage, Options & Common CI Errors
pg_isready reports whether a Postgres server is up and accepting connections.
pg_isready is the canonical "wait for the database" probe in CI. Its value is entirely in its exit codes, which let a shell loop block until the service container is ready.
What it does
pg_isready sends a connection probe to a PostgreSQL server and reports its status via exit code without running any query or needing valid credentials. It is built for readiness checks, not for querying data.
Common usage
pg_isready -h localhost -p 5432
pg_isready -h db -U postgres -d app
until pg_isready -h localhost -p 5432 -q; do sleep 1; done
pg_isready -h localhost -t 5 # 5-second connection timeoutOptions
| Flag | What it does |
|---|---|
| -h <host> | Server host |
| -p <port> | Server port (default 5432) |
| -d <db> | Database name (cosmetic for the probe) |
| -t <secs> | Connection timeout (0 = wait forever) |
| -q | Quiet; rely on exit code only |
Common errors in CI
The exit codes are the contract: 0 = accepting connections, 1 = server is rejecting connections (e.g. still starting up - "no response"), 2 = no response at all (host/port unreachable), 3 = no attempt was made (bad arguments). The standard wait loop is until pg_isready -h host -q; do sleep 1; done so migrations do not race a half-started container. pg_isready can return 0 before the database itself accepts logins, so a final psql -c "SELECT 1" is a stronger gate.