pg_isready
Check PostgreSQL server connection status
TLDR
Check connection
Check connection with a specific hostname and port
Check connection displaying a message only when the connection fails
SYNOPSIS
pg_isready [options]
PARAMETERS
-d dbname
Specifies the database name to connect to. Defaults to the user name.-h hostname
Specifies the host name of the machine on which the server is running. If it begins with a slash, it is used as the directory for the Unix domain socket.-p port
Specifies the port number to which the server is listening.-q
Specifies quiet mode. Only the exit code will be returned.-t seconds
Specifies the maximum number of seconds to wait while trying to connect. The default is 3 seconds. Zero or negative values mean to wait forever.-U username
Specifies the user name to connect as. Defaults to the current operating system user name.-w
Do not issue a password prompt. The command will attempt to connect without a password.-W
Force pg_isready to prompt for a password before connecting to the database.-V
Prints the pg_isready version and exits.-?
Shows help about pg_isready command line arguments, and exits.
DESCRIPTION
The pg_isready
command is a utility for checking the connection status of a PostgreSQL server. It tests whether a PostgreSQL server is running and accepting connections. This is useful for scripting, monitoring, and ensuring that a database server is available before attempting to connect to it.
It attempts to connect to the specified PostgreSQL server. If the connection is successful, the command returns 0, indicating that the server is ready. If the connection fails or times out, it returns a non-zero exit code. It provides a simple and reliable way to determine the availability of a PostgreSQL server programmatically. The command provides options to customize the connection parameters, such as the host, port, username, and database to connect to.
CAVEATS
pg_isready
only checks the connection status. It does not verify database integrity or perform more complex server health checks. It also depends on the proper settings being correctly configured for the connection, such as `pg_hba.conf`.
EXIT CODES
The command returns the following exit codes:0
: The server is ready to accept connections.1
: The server is not ready to accept connections.2
: There was no response from the server.3
: There was no attempt to connect to the server.
HISTORY
pg_isready
was introduced as a utility to programmatically check PostgreSQL server readiness. It is included in standard PostgreSQL distributions. Its primary purpose is to simplify monitoring and automation tasks related to PostgreSQL deployments. The command has been updated and improved over the different PostgreSQL versions, but the core functionality has stayed same through the releases.