pg_isready

A core utility which checks the connection status of a PostgreSQL server

pg_isready is a core utility which checks the connection status of a PostgreSQL server.

pg_isready was added in PostgreSQL 9.3 .

Usage

pg_isready uses the provided connection details to initiate a server connection, and determine the server status from the server's response (or lack thereof).

Note that pg_isready never actually connects to the database and does not require a valid database, user or password to be provided to check the server's response. However the server will log the validity of the connection attempt.

Change history

pg_isready has not been substantially modified since it was introduced in PostgreSQL 9.3.

Examples

Basic usage example for pg_isready:

postgres $ pg_isready -d 'user=postgres dbname=postgres host=localhost port=5432'
localhost:5432 - accepting connections
postgres $ echo $?
0

The log file will contain an entry like the following (assuming log_connections is set to on):

2022-09-02 10:02:25.015 UTC [31325] LOG:  connection received: host=127.0.0.1 port=36628
2022-09-02 10:02:25.015 UTC [31325] LOG:  connection authorized: user=postgres database=postgres application_name=pg_isready

Attempting to connect to a server with an invalid username and/or database name:

postgres $ pg_isready -d 'user=nosuchuser dbname=nosuchdb host=localhost port=5432'
localhost:5432 - accepting connections
postgres $ echo $?
0

The log file will contain an entry like the following:

2022-09-01 10:12:18.711 UTC [32711] LOG:  connection authorized: user=nosuchuser database=nosuchdb application_name=pg_isready
2022-09-01 10:12:18.711 UTC [32711] FATAL:  role "nosuchuser" does not exist

Attempting to connect to a port where a server is not currently running:

postgres $ pg_isready -d 'user=postgres dbname=postgres host=localhost port=9999'
localhost:9999 - no response
postgres $ echo $?
2

Categories

Core utility, Database connections, Monitoring