Writing some more SGML docs

diff --git a/doc/src/sgml/failover.sgml b/doc/src/sgml/failover.sgml
index 55e73de0b84d8d1294538a37b9286a93c6a143e7..dc4039e960b39c5e41626d35ed3565e25ab70b3f 100644 (file)
--- a/doc/src/sgml/failover.sgml
+++ b/doc/src/sgml/failover.sgml
@@ -3,8 +3,322 @@
 <sect1 id="runtime-config-failover">
   <title>Failover and Failback</title>
 
-  <para>
-    failover_command, failback_command, fail_over_on_backend_error,
-    search_primary_node_timeout
-  </para>
+  <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 PostgreSQL backend node detaches.
+          <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>Backend ID of a detached node</entry>
+              </row>
+              <row>
+                <entry>%h</entry>
+                <entry>Hostname of a detached node</entry>
+              </row>
+              <row>
+                <entry>%p</entry>
+                <entry>Port number of a detached node</entry>
+              </row>
+              <row>
+                <entry>%D</entry>
+                <entry>Database cluster directory of a 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>New master port number</entry>
+              </row>
+              <row>
+                <entry>%R</entry>
+                <entry>New master database cluster directory</entry>
+              </row>
+              <row>
+                <entry>%%</entry>
+                <entry>        '%' character</entry>
+              </row>
+
+            </tbody>
+          </tgroup>
+        </table>
+
+        <note>
+          <para>
+            When a failover is performed, <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>
+        </note>
+        <para>
+          This parameter can be changed by reloading the pgpool 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 PostgreSQL backend node gets attached to
+          <productname>Pgpool-II</productname>, <productname>Pgpool-II</productname>
+          replaces the following special characters with the backend specific information.
+        </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>Backend ID of a detached node</entry>
+              </row>
+              <row>
+                <entry>%h</entry>
+                <entry>Hostname of a detached node</entry>
+              </row>
+              <row>
+                <entry>%p</entry>
+                <entry>Port number of a detached node</entry>
+              </row>
+              <row>
+                <entry>%D</entry>
+                <entry>Database cluster directory of a 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>New master port number</entry>
+              </row>
+              <row>
+                <entry>%R</entry>
+                <entry>New master database cluster directory</entry>
+              </row>
+              <row>
+                <entry>%%</entry>
+                <entry>        '%' character</entry>
+              </row>
+
+            </tbody>
+          </tgroup>
+        </table>
+
+        <para>
+          This parameter can be changed by reloading the pgpool 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 in master/slave streaming replication mode
+          after the master backend node failover.
+          <productname>Pgpool-II</productname>, <productname>Pgpool-II</productname>
+          replaces the following special characters with the backend specific information.
+        </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>Backend ID of a detached node</entry>
+              </row>
+              <row>
+                <entry>%h</entry>
+                <entry>Hostname of a detached node</entry>
+              </row>
+              <row>
+                <entry>%p</entry>
+                <entry>Port number of a detached node</entry>
+              </row>
+              <row>
+                <entry>%D</entry>
+                <entry>Database cluster directory of a 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>New master port number</entry>
+              </row>
+              <row>
+                <entry>%R</entry>
+                <entry>New master database cluster directory</entry>
+              </row>
+              <row>
+                <entry>%%</entry>
+                <entry>        '%' character</entry>
+              </row>
+
+            </tbody>
+          </tgroup>
+        </table>
+
+        <para>
+          If <xref linkend="guc-follow-master-command"> is not left out empty, then when
+          a master node failover gets completed in master/slave streaming replication mode,
+          <productname>Pgpool-II</productname> degenerates all nodes excepted the new master
+          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 <xref linkend="guc-follow-master-command"> for each degenerated backend nodes.
+        </para>
+        <para>
+          Typically <xref linkend="guc-follow-master-command"> command is used to recover
+          the slave from the new master by calling the pcp_recovery_node command.
+        </para>
+        <para>
+          This parameter can be changed by reloading the pgpool 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 <xref linkend="guc-fail-over-on-backend-error"> is set to off.
+            However, <productname>Pgpool-II</productname> still triggers the
+            failover when it detects the administrative shutdown of
+            PostgreSQL backend server.
+          </para>
+        </note>
+        <para>
+          This parameter can be changed by reloading the pgpool 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 10 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 pgpool configurations.
+        </para>
+      </listitem>
+    </varlistentry>
+
+  </variablelist>
+
 </sect1>

