pg_isready Command Reference: Flags, Exit Codes & CI Examples

pg_isready reports whether a PostgreSQL server is accepting connections.

pg_isready sends a lightweight connection probe and reports status purely through its exit code, without running a query or needing valid credentials. It is the canonical readiness probe in CI.

Common flags and usage

• -h <host> / -p <port>: server host and port
• -d <db>: database name (cosmetic for the probe)
• -t <secs>: connection timeout (0 waits forever)
• -q: quiet; rely on the exit code only
• Exit codes: 0 accepting, 1 rejecting, 2 no response, 3 bad args

Example

until pg_isready -h localhost -p 5432 -q; do
  echo "waiting for postgres..."; sleep 1
done
psql "${DATABASE_URL}" -c 'SELECT 1'

In CI

Use the until-loop above to wait for a database service before migrations run, so a job does not race a half-started container. pg_isready can return 0 just before the server accepts logins, so a final psql -c "SELECT 1" is a stronger gate.

Key takeaways

• pg_isready signals readiness through exit codes, not query output.
• The standard CI gate is an until-loop on pg_isready -q.
• Follow it with a real SELECT for a stricter readiness check.

Related guides