<!-- doc/src/sgml/config.sgml -->

<sect1 id="runtime-config-health-check">
  <title>Health Check</title>

  <para>
    <productname>Pgpool-II</productname> periodically connects to the configured
    PostgreSQL backends to detect any error on the servers or networks.
    This error check procedure is called "health check".
    If an error is detected, <productname>Pgpool-II</productname> performs failover
    or degeneration depending on the configurations.
    <caution>
      <para>
      Health check requires one extra connection to each backend node,
      so <literal>max_connections</> in the <filename>postgresql.conf</filename>
      needs to be adjusted accordingly.
      </para>
    </caution>
  </para>

  <variablelist>

   <varlistentry id="guc-health-check-timeout" xreflabel="health_check_timeout">
    <term><varname>health_check_timeout</varname> (<type>integer</type>)
      <indexterm>
       <primary><varname>health_check_timeout</varname> configuration parameter</primary>
      </indexterm>
    </term>
  <listitem>
    <para>
      Specifies the timeout in seconds to give up connecting to the backend
      <productname>PostgreSQL</> if the TCP connect does not succeed within this time.
    </para>
    <para>
      This parameter serves to prevent the health check from waiting for a
      long time when the network cable is unplugged.
      Default value is 20. Setting it to 0, disables the timeout (waits until TCP/IP timeout).
    </para>
    <para>
      This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
    </para>
	  </listitem>
   </varlistentry>

   <varlistentry id="guc-health-check-period" xreflabel="health_check_period">
    <term><varname>health_check_period</varname> (<type>integer</type>)
      <indexterm>
        <primary><varname>health_check_period</varname> configuration parameter</primary>
      </indexterm>
    </term>
    <listitem>
    <para>
      Specifies the interval between the health checks in seconds.
      Default is 0, which means health check is disabled.
    </para>
    <para>
     This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
    </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-health-check-user" xreflabel="health_check_user">
    <term><varname>health_check_user</varname> (<type>string</type>)
      <indexterm>
        <primary><varname>health_check_user</varname> configuration parameter</primary>
      </indexterm>
    </term>
    <listitem>
      <para>
        Specifies the <productname>PostgreSQL</> user name to perform health check.
        The same user must exist in all the <productname>PostgreSQL</> backends.
        Otherwise, health check causes an error.
      </para>
      <para>
        This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
      </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-health-check-password" xreflabel="health_check_password">
    <term><varname>health_check_password</varname> (<type>string</type>)
      <indexterm>
        <primary><varname>health_check_password</varname> configuration parameter</primary>
      </indexterm>
    </term>
    <listitem>
      <para>
        Specifies the password for the <productname>PostgreSQL</> user name configured in
        <xref linkend="guc-health-check-user"> to perform health check.
        The user and password must be same in all the <productname>PostgreSQL</> backends.
        Otherwise, health check results in an error.
      </para>
      <para>
        This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id="guc-health-check-database" xreflabel="health_check_database">
    <term><varname>health_check_database</varname> (<type>string</type>)
      <indexterm>
        <primary><varname>health_check_database</varname> configuration parameter</primary>
      </indexterm>
    </term>
    <listitem>
      <para>
        Specifies the PostgreSQL database name to perform health check.
        The default is <literal>''</literal>(empty), which tries <literal>"postgres"</literal>
        database first, then <literal>"template1"</literal> database until it succeeds
      </para>
      <para>
        <varname>health_check_database</varname> was introduced in
        <productname>Pgpool-II</productname> <emphasis>V3.5</emphasis>.
      </para>
      <para>
	      This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id="guc-health-check-max-retries" xreflabel="health_check_max_retries">
    <term><varname>health_check_max_retries</varname> (<type>integer</type>)
      <indexterm>
        <primary><varname>health_check_max_retries</varname> configuration parameter</primary>
      </indexterm>
    </term>
    <listitem>
      <para>
        Specifies the maximum number of retries to do before giving up and
	    initiating failover when health check fails.
        <tip>
          <para>
            This setting can be useful in spotty networks, when it is expected that
            health checks will fail occasionally even when the master node is fine.
          </para>
        </tip>
        <tip>
          <para>
            It is advised that <xref linkend="guc-fail-over-on-backend-error"> must be disabled,
            if you want to enable <varname>health_check_max_retries</>.
          </para>
        </tip>
        Default is 0, which means do not retry.
      </para>
      <para>
        This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id="guc-health-check-retry-delay" xreflabel="health_check_retry_delay">
    <term><varname>health_check_retry_delay</varname> (<type>integer</type>)
      <indexterm>
        <primary><varname>health_check_retry_delay</varname> configuration parameter</primary>
      </indexterm>
    </term>
    <listitem>
      <para>
        Specifies the amount of time in seconds to sleep between failed
        health check retries (not used unless <xref linkend="guc-health-check-max-retries"> is > 0).
        If 0, then retries are immediate without delay.
      </para>
      <para>
        This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
      </para>
    </listitem>
  </varlistentry>

   <varlistentry id="guc-connect-timeout" xreflabel="connect_timeout">
    <term><varname>connect_timeout</varname> (<type>integer</type>)
      <indexterm>
        <primary><varname>connect_timeout</varname> configuration parameter</primary>
      </indexterm>
    </term>
    <listitem>
      <para>
        Specifies the amount of time in milliseconds before giving up connecting
        to backend using <function>connect()</> system call.
        Default is 10000 ms (10 second). The flaky network user may want to increase the value.
        0 means no timeout.
        <note>
          <para>
            <varname>connect_timeout</varname> value is not only used for a health check,
            but also for creating ordinary connection pools.
          </para>
        </note>
      </para>
      <para>
        This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
      </para>
	  </listitem>
   </varlistentry>

  </variablelist>
</sect1>
