granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/pg_isready.sgml

   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>check 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
  58        linkend="libpq-connstring"> for more information.
  59       </para>
  60       </listitem>
  61     </varlistentry>
  62
  63      <varlistentry>
  64        <term><option>-h <replaceable class="parameter">hostname</replaceable></></term>
  65        <term><option>--host=<replaceable class="parameter">hostname</replaceable></></term>
  66        <listitem>
  67        <para>
  68        Specifies the host name of the machine on which the
  69        server is running. If the value begins
  70        with a slash, it is used as the directory for the Unix-domain
  71        socket.
  72        </para>
  73        </listitem>
  74      </varlistentry>
  75
  76      <varlistentry>
  77        <term><option>-p <replaceable class="parameter">port</replaceable></></term>
  78        <term><option>--port=<replaceable class="parameter">port</replaceable></></term>
  79        <listitem>
  80        <para>
  81        Specifies the TCP port or the local Unix-domain
  82        socket file extension on which the server is listening for
  83        connections. Defaults to the value of the <envar>PGPORT</envar>
  84        environment variable or, if not set, to the port specified at
  85        compile time, usually 5432.
  86        </para>
  87        </listitem>
  88      </varlistentry>
  89
  90      <varlistentry>
  91       <term><option>-q</option></term>
  92       <term><option>--quiet</option></term>
  93       <listitem>
  94        <para>
  95         Do not display status message. This is useful when scripting.
  96        </para>
  97       </listitem>
  98      </varlistentry>
  99
 100      <varlistentry>
 101        <term><option>-t <replaceable class="parameter">seconds</replaceable></></term>
 102        <term><option>--timeout=<replaceable class="parameter">seconds</replaceable></></term>
 103        <listitem>
 104        <para>
 105         The maximum number of seconds to wait when attempting connection before
 106         returning that the server is not responding. Setting to 0 disables. The
 107         default is 3 seconds.
 108        </para>
 109        </listitem>
 110      </varlistentry>
 111
 112      <varlistentry>
 113        <term><option>-U <replaceable class="parameter">username</replaceable></></term>
 114        <term><option>--username=<replaceable class="parameter">username</replaceable></></term>
 115        <listitem>
 116        <para>
 117        Connect to the database as the user <replaceable
 118        class="parameter">username</replaceable> instead of the default.
 119        </para>
 120        </listitem>
 121      </varlistentry>
 122
 123      <varlistentry>
 124       <term><option>-V</></term>
 125       <term><option>--version</></term>
 126        <listitem>
 127         <para>
 128          Print the <application>pg_isready</application> version and exit.
 129         </para>
 130        </listitem>
 131      </varlistentry>
 132
 133      <varlistentry>
 134       <term><option>-?</></term>
 135       <term><option>--help</></term>
 136       <listitem>
 137        <para>
 138         Show help about <application>pg_isready</application> command line
 139         arguments, and exit.
 140        </para>
 141       </listitem>
 142      </varlistentry>
 143    </variablelist>
 144  </refsect1>
 145
 146  <refsect1>
 147   <title>Exit Status</title>
 148
 149   <para>
 150    <application>pg_isready</application> returns <literal>0</literal> to the shell if the server
 151    is accepting connections normally, <literal>1</literal> if the server is rejecting
 152    connections (for example during startup), <literal>2</literal> if there was no response to the
 153    connection attempt, and <literal>3</literal> if no attempt was made (for example due to invalid
 154    parameters).
 155   </para>
 156  </refsect1>
 157
 158  <refsect1>
 159   <title>Environment</title>
 160
 161   <para>
 162    <command>pg_isready</command>, like most other <productname>PostgreSQL</>
 163    utilities,
 164    also uses the environment variables supported by <application>libpq</>
 165    (see <xref linkend="libpq-envars">).
 166   </para>
 167  </refsect1>
 168
 169  <refsect1 id="app-pg-isready-notes">
 170   <title>Notes</title>
 171
 172   <para>
 173    The options <option>--dbname</> and <option>--username</> can be used to avoid gratuitous
 174    error messages in the logs, but are not necessary for proper functionality.
 175   </para>
 176  </refsect1>
 177
 178  <refsect1 id="app-pg-isready-examples">
 179   <title>Examples</title>
 180
 181   <para>
 182    Standard Usage:
 183    <screen>
 184     <prompt>$</prompt> <userinput>pg_isready</userinput>
 185     <computeroutput>/tmp:5432 - accepting connections</computeroutput>
 186     <prompt>$</prompt> <userinput>echo $?</userinput>
 187     <computeroutput>0</computeroutput>
 188    </screen>
 189   </para>
 190
 191   <para>
 192    Running with connection parameters to a <productname>PostgreSQL</productname> cluster in startup:
 193    <screen>
 194     <prompt>$ </prompt><userinput>pg_isready -h localhost -p 5433</userinput>
 195     <computeroutput>localhost:5433 - rejecting connections</computeroutput>
 196     <prompt>$</prompt> <userinput>echo $?</userinput>
 197     <computeroutput>1</computeroutput>
 198    </screen>
 199   </para>
 200
 201   <para>
 202    Running with connection parameters to a non-responsive <productname>PostgreSQL</productname> cluster:
 203    <screen>
 204     <prompt>$ </prompt><userinput>pg_isready -h someremotehost</userinput>
 205     <computeroutput>someremotehost:5432 - no response</computeroutput>
 206     <prompt>$</prompt> <userinput>echo $?</userinput>
 207     <computeroutput>2</computeroutput>
 208    </screen>
 209   </para>
 210
 211  </refsect1>
 212
 213 </refentry>