Documentation update for quorum aware failover feature

The commit also renames the configuration parameter
enable_multiple_failover_requests_from_node to
allow_multiple_failover_requests_from_node

diff --git a/doc/src/sgml/watchdog.sgml b/doc/src/sgml/watchdog.sgml
index 09549af608e5341278a4ffff028114d0b82359d8..81bc5b434fc10c4537ae0ef4630669e7e8cd75e0 100644 (file)
--- a/doc/src/sgml/watchdog.sgml
+++ b/doc/src/sgml/watchdog.sgml
@@ -361,7 +361,7 @@
         </para>
         <para>
         <varname>wd_de_escalation_command</varname> is not available prior to
-        <productname>Pgpool-II</productname><emphasis>V3.5</emphasis>.
+        <productname>Pgpool-II </productname><emphasis>V3.5</emphasis>.
         </para>
         <para>
           This parameter can only be set at server start.
@@ -371,6 +371,124 @@
   </variablelist>
   </sect2>
 
+<sect2 id="config-watchdog-failover-behavior">
+    <title>Controlling the Failover behavior</title>
+
+    <para>
+      These settings are used to control the behavior of backend node failover when the watchdog is enabled.
+      The effect of these configurations is limited to the failover/degenerate requests initiated by
+      <productname>Pgpool-II</productname> internally, while the user initiated detach backend requests
+      (using PCP command) by-pass these configuration settings.
+    </para>
+
+    <variablelist>
+
+      <varlistentry id="guc-failover-when-quorum-exists" xreflabel="failover_when_quorum_exists">
+        <term><varname>failover_when_quorum_exists</varname> (<type>boolean</type>)
+          <indexterm>
+            <primary><varname>failover_when_quorum_exists</varname> configuration parameter</primary>
+          </indexterm>
+        </term>
+      <listitem>
+        <para>
+        When enabled, <productname>Pgpool-II</productname> will perform the degenerate/failover on
+        backend node if the quorum exists. In the absence of the quorum, <productname>Pgpool-II</productname>
+        node that detects the backend failure will quarantine the failed backend node until the quorum exists again.
+        </para>
+        <para>
+        The quarantine nodes behaves similar to the detached backend nodes but unlike failed/degenerated backends
+        the quarantine status is not propagated to the other <productname>Pgpool-II</productname> nodes in the
+        watchdog cluster, So even if the backend node is in the quarantine state on one
+        <productname>Pgpool-II</productname> node, other <productname>Pgpool-II</productname> nodes may
+        still continue to use that backend.
+        </para>
+        <para>
+        Although there are many similarities in quarantine and failover operations, but they both differ in a very
+        fundamental way. The quarantine operations does not executes the <xref linkend="guc-failover-command">
+        and silently detaches the problematic node, So in the case when the master backend node is quarantined, the
+        <productname>Pgpool-II</productname> will not promote the standby to take over the master responsibilities
+        and until the master node is quarantined the <productname>Pgpool-II</productname> will not have
+        any useable master backend node.
+        </para>
+        <para>
+          Default is on.
+        </para>
+        <para>
+        <varname>failover_when_quorum_exists</varname> is not available prior to
+        <productname>Pgpool-II </productname><emphasis>V3.7</emphasis>.
+        </para>
+        <para>
+          This parameter can only be set at server start.
+        </para>
+      </listitem>
+    </varlistentry>
+
+      <varlistentry id="guc-failover-require-consensus" xreflabel="failover_require_consensus">
+        <term><varname>failover_require_consensus</varname> (<type>boolean</type>)
+          <indexterm>
+            <primary><varname>failover_require_consensus</varname> configuration parameter</primary>
+          </indexterm>
+        </term>
+      <listitem>
+        <para>
+        When enabled, <productname>Pgpool-II</productname> will perform the degenerate/failover on a
+        backend node if the watchdog quorum exists and at-least minimum number of nodes necessary
+        for the quorum vote for the failover.
+        </para>
+        <para>
+        For example, in a three node watchdog cluster, the failover will only be performed until at
+        least two nodes ask for performing the failover on the particular backend node.
+        </para>
+        <para>
+          Default is on.
+        </para>
+        <para>
+        <varname>failover_require_consensus</varname> is not available prior to
+        <productname>Pgpool-II </productname><emphasis>V3.7</emphasis>. and it is only
+        effective when <xref linkend="guc-failover-when-quorum-exists"> is enabled
+        </para>
+        <para>
+          This parameter can only be set at server start.
+        </para>
+      </listitem>
+    </varlistentry>
+
+      <varlistentry id="guc-allow-multiple-failover-requests-from-node" xreflabel="allow_multiple_failover_requests_from_node">
+        <term><varname>allow_multiple_failover_requests_from_node</varname> (<type>boolean</type>)
+          <indexterm>
+            <primary><varname>allow_multiple_failover_requests_from_node</varname> configuration parameter</primary>
+          </indexterm>
+        </term>
+      <listitem>
+        <para>
+        This parameter works in connection with the
+        <xref linkend="guc-failover-require-consensus">. When enabled, a single <productname>Pgpool-II</productname>
+        node can cast multiple votes for the failover.
+        </para>
+        <para>
+        For example, in a three node watchdog cluster, if one <productname>Pgpool-II</productname> node sends two
+        failover requests for a particular backend node failover, Both requests will be counted as a separate
+        vote in the favor of the failover and <productname>Pgpool-II</productname> will execute the failover,
+        even if it does not get the vote from any other <productname>Pgpool-II</productname> node.
+        </para>
+        <para>
+          Default is off.
+        </para>
+        <para>
+        <varname>allow_multiple_failover_requests_from_node</varname> is not available prior to
+        <productname>Pgpool-II </productname><emphasis>V3.7</emphasis>. and it is only
+        effective when both <xref linkend="guc-failover-when-quorum-exists"> and
+        <xref linkend="guc-failover-require-consensus"> are enabled
+        </para>
+        <para>
+          This parameter can only be set at server start.
+        </para>
+      </listitem>
+    </varlistentry>
+
+  </variablelist>
+  </sect2>
+
 <sect2 id="config-watchdog-lifecheck">
     <title>Life checking <productname>Pgpool-II</productname> </title>
 

