doc/src/sgml/ref/pg_isready.sgml

<!--
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>