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

<sect1 id="runtime-config-failover">
 <title>Failover and Failback</title>

 <sect2 id="runtime-config-failover-settings">

  <title>Failover and Failback Settings</title>

  <variablelist>

    <varlistentry id="guc-failover-command" xreflabel="failover_command">
      <term><varname>failover_command</varname> (<type>string</type>)
        <indexterm>
          <primary><varname>failover_command</varname> configuration parameter</primary>
        </indexterm>
      </term>
      <listitem>
        <para>
          Specifies a user command to run when a <productname>PostgreSQL</> backend node gets detached.
          <productname>Pgpool-II</productname> replaces the following special characters
          with the backend specific information.
        </para>

        <table id="failover-command-table">
          <title>failover command options</title>
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Special character</entry>
                <entry>Description</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry>%d</entry>
                <entry>DB node ID of the detached node</entry>
              </row>
              <row>
                <entry>%h</entry>
                <entry>Hostname of the detached node</entry>
              </row>
              <row>
                <entry>%p</entry>
                <entry>Port number of the detached node</entry>
              </row>
              <row>
                <entry>%D</entry>
                <entry>Database cluster directory of the detached node</entry>
              </row>
              <row>
                <entry>%M</entry>
                <entry>Old master node ID</entry>
              </row>
              <row>
                <entry>%m</entry>
                <entry>	New master node ID</entry>
              </row>
              <row>
                <entry>%H</entry>
                <entry>Hostname of the new master node</entry>
              </row>
              <row>
                <entry>%P</entry>
                <entry>	Old primary node ID</entry>
              </row>
              <row>
                <entry>%r</entry>
                <entry>Port number of the new master node</entry>
              </row>
              <row>
                <entry>%R</entry>
                <entry>Database cluster directory of the new master node</entry>
              </row>
              <row>
                <entry>%%</entry>
                <entry>	'%' character</entry>
              </row>

            </tbody>
          </tgroup>
        </table>

	<note>
	  <para>
	    The "master node" referes to a node which has the
	    "youngest (or the smallest) node id" among live the
	    database nodes. In <link linkend="running-mode">streaming
	    replication mode</link>, this may be different from
	    primary node. In <xref linkend="failover-command-table">,
	    %m is the new master node chosen
	    by <productname>Pgpool-II</productname>. It is the node
	    being assigned the youngest (smallest) node id which is
	    alive. For example if you have 3 nodes, namely node 0, 1,
	    2. Suppose node 1 the primary and all of them are healthy
	    (no down node). If node 1 fails, failover_command is
	    called with %m = 0.
	  </para>
	</note>

        <note>
          <para>
            When a failover is performed,
            basically <productname>Pgpool-II</productname> kills all
            its child processes, which will in turn terminate all the
            active sessions to
            <productname>Pgpool-II</productname>. After that <productname>Pgpool-II</productname>
            invokes the <command>failover_command</command> and after the command completion
            <productname>Pgpool-II</productname> starts new child processes
            which makes it ready again to accept client connections.
          </para>
	  <para>
	    However from <productname>Pgpool-II</productname> 3.6, In
	    the steaming replication mode, client sessions will not be
	    disconnected when a fail-over occurs any more if the
	    session does not use the failed standby server. If the
	    primary server goes down, still all sessions will be
	    disconnected. Health check timeout case will also cause
	    the full session disconnection. Other health check error,
	    including retry over case does not trigger full session
	    disconnection.
	  </para>
        </note>

        <para>
          This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
        </para>
      </listitem>
    </varlistentry>

  <varlistentry id="guc-failback-command" xreflabel="failback_command">
      <term><varname>failback_command</varname> (<type>string</type>)
        <indexterm>
          <primary><varname>failback_command</varname> configuration parameter</primary>
        </indexterm>
      </term>
      <listitem>
        <para>
          Specifies a user command to run when a <productname>PostgreSQL</> backend node gets attached to
          <productname>Pgpool-II</productname>. <productname>Pgpool-II</productname>
          replaces the following special characters with the backend specific information.
          before excuting the command.
        </para>

        <table id="ffailback-command-table">
          <title>failback command options</title>
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Special character</entry>
                <entry>Description</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry>%d</entry>
                <entry>DB node ID of the attached node</entry>
              </row>
              <row>
                <entry>%h</entry>
                <entry>Hostname of the attached node</entry>
              </row>
              <row>
                <entry>%p</entry>
                <entry>Port number of the attached node</entry>
              </row>
              <row>
                <entry>%D</entry>
                <entry>Database cluster directory of the attached node</entry>
              </row>
              <row>
                <entry>%M</entry>
                <entry>Old master node ID</entry>
              </row>
              <row>
                <entry>%m</entry>
                <entry>	New master node ID</entry>
              </row>
              <row>
                <entry>%H</entry>
                <entry>Hostname of the new master node</entry>
              </row>
              <row>
                <entry>%P</entry>
                <entry>	Old primary node ID</entry>
              </row>
              <row>
                <entry>%r</entry>
                <entry>Port number of the new master node</entry>
              </row>
              <row>
                <entry>%R</entry>
                <entry>Database cluster directory of the new master node</entry>
              </row>
              <row>
                <entry>%%</entry>
                <entry>	'%' character</entry>
              </row>

            </tbody>
          </tgroup>
        </table>

        <para>
          This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="guc-follow-master-command" xreflabel="follow_master_command">
      <term><varname>follow_master_command</varname> (<type>string</type>)
        <indexterm>
          <primary><varname>follow_master_command</varname> configuration parameter</primary>
        </indexterm>
      </term>
      <listitem>

        <para>
          Specifies a user command to run after failover on the primary node failover.
		  This works only in Master Replication mode with streaming replication.
          <productname>Pgpool-II</productname> replaces the following special characters
          with the backend specific information before excuting the command.
        </para>

        <table id="follow-master-command-table">
          <title>follow master command options</title>
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Special character</entry>
                <entry>Description</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry>%d</entry>
                <entry>DB node ID of the detached node</entry>
              </row>
              <row>
                <entry>%h</entry>
                <entry>Hostname of the detached node</entry>
              </row>
              <row>
                <entry>%p</entry>
                <entry>Port number of the detached node</entry>
              </row>
              <row>
                <entry>%D</entry>
                <entry>Database cluster directory of the detached node</entry>
              </row>
              <row>
                <entry>%M</entry>
                <entry>Old master node ID</entry>
              </row>
              <row>
                <entry>%m</entry>
                <entry>	New master node ID</entry>
              </row>
              <row>
                <entry>%H</entry>
                <entry>Hostname of the new master node</entry>
              </row>
              <row>
                <entry>%P</entry>
                <entry>	Old primary node ID</entry>
              </row>
              <row>
                <entry>%r</entry>
                <entry>Port number of the new master node</entry>
              </row>
              <row>
                <entry>%R</entry>
                <entry>Database cluster directory of the new master node</entry>
              </row>
              <row>
                <entry>%%</entry>
                <entry>	'%' character</entry>
              </row>

            </tbody>
          </tgroup>
        </table>

        <note>
        <para>
          If <varname>follow_master_command</varname>> is not empty, then after failover
          on the primary node gets completed in Master Slave mode with streaming replication,
          <productname>Pgpool-II</productname> degenerates all nodes excepted the new primary
          and starts new child processes to be ready again to accept connections from the clients.
          After this, <productname>Pgpool-II</productname> executes the command configured
          in the <varname>follow_master_command</varname> for each degenerated backend nodes.
        </para>
        </note>
        <para>
          Typically <varname>follow_master_command</varname> command is used to recover
          the slave from the new primary by calling the pcp_recovery_node command.
        </para>
        <para>
          This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="guc-fail-over-on-backend-error" xreflabel="fail_over_on_backend_error">
      <term><varname>fail_over_on_backend_error</varname> (<type>boolean</type>)
        <indexterm>
          <primary><varname>fail_over_on_backend_error</varname> configuration parameter</primary>
        </indexterm>
      </term>
      <listitem>
        <para>
          When set to on, <productname>Pgpool-II</productname> considers the reading/writing
          errors on the PostgreSQL backend connection as the backend node failure and trigger the
          failover on that node after disconnecting the current session.
          When this is set to off, <productname>Pgpool-II</productname> only report an error
          and disconnect the session in case of such errors.
        </para>
        <note>
          <para>
            It is recommended to turn on the backend health checking
            (see <xref linkend="runtime-config-health-check">)
            when <varname>fail_over_on_backend_error</varname> is set to off.
            Note, however, that <productname>Pgpool-II</productname> still triggers the
            failover when it detects the administrative shutdown of
            <productname>PostgreSQL</> backend server.
          </para>
        </note>
        <para>
          This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="guc-search-primary-node-timeout" xreflabel="search_primary_node_timeout">
      <term><varname>search_primary_node_timeout</varname> (<type>integer</type>)
        <indexterm>
          <primary><varname>search_primary_node_timeout</varname> configuration parameter</primary>
        </indexterm>
      </term>
      <listitem>
        <para>
          Specifies the maximum amount of time in seconds to search for the
          primary node when a failover scenario occurs.
          <productname>Pgpool-II</productname> will give up looking for the primary
          node if it is not found with-in this configured time.
          Default is 300 and Setting this parameter to 0 means keep trying forever.
        </para>
        <para>
          This parameter is only applicable in the streaming replication mode.
        </para>
        <para>
          This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
        </para>
      </listitem>
    </varlistentry>

  </variablelist>
 </sect2>

 <sect2 id="runtime-config-failover-in-the-raw-mode">

  <title>Failover in the raw Mode</title>

  <para>
  Failover can be performed in raw mode if multiple backend servers are defined.
  <productname>Pgpool-II</> usually accesses the backend specified by
  <literal>backend_hostname0</> during normal operation. If the
  <literal>backend_hostname0</> fails for some reason,
  <productname>Pgpool-II</> tries to access the backend specified by
  <literal>backend_hostname1</>. If that fails, <productname>Pgpool-II</>
  tries the <literal>backend_hostname2, 3</> and so on.
  </para>

 </sect2>

</sect1>
