1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
'\" t
.\" Title: pg_isready
.\" Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\" Date: 2024
.\" Manual: PostgreSQL 16.2 Documentation
.\" Source: PostgreSQL 16.2
.\" Language: English
.\"
.TH "PG_ISREADY" "1" "2024" "PostgreSQL 16.2" "PostgreSQL 16.2 Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pg_isready \- check the connection status of a PostgreSQL server
.SH "SYNOPSIS"
.HP \w'\fBpg_isready\fR\ 'u
\fBpg_isready\fR [\fIconnection\-option\fR...] [\fIoption\fR...]
.SH "DESCRIPTION"
.PP
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\&.
.SH "OPTIONS"
.PP
\fB\-d \fR\fB\fIdbname\fR\fR
.br
\fB\-\-dbname=\fR\fB\fIdbname\fR\fR
.RS 4
Specifies the name of the database to connect to\&. The
\fIdbname\fR
can be a
connection string\&. If so, connection string parameters will override any conflicting command line options\&.
.RE
.PP
\fB\-h \fR\fB\fIhostname\fR\fR
.br
\fB\-\-host=\fR\fB\fIhostname\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-p \fR\fB\fIport\fR\fR
.br
\fB\-\-port=\fR\fB\fIport\fR\fR
.RS 4
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
\fBPGPORT\fR
environment variable or, if not set, to the port specified at compile time, usually 5432\&.
.RE
.PP
\fB\-q\fR
.br
\fB\-\-quiet\fR
.RS 4
Do not display status message\&. This is useful when scripting\&.
.RE
.PP
\fB\-t \fR\fB\fIseconds\fR\fR
.br
\fB\-\-timeout=\fR\fB\fIseconds\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-U \fR\fB\fIusername\fR\fR
.br
\fB\-\-username=\fR\fB\fIusername\fR\fR
.RS 4
Connect to the database as the user
\fIusername\fR
instead of the default\&.
.RE
.PP
\fB\-V\fR
.br
\fB\-\-version\fR
.RS 4
Print the
pg_isready
version and exit\&.
.RE
.PP
\fB\-?\fR
.br
\fB\-\-help\fR
.RS 4
Show help about
pg_isready
command line arguments, and exit\&.
.RE
.SH "EXIT STATUS"
.PP
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)\&.
.SH "ENVIRONMENT"
.PP
\fBpg_isready\fR, like most other
PostgreSQL
utilities, also uses the environment variables supported by
libpq
(see
Section\ \&34.15)\&.
.PP
The environment variable
\fBPG_COLOR\fR
specifies whether to use color in diagnostic messages\&. Possible values are
always,
auto
and
never\&.
.SH "NOTES"
.PP
It is not necessary to supply correct user name, password, or database name values to obtain the server status; however, if incorrect values are provided, the server will log a failed connection attempt\&.
.SH "EXAMPLES"
.PP
Standard Usage:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBpg_isready\fR
/tmp:5432 \- accepting connections
$ \fBecho $?\fR
0
.fi
.if n \{\
.RE
.\}
.PP
Running with connection parameters to a
PostgreSQL
cluster in startup:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBpg_isready \-h localhost \-p 5433\fR
localhost:5433 \- rejecting connections
$ \fBecho $?\fR
1
.fi
.if n \{\
.RE
.\}
.PP
Running with connection parameters to a non\-responsive
PostgreSQL
cluster:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBpg_isready \-h someremotehost\fR
someremotehost:5432 \- no response
$ \fBecho $?\fR
2
.fi
.if n \{\
.RE
.\}
.sp
|
