Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit ac2e967

Browse files
robertmhaasrobertmhaas
committed
pg_isready
New command-line utility to test whether a server is ready to accept connections. Phil Sorber, reviewed by Michael Paquier and Peter Eisentraut
1 parent 0ac5ad5 commit ac2e967

File tree

7 files changed

+413
-1
lines changed

7 files changed

+413
-1
lines changed

‎doc/src/sgml/ref/allfiles.sgml

+1
Original file line numberDiff line numberDiff line change
@@ -175,6 +175,7 @@ Complete list of usable sgml source files in this directory.
175175
<!ENTITY pgCtl SYSTEM "pg_ctl-ref.sgml">
176176
<!ENTITY pgDump SYSTEM "pg_dump.sgml">
177177
<!ENTITY pgDumpall SYSTEM "pg_dumpall.sgml">
178+
<!ENTITY pgIsready SYSTEM "pg_isready.sgml">
178179
<!ENTITY pgReceivexlog SYSTEM "pg_receivexlog.sgml">
179180
<!ENTITY pgResetxlog SYSTEM "pg_resetxlog.sgml">
180181
<!ENTITY pgRestore SYSTEM "pg_restore.sgml">

‎doc/src/sgml/ref/pg_isready.sgml

+200
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
<!--
2+
doc/src/sgml/ref/pg_isready.sgml
3+
PostgreSQL documentation
4+
-->
5+
6+
<refentry id="app-pg-isready">
7+
<refmeta>
8+
<refentrytitle><application>pg_isready</application></refentrytitle>
9+
<manvolnum>1</manvolnum>
10+
<refmiscinfo>Application</refmiscinfo>
11+
</refmeta>
12+
13+
<refnamediv>
14+
<refname>pg_isready</refname>
15+
<refpurpose>checks the connection status of a <productname>PostgreSQL</productname> server</refpurpose>
16+
</refnamediv>
17+
18+
<indexterm zone="app-pg-isready">
19+
<primary>pg_isready</primary>
20+
</indexterm>
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></></term>
47+
<term><option>--dbname=<replaceable class="parameter">dbname</replaceable></></term>
48+
<listitem>
49+
<para>
50+
Specifies the name of the database to connect to.
51+
</para>
52+
<para>
53+
If this parameter contains an <symbol>=</symbol> sign or starts
54+
with a valid <acronym>URI</acronym> prefix
55+
(<literal>postgresql://</literal>
56+
or <literal>postgres://</literal>), it is treated as a
57+
<parameter>conninfo</parameter> string. See <xref linkend="libpq-connect"> for more information.
58+
</para>
59+
</listitem>
60+
</varlistentry>
61+
62+
<varlistentry>
63+
<term><option>-h <replaceable class="parameter">hostname</replaceable></></term>
64+
<term><option>--host=<replaceable class="parameter">hostname</replaceable></></term>
65+
<listitem>
66+
<para>
67+
Specifies the host name of the machine on which the
68+
server is running. If the value begins
69+
with a slash, it is used as the directory for the Unix-domain
70+
socket.
71+
</para>
72+
</listitem>
73+
</varlistentry>
74+
75+
<varlistentry>
76+
<term><option>-p <replaceable class="parameter">port</replaceable></></term>
77+
<term><option>--port=<replaceable class="parameter">port</replaceable></></term>
78+
<listitem>
79+
<para>
80+
Specifies the TCP port or the local Unix-domain
81+
socket file extension on which the server is listening for
82+
connections. Defaults to the value of the <envar>PGPORT</envar>
83+
environment variable or, if not set, to the port specified at
84+
compile time, usually 5432.
85+
</para>
86+
</listitem>
87+
</varlistentry>
88+
89+
<varlistentry>
90+
<term><option>-q</option></term>
91+
<term><option>--quiet</option></term>
92+
<listitem>
93+
<para>
94+
Do not display status message. This is useful when scripting.
95+
</para>
96+
</listitem>
97+
</varlistentry>
98+
99+
<varlistentry>
100+
<term><option>-U <replaceable class="parameter">username</replaceable></></term>
101+
<term><option>--username=<replaceable class="parameter">username</replaceable></></term>
102+
<listitem>
103+
<para>
104+
Connect to the database as the user <replaceable
105+
class="parameter">username</replaceable> instead of the default.
106+
</para>
107+
</listitem>
108+
</varlistentry>
109+
110+
<varlistentry>
111+
<term><option>-V</></term>
112+
<term><option>--version</></term>
113+
<listitem>
114+
<para>
115+
Print the <application>pg_isready</application> version and exit.
116+
</para>
117+
</listitem>
118+
</varlistentry>
119+
120+
<varlistentry>
121+
<term><option>-?</></term>
122+
<term><option>--help</></term>
123+
<listitem>
124+
<para>
125+
Show help about <application>pg_isready</application> command line
126+
arguments, and exit.
127+
</para>
128+
</listitem>
129+
</varlistentry>
130+
</variablelist>
131+
</refsect1>
132+
133+
<refsect1>
134+
<title>Exit Status</title>
135+
136+
<para>
137+
<application>pg_isready</application> returns <literal>0</literal> to the shell if the server
138+
is accepting connections normally, <literal>1</literal> if the server is rejecting
139+
connections (for example during startup), <literal>2</literal> if there was no response to the
140+
connection attempt, and <literal>3</literal> if no attempt was made (for example due to invalid
141+
parameters).
142+
</para>
143+
</refsect1>
144+
145+
<refsect1>
146+
<title>Environment</title>
147+
148+
<para>
149+
<command>pg_isready</command>, like most other <productname>PostgreSQL</>
150+
utilities,
151+
also uses the environment variables supported by <application>libpq</>
152+
(see <xref linkend="libpq-envars">).
153+
</para>
154+
</refsect1>
155+
156+
<refsect1 id="app-pg-isready-notes">
157+
<title>Notes</title>
158+
159+
<para>
160+
The options <option>--dbname</> and <option>--username</> can be used to avoid gratuitous
161+
error messages in the logs, but are not necessary for proper functionality.
162+
</para>
163+
</refsect1>
164+
165+
<refsect1 id="app-pg-isready-examples">
166+
<title>Examples</title>
167+
168+
<para>
169+
Standard Usage:
170+
<screen>
171+
<prompt>$</prompt> <userinput>pg_isready</userinput>
172+
<computeroutput>/tmp:5432 - accepting connections</computeroutput>
173+
<prompt>$</prompt> <userinput>echo $?</userinput>
174+
<computeroutput>0</computeroutput>
175+
</screen>
176+
</para>
177+
178+
<para>
179+
Running with connection parameters to a <productname>PostgreSQL</productname> cluster in startup:
180+
<screen>
181+
<prompt>$ </prompt><userinput>pg_isready -h localhost -p 5433</userinput>
182+
<computeroutput>localhost:5433 - rejecting connections</computeroutput>
183+
<prompt>$</prompt> <userinput>echo $?</userinput>
184+
<computeroutput>1</computeroutput>
185+
</screen>
186+
</para>
187+
188+
<para>
189+
Running with connection parameters to a non-responsive <productname>PostgreSQL</productname> cluster:
190+
<screen>
191+
<prompt>$ </prompt><userinput>pg_isready -h someremotehost</userinput>
192+
<computeroutput>someremotehost:5432 - no response</computeroutput>
193+
<prompt>$</prompt> <userinput>echo $?</userinput>
194+
<computeroutput>2</computeroutput>
195+
</screen>
196+
</para>
197+
198+
</refsect1>
199+
200+
</refentry>

‎doc/src/sgml/reference.sgml

+1
Original file line numberDiff line numberDiff line change
@@ -223,6 +223,7 @@
223223
&pgConfig;
224224
&pgDump;
225225
&pgDumpall;
226+
&pgIsready;
226227
&pgReceivexlog;
227228
&pgRestore;
228229
&psqlRef;

‎src/bin/scripts/.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
/dropuser
88
/reindexdb
99
/vacuumdb
10+
/pg_isready
1011

1112
/dumputils.c
1213
/keywords.c

‎src/bin/scripts/Makefile

+3-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ subdir = src/bin/scripts
1616
top_builddir = ../../..
1717
include $(top_builddir)/src/Makefile.global
1818

19-
PROGRAMS = createdb createlang createuser dropdb droplang dropuser clusterdb vacuumdb reindexdb
19+
PROGRAMS = createdb createlang createuser dropdb droplang dropuser clusterdb vacuumdb reindexdb pg_isready
2020

2121
override CPPFLAGS := -I$(top_srcdir)/src/bin/pg_dump -I$(top_srcdir)/src/bin/psql -I$(libpq_srcdir) $(CPPFLAGS)
2222

@@ -34,6 +34,7 @@ dropuser: dropuser.o common.o dumputils.o kwlookup.o keywords.o | submake-libpq
3434
clusterdb: clusterdb.o common.o dumputils.o kwlookup.o keywords.o | submake-libpq
3535
vacuumdb: vacuumdb.o common.o dumputils.o kwlookup.o keywords.o | submake-libpq
3636
reindexdb: reindexdb.o common.o dumputils.o kwlookup.o keywords.o | submake-libpq
37+
pg_isready: pg_isready.o common.o | submake-libpq submake-libpgport
3738

3839
dumputils.c keywords.c: % : $(top_srcdir)/src/bin/pg_dump/%
3940
rm -f $@ && $(LN_S) $< .
@@ -54,6 +55,7 @@ install: all installdirs
5455
$(INSTALL_PROGRAM) clusterdb$(X) '$(DESTDIR)$(bindir)'/clusterdb$(X)
5556
$(INSTALL_PROGRAM) vacuumdb$(X) '$(DESTDIR)$(bindir)'/vacuumdb$(X)
5657
$(INSTALL_PROGRAM) reindexdb$(X) '$(DESTDIR)$(bindir)'/reindexdb$(X)
58+
$(INSTALL_PROGRAM) pg_isready$(X) '$(DESTDIR)$(bindir)'/pg_isready$(X)
5759

5860
installdirs:
5961
$(MKDIR_P) '$(DESTDIR)$(bindir)'

0 commit comments

Comments
 (0)