LinuxCommandLibrary

pg_isready

Check PostgreSQL server connection status

TLDR

Check connection

$ pg_isready
copy

Check connection with a specific hostname and port
$ pg_isready [[-h|--host]] [hostname] [[-p|--port]] [port]
copy

Check connection displaying a message only when the connection fails
$ pg_isready [[-q|--quiet]]
copy

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.

SEE ALSO

psql(1), pg_ctl(1)

Copied to clipboard