diff --git a/doc/src/sgml/healthcheck.sgml b/doc/src/sgml/healthcheck.sgml
index 664e8968d4c26c93359cd70c180c3ba614b66032..14982f4986bd5ea0bcb1ce59ba718c9808a68438 100644 (file)
--- a/doc/src/sgml/healthcheck.sgml
+++ b/doc/src/sgml/healthcheck.sgml
@@ -37,7 +37,7 @@
       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 pgpool configuration.
+      This parameter can be changed by reloading the pgpool configurations.
     </para>
          </listitem>
    </varlistentry>
@@ -54,7 +54,7 @@
       Default is 0, which means health check is disabled.
     </para>
     <para>
-     This parameter can be changed by reloading pgpool configuration.
+     This parameter can be changed by reloading the pgpool configurations.
     </para>
     </listitem>
    </varlistentry>
@@ -72,7 +72,7 @@
         Otherwise, health check causes an error.
       </para>
       <para>
-        This parameter can be changed by reloading pgpool configuration.
+        This parameter can be changed by reloading the pgpool configurations.
       </para>
     </listitem>
    </varlistentry>
@@ -91,7 +91,7 @@
         Otherwise, health check causes an error.
       </para>
       <para>
-        This parameter can be changed by reloading pgpool configuration.
+        This parameter can be changed by reloading the pgpool configurations.
       </para>
     </listitem>
   </varlistentry>
@@ -113,7 +113,7 @@
         <productname>Pgpool-II</productname> <emphasis>V3.5</emphasis>.
       </para>
       <para>
-             This parameter can be changed by reloading pgpool configuration.
+             This parameter can be changed by reloading the pgpool configurations.
       </para>
     </listitem>
   </varlistentry>
@@ -144,7 +144,7 @@
         Default is 0, which means do not retry.
       </para>
       <para>
-        This parameter can be changed by reloading pgpool configuration.
+        This parameter can be changed by reloading the pgpool configurations.
       </para>
     </listitem>
   </varlistentry>
@@ -162,7 +162,7 @@
         If 0, then retries are immediate (no delay).
       </para>
       <para>
-        This parameter can be changed by reloading pgpool configuration.
+        This parameter can be changed by reloading the pgpool configurations.
       </para>
     </listitem>
   </varlistentry>
@@ -187,7 +187,7 @@
         </note>
       </para>
       <para>
-        This parameter can be changed by reloading pgpool configuration.
+        This parameter can be changed by reloading the pgpool configurations.
       </para>
          </listitem>
    </varlistentry>

diff --git a/doc/src/sgml/loadbalance.sgml b/doc/src/sgml/loadbalance.sgml
index 915833418a8d536c153ece1cb4fe74eefd4bb831..33496374ca9dbedf30afe4c3d7a0f3a9839c20d6 100644 (file)
--- a/doc/src/sgml/loadbalance.sgml
+++ b/doc/src/sgml/loadbalance.sgml
@@ -46,7 +46,7 @@
           white spaces against the user's will.
         </para>
         <para>
-          This parameter can be changed by reloading pgpool configuration.
+          This parameter can be changed by reloading the pgpool configurations.
         </para>
       </listitem>
     </varlistentry>
@@ -83,7 +83,7 @@ white_function_list = 'get_.*,select_.*'
         </example>
 
         <para>
-          This parameter can be changed by reloading pgpool configuration.
+          This parameter can be changed by reloading the pgpool configurations.
         </para>
       </listitem>
     </varlistentry>
@@ -153,7 +153,7 @@ black_function_list = 'nextval,setval,lastval,currval'
           </para>
         </note>
         <para>
-          This parameter can be changed by reloading pgpool configuration.
+          This parameter can be changed by reloading the pgpool configurations.
         </para>
       </listitem>
     </varlistentry>
@@ -217,7 +217,7 @@ database_redirect_preference_list = 'postgres:primary,mydb[01]:1,mydb2:standby'
         </example>
 
         <para>
-          This parameter can be changed by reloading pgpool configuration.
+          This parameter can be changed by reloading the pgpool configurations.
         </para>
       </listitem>
     </varlistentry>
@@ -321,7 +321,7 @@ app_name_redirect_preference_list = 'psql:primary,myapp1:1,myapp2:standby'
         </caution>
 
         <para>
-          This parameter can be changed by reloading pgpool configuration.
+          This parameter can be changed by reloading the pgpool configurations.
         </para>
       </listitem>
     </varlistentry>
@@ -343,7 +343,7 @@ app_name_redirect_preference_list = 'psql:primary,myapp1:1,myapp2:standby'
         <emphasis>V3.4</emphasis> behavior).
         </para>
         <para>
-          This parameter can be changed by reloading pgpool configuration.
+          This parameter can be changed by reloading the pgpool configurations.
         </para>
       </listitem>
     </varlistentry>