pg_isready is a core utility which checks the connection status of a PostgreSQL server.
pg_isready was added in PostgreSQL 9.3 .
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).
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.
pg_isready has not been substantially modified since it was introduced in PostgreSQL 9.3.
Basic usage example for
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
2022-09-02 10:02:25.015 UTC  LOG: connection received: host=127.0.0.1 port=36628 2022-09-02 10:02:25.015 UTC  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  LOG: connection authorized: user=nosuchuser database=nosuchdb application_name=pg_isready 2022-09-01 10:12:18.711 UTC  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