# pg_isready ## Name pg_isready -- check the connection status of a PostgreSQL server ## Synopsis `pg_isready` [`_connection-option_`...] [`_option_`...] ## Description pg_isready is a utility for checking the connection status of a PostgreSQL database server. The exit status specifies the result of the connection check. ## Options `-d` `_dbname_``--dbname=``_dbname_` Specifies the name of the database to connect to. If this parameter contains an `=` sign or starts with a valid URI prefix (`postgresql://` or `postgres://`), it is treated as a `conninfo` string. See [Section 31.1.1](#calibre_link-458) for more information. `-h` `_hostname_` `--host=``_hostname_` Specifies the host name of the machine on which the server is running. If the value begins with a slash, it is used as the directory for the Unix-domain socket. `-p` `_port_` `--port=``_port_` Specifies the TCP port or the local Unix-domain socket file extension on which the server is listening for connections. Defaults to the value of the `PGPORT` environment variable or, if not set, to the port specified at compile time, usually 5432. `-q` `--quiet` Do not display status message. This is useful when scripting. `-t` `_seconds_` `--timeout=``_seconds_` The maximum number of seconds to wait when attempting connection before returning that the server is not responding. Setting to 0 disables. The default is 3 seconds. `-U` `_username_` `--username=``_username_` Connect to the database as the user `_username_` instead of the default. `-V` `--version` Print the pg_isready version and exit. `-?` `--help` Show help about pg_isready command line arguments, and exit. ## Exit Status pg_isready returns `0` to the shell if the server is accepting connections normally, `1` if the server is rejecting connections (for example during startup), `2` if there was no response to the connection attempt, and `3` if no attempt was made (for example due to invalid parameters). ## Environment `pg_isready`, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see [Section 31.14](#calibre_link-39)). ## Notes The options `--dbname` and `--username` can be used to avoid gratuitous error messages in the logs, but are not necessary for proper functionality. ## Examples Standard Usage: ``` <samp class="literal">$</samp> <kbd class="literal">pg_isready</kbd> <samp class="literal">/tmp:5432 - accepting connections</samp> <samp class="literal">$</samp> <kbd class="literal">echo $?</kbd> <samp class="literal">0</samp> ``` Running with connection parameters to a PostgreSQL cluster in startup: ``` <samp class="literal">$</samp> <kbd class="literal">pg_isready -h localhost -p 5433</kbd> <samp class="literal">localhost:5433 - rejecting connections</samp> <samp class="literal">$</samp> <kbd class="literal">echo $?</kbd> <samp class="literal">1</samp> ``` Running with connection parameters to a non-responsive PostgreSQL cluster: ``` <samp class="literal">$</samp> <kbd class="literal">pg_isready -h someremotehost</kbd> <samp class="literal">someremotehost:5432 - no response</samp> <samp class="literal">$</samp> <kbd class="literal">echo $?</kbd> <samp class="literal">2</samp> ```