1PG_ISREADY(1)            PostgreSQL 16.1 Documentation           PG_ISREADY(1)
2
3
4

NAME

6       pg_isready - check the connection status of a PostgreSQL server
7

SYNOPSIS

9       pg_isready [connection-option...] [option...]
10

DESCRIPTION

12       pg_isready is a utility for checking the connection status of a
13       PostgreSQL database server. The exit status specifies the result of the
14       connection check.
15

OPTIONS

17       -d dbname
18       --dbname=dbname
19           Specifies the name of the database to connect to. The dbname can be
20           a connection string. If so, connection string parameters will
21           override any conflicting command line options.
22
23       -h hostname
24       --host=hostname
25           Specifies the host name of the machine on which the server is
26           running. If the value begins with a slash, it is used as the
27           directory for the Unix-domain socket.
28
29       -p port
30       --port=port
31           Specifies the TCP port or the local Unix-domain socket file
32           extension on which the server is listening for connections.
33           Defaults to the value of the PGPORT environment variable or, if not
34           set, to the port specified at compile time, usually 5432.
35
36       -q
37       --quiet
38           Do not display status message. This is useful when scripting.
39
40       -t seconds
41       --timeout=seconds
42           The maximum number of seconds to wait when attempting connection
43           before returning that the server is not responding. Setting to 0
44           disables. The default is 3 seconds.
45
46       -U username
47       --username=username
48           Connect to the database as the user username instead of the
49           default.
50
51       -V
52       --version
53           Print the pg_isready version and exit.
54
55       -?
56       --help
57           Show help about pg_isready command line arguments, and exit.
58

EXIT STATUS

60       pg_isready returns 0 to the shell if the server is accepting
61       connections normally, 1 if the server is rejecting connections (for
62       example during startup), 2 if there was no response to the connection
63       attempt, and 3 if no attempt was made (for example due to invalid
64       parameters).
65

ENVIRONMENT

67       pg_isready, like most other PostgreSQL utilities, also uses the
68       environment variables supported by libpq (see Section 34.15).
69
70       The environment variable PG_COLOR specifies whether to use color in
71       diagnostic messages. Possible values are always, auto and never.
72

NOTES

74       It is not necessary to supply correct user name, password, or database
75       name values to obtain the server status; however, if incorrect values
76       are provided, the server will log a failed connection attempt.
77

EXAMPLES

79       Standard Usage:
80
81           $ pg_isready
82           /tmp:5432 - accepting connections
83           $ echo $?
84           0
85
86       Running with connection parameters to a PostgreSQL cluster in startup:
87
88           $ pg_isready -h localhost -p 5433
89           localhost:5433 - rejecting connections
90           $ echo $?
91           1
92
93       Running with connection parameters to a non-responsive PostgreSQL
94       cluster:
95
96           $ pg_isready -h someremotehost
97           someremotehost:5432 - no response
98           $ echo $?
99           2
100
101
102
103
104
105PostgreSQL 16.1                      2023                        PG_ISREADY(1)