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
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
<!--
doc/src/sgml/ref/pg_isready.sgml
PostgreSQL documentation
-->
<refentry id="app-pg-isready">
<indexterm zone="app-pg-isready">
<primary>pg_isready</primary>
</indexterm>
<refmeta>
<refentrytitle><application>pg_isready</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>pg_isready</refname>
<refpurpose>check the connection status of a <productname>PostgreSQL</productname> server</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_isready</command>
<arg rep="repeat"><replaceable>connection-option</replaceable></arg>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id="app-pg-isready-description">
<title>Description</title>
<para>
<application>pg_isready</application> is a utility for checking the connection
status of a <productname>PostgreSQL</productname> database server. The exit
status specifies the result of the connection check.
</para>
</refsect1>
<refsect1 id="app-pg-isready-options">
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-d <replaceable class="parameter">dbname</replaceable></option></term>
<term><option>--dbname=<replaceable class="parameter">dbname</replaceable></option></term>
<listitem>
<para>
Specifies the name of the database to connect to. The
<replaceable>dbname</replaceable> can be a <link
linkend="libpq-connstring">connection string</link>. If so,
connection string parameters will override any conflicting command
line options.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-h <replaceable class="parameter">hostname</replaceable></option></term>
<term><option>--host=<replaceable class="parameter">hostname</replaceable></option></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p <replaceable class="parameter">port</replaceable></option></term>
<term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
<listitem>
<para>
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 <envar>PGPORT</envar>
environment variable or, if not set, to the port specified at
compile time, usually 5432.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-q</option></term>
<term><option>--quiet</option></term>
<listitem>
<para>
Do not display status message. This is useful when scripting.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-t <replaceable class="parameter">seconds</replaceable></option></term>
<term><option>--timeout=<replaceable class="parameter">seconds</replaceable></option></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-U <replaceable class="parameter">username</replaceable></option></term>
<term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
<listitem>
<para>
Connect to the database as the user <replaceable
class="parameter">username</replaceable> instead of the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-V</option></term>
<term><option>--version</option></term>
<listitem>
<para>
Print the <application>pg_isready</application> version and exit.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-?</option></term>
<term><option>--help</option></term>
<listitem>
<para>
Show help about <application>pg_isready</application> command line
arguments, and exit.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Exit Status</title>
<para>
<application>pg_isready</application> returns <literal>0</literal> to the shell if the server
is accepting connections normally, <literal>1</literal> if the server is rejecting
connections (for example during startup), <literal>2</literal> if there was no response to the
connection attempt, and <literal>3</literal> if no attempt was made (for example due to invalid
parameters).
</para>
</refsect1>
<refsect1>
<title>Environment</title>
<para>
<command>pg_isready</command>, like most other <productname>PostgreSQL</productname>
utilities,
also uses the environment variables supported by <application>libpq</application>
(see <xref linkend="libpq-envars"/>).
</para>
<para>
The environment variable <envar>PG_COLOR</envar> specifies whether to use
color in diagnostic messages. Possible values are
<literal>always</literal>, <literal>auto</literal> and
<literal>never</literal>.
</para>
</refsect1>
<refsect1 id="app-pg-isready-notes">
<title>Notes</title>
<para>
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.
</para>
</refsect1>
<refsect1 id="app-pg-isready-examples">
<title>Examples</title>
<para>
Standard Usage:
<screen>
<prompt>$</prompt> <userinput>pg_isready</userinput>
<computeroutput>/tmp:5432 - accepting connections</computeroutput>
<prompt>$</prompt> <userinput>echo $?</userinput>
<computeroutput>0</computeroutput>
</screen>
</para>
<para>
Running with connection parameters to a <productname>PostgreSQL</productname> cluster in startup:
<screen>
<prompt>$ </prompt><userinput>pg_isready -h localhost -p 5433</userinput>
<computeroutput>localhost:5433 - rejecting connections</computeroutput>
<prompt>$</prompt> <userinput>echo $?</userinput>
<computeroutput>1</computeroutput>
</screen>
</para>
<para>
Running with connection parameters to a non-responsive <productname>PostgreSQL</productname> cluster:
<screen>
<prompt>$ </prompt><userinput>pg_isready -h someremotehost</userinput>
<computeroutput>someremotehost:5432 - no response</computeroutput>
<prompt>$</prompt> <userinput>echo $?</userinput>
<computeroutput>2</computeroutput>
</screen>
</para>
</refsect1>
</refentry>
|
