Check PostgreSQL Readiness with pg_isready

You will use pg_isready to tell whether a PostgreSQL server is accepting connections, still starting, not responding, or was not checked because the command line was invalid. Allow about five minutes for a local check, or ten minutes if you need to confirm a remote host, socket directory or service health check.

This guide describes the PostgreSQL 16.15 client installed on this machine. The command is a probe: it does not create a database, change server configuration or start a service. The examples are ordinary user commands. They do not need sudo.

1. Confirm the installed client

First check that the command you will run is the expected binary and record its version. The Debian package on this machine is postgresql-client-16, version 16.15-0ubuntu0.24.04.1.

$ command -v pg_isready
/usr/bin/pg_isready
$ pg_isready --version
pg_isready (PostgreSQL) 16.15 (Ubuntu 16.15-0ubuntu0.24.04.1)

The version matters when a script depends on option details or diagnostic wording. The exit status meanings used below are documented by PostgreSQL 16 and are also present in the installed manual page.

2. Run the default local check

With no connection options, pg_isready uses libpq defaults. For the local Unix socket, the output commonly names the socket directory and the default port. The port comes from PGPORT when it is set; otherwise it is normally 5432.

$ pg_isready
/tmp:5432 - accepting connections
$ printf 'exit status: %s\n' "$?"
exit status: 0

Your socket directory, port and result can differ. A status of 0 means the server answered as ready to accept connections. It does not prove that a particular application role can log in or that its target database exists.

3. Select a TCP host and port explicitly

Use -h and -p when you need to test a specific listener rather than the local socket. This avoids a common distraction: a healthy local socket can hide a broken TCP listener, and a TCP check can fail even while the local socket works.

$ pg_isready -h 127.0.0.1 -p 5432
127.0.0.1:5432 - accepting connections
$ printf 'exit status: %s\n' "$?"
exit status: 0

Replace 127.0.0.1 and 5432 with values from the service configuration. A host value beginning with a slash is treated as a Unix-domain socket directory, so this is also valid when you need to avoid the default socket location:

$ pg_isready -h /run/postgresql -p 5432
/run/postgresql:5432 - accepting connections

Do not infer that a refused TCP check means PostgreSQL is down until you have checked the host and port. A firewall, container network, bind address or wrong port can produce the same operational symptom.

4. Read the four exit statuses

For automation, inspect $? immediately after the probe. Do not use the text alone: status messages can be suppressed, coloured or changed slightly between releases.

For example, this deliberately probes an unused local port without changing anything on the host:

$ pg_isready -h 127.0.0.1 -p 1
127.0.0.1:1 - no response
$ printf 'exit status: %s\n' "$?"
exit status: 2

For a deliberately invalid option, status 3 indicates a command-line problem rather than a PostgreSQL server state:

$ pg_isready --definitely-not-an-option
/usr/lib/postgresql/16/bin/pg_isready: unrecognized option '--definitely-not-an-option'
pg_isready: hint: Try "pg_isready --help" for more information.
$ printf 'exit status: %s\n' "$?"
exit status: 3

5. Make a script-safe readiness check

Use --quiet when another program only needs the exit status. The check below prints its own result and returns the same status to the shell. The if form is useful because it tests the command without losing its status to an unrelated command.

$ if pg_isready --quiet -h 127.0.0.1 -p 5432; then
>     printf 'PostgreSQL is ready\n'
> else
>     status=$?
>     printf 'PostgreSQL is not ready, pg_isready status %s\n' "$status"
> fi
PostgreSQL is ready

Keep the four statuses distinct if the next action differs. A service may reasonably retry status 1 while it starts, report status 2 as a network or availability fault, and stop immediately on status 3 because retrying bad arguments will not help.

6. Bound the wait and choose connection identity

The default timeout is three seconds. Set it explicitly for a health check whose timing is part of its contract. -t 0 disables the timeout, which can leave a monitoring process waiting indefinitely, so use that only when an unbounded wait is intentional.

$ pg_isready -h db.example.test -p 5432 -t 5
db.example.test:5432 - accepting connections

You can supply a database name with -d and a user with -U. These values are not required merely to learn whether the server is ready:

$ pg_isready -h db.example.test -p 5432 -U app_user -d appdb
db.example.test:5432 - accepting connections

The server can log a failed connection attempt if you provide incorrect user, password or database details. Do not put a password on the command line. If a real authentication test is required, use your normal libpq password handling and treat the credentials as sensitive. A readiness probe is not a substitute for an application login test.

7. Diagnose a failing check without changing service state

Start with the exact endpoint and environment used by the failing process. Check whether PGHOST, PGPORT, PGUSER or another libpq variable is redirecting an apparently simple command:

$ env | grep '^PG_' || true
$ printf 'host=%s port=%s\n' "${PGHOST:-<unset>}" "${PGPORT:-<unset>}"
$ pg_isready -h 127.0.0.1 -p 5432 -t 3
127.0.0.1:5432 - no response

Next compare the probe with the service's own listening information and logs. Those checks depend on how PostgreSQL was installed, so do not assume a systemd unit name or use elevated privileges blindly. If you administer the host, an appropriate service-status command may require sudo; pg_isready itself does not.

Do not restart PostgreSQL just because the probe returned status 1 or 2. Restarting can interrupt active clients and destroys useful evidence. First confirm the endpoint, wait for a startup operation to finish, and inspect logs. There is nothing to undo from the commands in this guide because they only read status.