Skip to content

pg_isready

Checks whether a PostgreSQL server accepts connections and reports it as an exit code: ideal for scripts and monitoring.

pg_isready output

Syntax

pg_isready [-h HOST] [-p PORT] [-d DB] [-U USER] [-t SECONDS] [-q]

Options

Option Description
-h HOST, -p PORT Server and port, default local socket and 5432
-d DB, -U USER Database and role for the check (only used in the log)
-t SECONDS Timeout, default 3
-q No output, only the exit code

Exit codes: 0 accepting connections, 1 rejecting (e.g. while starting), 2 no response, 3 no attempt (wrong parameters). pg_isready doesn't log in, so it needs no password.

Examples

Is the local server ready:

pg_isready
/var/run/postgresql:5432 - accepting connections

Check a server over the network:

pg_isready -h 192.0.2.22 -p 5432
192.0.2.22:5432 - accepting connections

The server is stopped:

pg_isready; echo $?
/var/run/postgresql:5432 - no response
2

Silent, for scripts:

pg_isready -q && echo ok || echo down
ok

When do I need it?

  • In scripts that must wait until the database is up, e.g. after a restart
  • As a health check in Docker Compose or a monitoring system
  • To check quickly from an application server whether the database is reachable

Wait for the database

until pg_isready -q -h db01; do sleep 1; done waits in a deploy script until the database accepts connections, and only then starts the migration.

Distribution differences

Debian Ubuntu RHEL Arch
Package postgresql-client postgresql-client postgresql postgresql-libs

psql · pg_lsclusters · systemctl · docker compose