pg_isready

Check connection

$ pg_isready

$ pg_isready [[-h|--host]] [hostname] [[-p|--port]] [port]

$ pg_isready [[-q|--quiet]]

pg_isready [OPTION...] [HOSTNAME:PORT [DBNAME]]

-d DBNAME, --dbname=DBNAME
    Database name for connection (default: postgres)

-h HOSTNAME, --host=HOSTNAME
    Server host (default: localhost)

-p PORT, --port=PORT
    TCP port or socket extension (default: 5432)

-q, --quiet
    Suppress status message output

-t TIMEOUT, --timeout=TIMEOUT
    Max seconds to wait for connection

-V, --version
    Print version and exit

-?, --help
    Show help and exit

pg_isready is a utility from the PostgreSQL suite that tests whether a PostgreSQL server is accepting connections.

It attempts to connect to the specified host and port (or defaults), and reports the server's status: /tmp: accepting connections, no response, or rejected. This is particularly useful in scripts or deployment automation to wait for the database server to become available after startup.

By default, it targets localhost on the standard PostgreSQL port (5432) and the 'postgres' database. Environment variables like PGHOST, PGPORT, and PGDATABASE influence defaults.

Key features include timeout control to prevent indefinite hangs and quiet mode for scripting. Exit status provides programmatic feedback: 0 for accepting, 1 for rejected (e.g., maintenance mode), 2 for no response, and 3 for timeout or fatal error.

Unlike psql, it doesn't require a full session or authentication, making it lightweight for readiness checks. However, it only verifies basic TCP connection acceptance, not database health, user permissions, or query execution.

Only checks connection acceptance, not full DB functionality or auth. Unix sockets require matching user/group permissions.

0: accepting connections
1: rejected
2: no response
3: timeout or fatal error

accepting connections (ready)
no response (unreachable)
rejected (e.g., shutdown mode)

Introduced in PostgreSQL 9.3 (2013) to simplify server readiness polling in init scripts.

psql(1), pg_ctl(1), postgres(1)