pg_isready

Check connection

$ pg_isready

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

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

pg_isready [-d] [-h host] [-p port] [-q] [-t timeout] [-U username]

-d
    Show debugging output. This provides more verbose information about the connection attempt.

-h host
    Specifies the host name or IP address of the database server to connect to. Defaults to the PGHOST environment variable or 'localhost'.

-p port
    Specifies the TCP port number on which the database server is listening. Defaults to the PGPORT environment variable or '5432'.

-q
    Quiet mode. Suppresses any output from pg_isready, returning only an exit status code.

-t timeout
    Specifies the maximum number of seconds to wait for a connection attempt. If the connection is not established within this time, pg_isready returns an exit status of 2. Defaults to 3 seconds.

-U username
    Specifies the database user name to connect as. Defaults to the PGUSER environment variable or the current operating system user.

pg_isready is a lightweight utility designed to check the connection status of a PostgreSQL server. It attempts to establish a connection to a specified PostgreSQL instance and reports whether the server is accepting connections, rejecting them, or if the connection attempt failed due to a timeout or other unresolvable errors. This command is particularly useful for scripting, monitoring systems, and startup scripts, allowing automated processes to verify server availability before proceeding. It provides clear exit codes, making it easy to integrate into shell scripts for conditional execution. Users can specify the target host, port, username, and a connection timeout.

pg_isready only checks if the PostgreSQL server is reachable and accepting connections. It does not verify if the database itself is fully operational, if specific databases exist, or if the user has privileges for any particular operation. A successful connection status (exit code 0) only indicates network reachability and that the server's PostgreSQL service is running and configured to accept connections on the specified address and port. It does not validate the integrity or health of the database contents.

pg_isready returns specific exit codes to indicate the server's status:

• 0: The server is accepting connections.
• 1: The server is rejecting connections. This might be due to configuration (e.g., pg_hba.conf rules, or max_connections limit).
• 2: A connection attempt timed out or an unresolvable error occurred (e.g., host not found, network unreachable, server not running).

pg_isready respects the following environment variables for default connection parameters, which can be overridden by command-line options:

• PGHOST: Default host.
• PGPORT: Default port.
• PGUSER: Default user.

The pg_isready utility was introduced in PostgreSQL to provide a standardized, script-friendly way to check the server's availability. Prior to its existence, users often relied on more complex methods, such as attempting a connection with psql and parsing its output, or using generic network tools like netcat. pg_isready simplifies this task by offering distinct exit codes for various connection states, thereby streamlining monitoring and automation scripts for PostgreSQL administrators and developers.

psql(1), pg_ctl(1), pg_dump(1)