diff --git a/src/config/pool_config_variables.c b/src/config/pool_config_variables.c
index 29617c418e9fa9e2bbc2777f7d2fc8800774c264..3ab803f1513e73e947aae1827c1da2b39a5d36ca 100644 (file)
--- a/src/config/pool_config_variables.c
+++ b/src/config/pool_config_variables.c
@@ -250,11 +250,11 @@ static struct config_bool ConfigureNamesBool[] =
                NULL, NULL,NULL
        },
        {
-               {"enable_multiple_failover_requests_from_node", CFGCXT_INIT, FAILOVER_CONFIG,
+               {"allow_multiple_failover_requests_from_node", CFGCXT_INIT, FAILOVER_CONFIG,
                        "A Pgpool-II node can send multiple failover requests to build consensus.",
                        CONFIG_VAR_TYPE_BOOL,false, 0
                },
-               &g_pool_config.enable_multiple_failover_requests_from_node,
+               &g_pool_config.allow_multiple_failover_requests_from_node,
                false,
                NULL, NULL,NULL
        },

diff --git a/src/include/pool_config.h b/src/include/pool_config.h
index 148d8d02cb9da7d0ce03106cfc4bf644b253fcba..22ea360deb5374efc649b7888775180b9d3872d5 100644 (file)
--- a/src/include/pool_config.h
+++ b/src/include/pool_config.h
@@ -302,7 +302,7 @@ typedef struct {
        bool use_watchdog;                                              /* Enables watchdog */
        bool failover_when_quorum_exists;               /* Do failover only when wd cluster holds he quorum */
        bool failover_require_consensus;                /* Only do failover when majority aggrees */
-       bool enable_multiple_failover_requests_from_node; /* One Pgpool-II node can send multiple
+       bool allow_multiple_failover_requests_from_node; /* One Pgpool-II node can send multiple
                                                                                                           * failover requests to build consensus
                                                                                                           */
        WdLifeCheckMethod wd_lifecheck_method;  /* method of lifecheck. 'heartbeat' or 'query' */

diff --git a/src/sample/pgpool.conf.sample b/src/sample/pgpool.conf.sample
index 0c09537ab53c40924b0c53ba2447c2e93dfb3ec4..4a70fd0d65001342242b9995f9aaab8bb2340f0c 100644 (file)
--- a/src/sample/pgpool.conf.sample
+++ b/src/sample/pgpool.conf.sample
@@ -561,7 +561,7 @@ failover_require_consensus = true
                                                                        # Perform failover when majority of Pgpool-II nodes
                                                                        # aggrees on the backend node status change
 
-enable_multiple_failover_requests_from_node = false
+allow_multiple_failover_requests_from_node = false
                                                                        # A Pgpool-II node can cast multiple votes
                                                                        # for building the consensus on failover
 

diff --git a/src/sample/pgpool.conf.sample-master-slave b/src/sample/pgpool.conf.sample-master-slave
index 360cba1fd5bb13a8f2f31ab2a53ccfcf9cadfa16..4e1f86ba8f8dd08c1667c43f4def9d23688fddea 100644 (file)
--- a/src/sample/pgpool.conf.sample-master-slave
+++ b/src/sample/pgpool.conf.sample-master-slave
@@ -559,7 +559,7 @@ failover_require_consensus = true
                                                                        # Perform failover when majority of Pgpool-II nodes
                                                                        # aggrees on the backend node status change
 
-enable_multiple_failover_requests_from_node = false
+allow_multiple_failover_requests_from_node = false
                                                                        # A Pgpool-II node can cast multiple votes
                                                                        # for building the consensus on failover
 

diff --git a/src/sample/pgpool.conf.sample-replication b/src/sample/pgpool.conf.sample-replication
index ebf530b6e610f3c5c875445c719ede592024fbc5..68c1106819011597f4a651047b12372bb5c947d6 100644 (file)
--- a/src/sample/pgpool.conf.sample-replication
+++ b/src/sample/pgpool.conf.sample-replication
@@ -560,7 +560,7 @@ failover_require_consensus = true
                                                                        # aggrees on the backend node status change
 
 
-enable_multiple_failover_requests_from_node = false
+allow_multiple_failover_requests_from_node = false
                                                                        # A Pgpool-II node can cast multiple votes
                                                                        # for building the consensus on failover
 

diff --git a/src/sample/pgpool.conf.sample-stream b/src/sample/pgpool.conf.sample-stream
index f5832c72390195794400f10c759cb5f92fc70596..cf3a7dc36e2addbfac6f37be722dbeb8ae8c4f63 100644 (file)
--- a/src/sample/pgpool.conf.sample-stream
+++ b/src/sample/pgpool.conf.sample-stream
@@ -560,7 +560,7 @@ failover_require_consensus = true
                                                                        # Perform failover when majority of Pgpool-II nodes
                                                                        # aggrees on the backend node status change
 
-enable_multiple_failover_requests_from_node = false
+allow_multiple_failover_requests_from_node = false
                                                                        # A Pgpool-II node can cast multiple votes
                                                                        # for building the consensus on failover
 

diff --git a/src/watchdog/watchdog.c b/src/watchdog/watchdog.c
index bc4f20680c531e4fd69996e0a8f48444f43b2972..8abb9e362b438ec1705245e455604c543e6bb334 100644 (file)
--- a/src/watchdog/watchdog.c
+++ b/src/watchdog/watchdog.c
@@ -2265,7 +2265,7 @@ static WDFailoverCMDResults compute_failover_consensus(POOL_REQUEST_KIND reqKind
                        ereport(LOG,(
                                        errmsg("failover requires the majority vote, waiting for consensus"),
                                                 errdetail("failover request noted")));
-                       if (duplicate && !pool_config->enable_multiple_failover_requests_from_node)
+                       if (duplicate && !pool_config->allow_multiple_failover_requests_from_node)
                                return FAILOVER_RES_CONSENSUS_MAY_FAIL;
                        else
                                return FAILOVER_RES_BUILDING_CONSENSUS;
@@ -2311,13 +2311,13 @@ static WDFailoverObject* add_failover(POOL_REQUEST_KIND reqKind, int *node_id_li
                        {
                                *duplicate = true;
                                /* The failover request is duplicate */
-                               if (pool_config->enable_multiple_failover_requests_from_node)
+                               if (pool_config->allow_multiple_failover_requests_from_node)
                                {
                                        failoverObj->request_count++;
                                        ereport(LOG,(
                                                        errmsg("duplicate failover request from \"%s\" node",wdNode->nodeName),
                                                                 errdetail("Pgpool-II can send multiple failover requests for same node"),
-                                                                errhint("enable_multiple_failover_requests_from_node is enabled")));
+                                                                errhint("allow_multiple_failover_requests_from_node is enabled")));
                                }
                                else
                                {