Debian Codegraph @

doc/src/sgml/ref/pg_isready.sgml

raw
1 <!--
2 doc/src/sgml/ref/pg_isready.sgml
3 PostgreSQL documentation
4 -->
5
6 <refentry id="app-pg-isready">
7 <indexterm zone="app-pg-isready">
8 <primary>pg_isready</primary>
9 </indexterm>
10
11 <refmeta>
12 <refentrytitle><application>pg_isready</application></refentrytitle>
13 <manvolnum>1</manvolnum>
14 <refmiscinfo>Application</refmiscinfo>
15 </refmeta>
16
17 <refnamediv>
18 <refname>pg_isready</refname>
19 <refpurpose>check the connection status of a <productname>PostgreSQL</productname> server</refpurpose>
20 </refnamediv>
21
22 <refsynopsisdiv>
23 <cmdsynopsis>
24 <command>pg_isready</command>
25 <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
26 <arg rep="repeat"><replaceable>option</replaceable></arg>
27 </cmdsynopsis>
28 </refsynopsisdiv>
29
30
31 <refsect1 id="app-pg-isready-description">
32 <title>Description</title>
33 <para>
34 <application>pg_isready</application> is a utility for checking the connection
35 status of a <productname>PostgreSQL</productname> database server. The exit
36 status specifies the result of the connection check.
37 </para>
38 </refsect1>
39
40 <refsect1 id="app-pg-isready-options">
41 <title>Options</title>
42
43 <variablelist>
44
45 <varlistentry>
46 <term><option>-d <replaceable class="parameter">dbname</replaceable></option></term>
47 <term><option>--dbname=<replaceable class="parameter">dbname</replaceable></option></term>
48 <listitem>
49 <para>
50 Specifies the name of the database to connect to. The
51 <replaceable>dbname</replaceable> can be a <link
52 linkend="libpq-connstring">connection string</link>. If so,
53 connection string parameters will override any conflicting command
54 line options.
55 </para>
56 </listitem>
57 </varlistentry>
58
59 <varlistentry>
60 <term><option>-h <replaceable class="parameter">hostname</replaceable></option></term>
61 <term><option>--host=<replaceable class="parameter">hostname</replaceable></option></term>
62 <listitem>
63 <para>
64 Specifies the host name of the machine on which the
65 server is running. If the value begins
66 with a slash, it is used as the directory for the Unix-domain
67 socket.
68 </para>
69 </listitem>
70 </varlistentry>
71
72 <varlistentry>
73 <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
74 <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
75 <listitem>
76 <para>
77 Specifies the TCP port or the local Unix-domain
78 socket file extension on which the server is listening for
79 connections. Defaults to the value of the <envar>PGPORT</envar>
80 environment variable or, if not set, to the port specified at
81 compile time, usually 5432.
82 </para>
83 </listitem>
84 </varlistentry>
85
86 <varlistentry>
87 <term><option>-q</option></term>
88 <term><option>--quiet</option></term>
89 <listitem>
90 <para>
91 Do not display status message. This is useful when scripting.
92 </para>
93 </listitem>
94 </varlistentry>
95
96 <varlistentry>
97 <term><option>-t <replaceable class="parameter">seconds</replaceable></option></term>
98 <term><option>--timeout=<replaceable class="parameter">seconds</replaceable></option></term>
99 <listitem>
100 <para>
101 The maximum number of seconds to wait when attempting connection before
102 returning that the server is not responding. Setting to 0 disables. The
103 default is 3 seconds.
104 </para>
105 </listitem>
106 </varlistentry>
107
108 <varlistentry>
109 <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
110 <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
111 <listitem>
112 <para>
113 Connect to the database as the user <replaceable
114 class="parameter">username</replaceable> instead of the default.
115 </para>
116 </listitem>
117 </varlistentry>
118
119 <varlistentry>
120 <term><option>-V</option></term>
121 <term><option>--version</option></term>
122 <listitem>
123 <para>
124 Print the <application>pg_isready</application> version and exit.
125 </para>
126 </listitem>
127 </varlistentry>
128
129 <varlistentry>
130 <term><option>-?</option></term>
131 <term><option>--help</option></term>
132 <listitem>
133 <para>
134 Show help about <application>pg_isready</application> command line
135 arguments, and exit.
136 </para>
137 </listitem>
138 </varlistentry>
139 </variablelist>
140 </refsect1>
141
142 <refsect1>
143 <title>Exit Status</title>
144
145 <para>
146 <application>pg_isready</application> returns <literal>0</literal> to the shell if the server
147 is accepting connections normally, <literal>1</literal> if the server is rejecting
148 connections (for example during startup), <literal>2</literal> if there was no response to the
149 connection attempt, and <literal>3</literal> if no attempt was made (for example due to invalid
150 parameters).
151 </para>
152 </refsect1>
153
154 <refsect1>
155 <title>Environment</title>
156
157 <para>
158 <command>pg_isready</command>, like most other <productname>PostgreSQL</productname>
159 utilities,
160 also uses the environment variables supported by <application>libpq</application>
161 (see <xref linkend="libpq-envars"/>).
162 </para>
163
164 <para>
165 The environment variable <envar>PG_COLOR</envar> specifies whether to use
166 color in diagnostic messages. Possible values are
167 <literal>always</literal>, <literal>auto</literal> and
168 <literal>never</literal>.
169 </para>
170 </refsect1>
171
172 <refsect1 id="app-pg-isready-notes">
173 <title>Notes</title>
174
175 <para>
176 It is not necessary to supply correct user name, password, or database
177 name values to obtain the server status; however, if incorrect values
178 are provided, the server will log a failed connection attempt.
179 </para>
180 </refsect1>
181
182 <refsect1 id="app-pg-isready-examples">
183 <title>Examples</title>
184
185 <para>
186 Standard Usage:
187 <screen>
188 <prompt>$</prompt> <userinput>pg_isready</userinput>
189 <computeroutput>/tmp:5432 - accepting connections</computeroutput>
190 <prompt>$</prompt> <userinput>echo $?</userinput>
191 <computeroutput>0</computeroutput>
192 </screen>
193 </para>
194
195 <para>
196 Running with connection parameters to a <productname>PostgreSQL</productname> cluster in startup:
197 <screen>
198 <prompt>$ </prompt><userinput>pg_isready -h localhost -p 5433</userinput>
199 <computeroutput>localhost:5433 - rejecting connections</computeroutput>
200 <prompt>$</prompt> <userinput>echo $?</userinput>
201 <computeroutput>1</computeroutput>
202 </screen>
203 </para>
204
205 <para>
206 Running with connection parameters to a non-responsive <productname>PostgreSQL</productname> cluster:
207 <screen>
208 <prompt>$ </prompt><userinput>pg_isready -h someremotehost</userinput>
209 <computeroutput>someremotehost:5432 - no response</computeroutput>
210 <prompt>$</prompt> <userinput>echo $?</userinput>
211 <computeroutput>2</computeroutput>
212 </screen>
213 </para>
214
215 </refsect1>
216
217 </refentry>