pgpool2.git / summary / log / commit / refs
commit 1caa58da593af8ebf6e5419818ee30e70b6d915f
Author: Muhammad Usama <m.usama@gmail.com>
Date: Thu Oct 13 14:51:55 2016 +0000
Some more SGML docs
doc/src/sgml/connection-pooling.sgml | 572 +++++++++++++++++++++++++++++++++-
doc/src/sgml/connection-settings.sgml | 15 +-
doc/src/sgml/loadbalance.sgml | 23 ++
doc/src/sgml/memcache.sgml | 2 +-
doc/src/sgml/misc-config.sgml | 41 +++
doc/src/sgml/online-recovery.sgml | 89 +++++-
6 files changed, 724 insertions(+), 18 deletions(-)
diff --git a/doc/src/sgml/connection-pooling.sgml b/doc/src/sgml/connection-pooling.sgml
index 3ed149a6a..0b1bd74f8 100644
--- a/doc/src/sgml/connection-pooling.sgml
+++ b/doc/src/sgml/connection-pooling.sgml
@@ -10,10 +10,6 @@
protocol version) comes in. It reduces the connection overhead,
and improves system's overall throughput.
</para>
- <para>
- connection_cache, max_pool, reset_query_list, child_life_time,
- child_max_connections, connection_life_time, client_idle_limit
- </para>
<sect2 id="runtime-config-connection-pooling-settings">
<title>Connection Pooling Settings</title>
@@ -67,7 +63,153 @@
This parameter can only be set at server start.
</para>
</listitem>
- </varlistentry>
+ </varlistentry>
+
+ <varlistentry id="guc-listen-backlog-multiplier" xreflabel="listen_backlog_multiplier">
+ <term><varname>listen_backlog_multiplier</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>listen_backlog_multiplier</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Specifies the length of connection queue from frontend to
+ <productname>Pgpool-II</productname>. The queue length (actually
+ <literal>"backlog"</literal> parameter of <literal>listen()</literal>
+ system call) is defined as
+ <varname>listen_backlog_multiplier</varname> * <xref linkend="guc-num-init-children">.
+ </para>
+ <note>
+ <para>
+ Some systems have the upper limit of the backlog parameter of
+ <literal>listen()</literal> system call.
+ See <xref linkend="guc-num-init-children"> for more details.
+ </para>
+ </note>
+ <para>
+ Default is 2.
+ </para>
+ <para>
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-serialize-accept" xreflabel="serialize_accept">
+ <term><varname>serialize_accept</varname> (<type>boolean</type>)
+ <indexterm>
+ <primary><varname>serialize_accept</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ When set to on, <productname>Pgpool-II</productname> enables the serialization
+ on incoming client connections.
+ Without serialization the OS kernel wakes up all of the <productname>
+ Pgpool-II</productname> child process to execute accept() and one of them
+ actually gets the incoming connection. The problem here is, because so my child
+ process wake up at a same time, heavy context switching occurs and the
+ performance is affected.
+ </para>
+ <para>
+ This phenomena is a well known classic problem called
+ "the thundering herd problem". which can be solved by the
+ the serialization of the accept calls, so that only one
+ <productname>Pgpool-II</productname> process gets woken up
+ for incoming connection to execute the <literal>accept()
+ </literal>.
+ </para>
+
+ <para>
+ But serialization has its own overheads, and it is recomended
+ to be used only with the larger values of <xref linkend="guc-num-init-children">.
+ For the small number of <xref linkend="guc-num-init-children">,
+ the serialize accept can degrade the performance because of
+ serializing overhead.
+ </para>
+
+ <note>
+ <para>
+ It is recomended to do a benchmark before deciding wether to use
+ <varname>serialize_accept</varname> or not, because the corelation
+ of <xref linkend="guc-num-init-children"> and <varname>serialize_accept</varname>
+ can be different on different environments.
+ </para>
+ </note>
+
+ <example id="example-serialize-accept-pgbench">
+ <title>Using pgbench to decide if serialize_accept should be used</title>
+ <para>
+ To run the <command>pgbench</command> use the following
+ command.
+ <programlisting>
+pgbench -n -S -p 9999 -c 32 -C -S -T 300 test
+ </programlisting>
+ Here, <literal>-C</literal> tells <command>pgbench</command> to connect
+ to database each time a transaction gets executed. <literal>-c 32</literal>
+ specifies the concurrent sessions to <productname>Pgpool-II</productname>.
+ You should change this according to your system's requirement.
+ When <command>pgbench</command> finishes, you want to check the number from
+ "including connections establishing".
+ </para>
+ </example>
+
+ <note>
+ <para>
+ When <xref linkend="guc-child-life-time"> is enabled, <varname>serialize_accept</varname>
+ has no effect. Make sure that you set <xref linkend="guc-child-life-time"> to 0 if you intend
+ to turn on the <varname>serialize_accept</varname>.
+ And if you are worried about <productname>Pgpool-II</productname> process memory leaks
+ or whatever potential issue, you could use <xref linkend="guc-child-max-connections"> instead.
+ This is purely an implementation limitation and may be removed in the future.
+ </para>
+ </note>
+
+ <para>
+ Default is off.
+ </para>
+ <para>
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-child-life-time" xreflabel="child_life_time">
+ <term><varname>child_life_time</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>child_life_time</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Specifies the time in seconds to terminate a <productname>Pgpool-II
+ </productname> child process if it remains idle. The new child process
+ is immediately spawned by <productname>Pgpool-II</productname>, when it
+ is terminated because of <varname>child_life_time</varname>.
+ <varname>child_life_time</varname> is a measure to prevent the
+ memory leaks and other unexpected errors in <productname>Pgpool-II
+ </productname> children.
+ </para>
+ <note>
+ <para>
+ <varname>child_life_time</varname> does not apply to
+ processes that have not accepted any connection yet.
+ </para>
+ </note>
+ <note>
+ <para>
+ <xref linkend="guc-serialize-accept"> becomes ineffective when
+ <varname>child_life_time</varname> is enabled.
+ </para>
+ </note>
+ <para>
+ Default is 300 (5 minutes) and setting it to 0 disables the feature.
+ </para>
+ <para>
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
<varlistentry id="guc-client-idle-limit" xreflabel="client_idle_limit">
<term><varname>client_idle_limit</varname> (<type>integer</type>)
@@ -98,6 +240,426 @@
</listitem>
</varlistentry>
+ <varlistentry id="guc-child-max-connections" xreflabel="child_max_connections">
+ <term><varname>child_max_connections</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>child_max_connections</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Specifies the lifetime of a <productname>Pgpool-II</productname>
+ child process in terms of the number of client connections it can receive.
+ <productname>Pgpool-II</productname> will terminate the child process
+ after it has served <varname>child_max_connections</varname> client
+ connections and will immediately spawn a new child process to take its place.
+ </para>
+ <para>
+ <varname>child_max_connections</varname> is useful on a very busy server,
+ where <xref linkend="guc-child-life-time"> and <xref linkend="guc-connection-life-time">
+ never gets triggered. It is also useful to prevent the PostgreSQL servers from getting
+ too big.
+ </para>
+ <para>
+ The default is 0, which turns off the feature.
+ </para>
+ <para>
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-connection-life-time" xreflabel="connection_life_time">
+ <term><varname>connection_life_time</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>connection_life_time</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Specifies the time in seconds to terminate the cached connections
+ to the PostgreSQL backend. This serves as the cached connection expiration time.
+ </para>
+ <para>
+ The default is 0, which means the cached connections will not be disconnected.
+ </para>
+ <para>
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-reset-query-list" xreflabel="reset_query_list">
+ <term><varname>reset_query_list</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>reset_query_list</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Specifies the <acronym>SQL</acronym> commands to be sent to reset the backend connection
+ when exiting the user session. Multiple commands can be specified by delimiting each
+ by <literal>";"</literal>.
+ </para>
+
+ <para>
+ Since the commands are different in each PostgreSQL version, So
+ below are some recommended settings for <varname>reset_query_list</varname>
+ on different PostgreSQL versions.
+ </para>
+
+ <table id="reset-query-list-suggestions-table">
+ <title>Recommended setting for <varname>reset_query_list</varname>
+ on different PostgreSQL versions</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>PostgreSQL version</entry>
+ <entry>reset_query_list</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>7.1 or earlier</entry>
+ <entry><literal>'ABORT'</literal></entry>
+ </row>
+
+ <row>
+ <entry>7.2 to 8.2</entry>
+ <entry><literal>'ABORT; RESET ALL; SET SESSION AUTHORIZATION DEFAULT'</literal></entry>
+ </row>
+
+ <row>
+ <entry>8.3 or later</entry>
+ <entry><literal>'ABORT; DISCARD ALL'</literal></entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+
+ <note>
+ <para>
+ <literal>"ABORT"</literal> is not issued when not in a transaction block for 7.4 or later
+ PostgreSQL versions.
+ </para>
+ </note>
+ <para>
+ Default is <literal>'ABORT; DISCARD ALL'</literal>.
+ </para>
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</sect2>
</sect1>
+
+<sect1 id="runtime-config-logging">
+ <title>Error Reporting and Logging</title>
+
+ <sect2 id="runtime-config-logging-where-to-log">
+ <title>Where To Log</title>
+
+ <variablelist>
+
+ <varlistentry id="guc-log-destination" xreflabel="log_destination">
+ <term><varname>log_destination</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>log_destination</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <productname>Pgpool-II</productname> supports several methods
+ for logging server messages, including <literal>stderr</literal>
+ and <literal>syslog</literal>.
+ The default is to log to <literal>stderr</literal>.
+ </para>
+ <note>
+ <para>
+ On some systems you will need to alter the configuration of your
+ system's syslog daemon in order to make use of the syslog option
+ for <xref linkend="guc-log-destination">. <productname>Pgpool-II</productname>
+ can log to syslog facilities LOCAL0 through LOCAL7
+ (see <xref linkend="guc-syslog-facility">), but the default syslog
+ configuration on most platforms will discard all such messages.
+ You will need to add something like:
+ <programlisting>
+local0.* /var/log/postgresql
+ </programlisting>
+ to the syslog daemon's configuration file to make it work.
+ </para>
+ </note>
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-syslog-facility" xreflabel="syslog_facility">
+ <term><varname>syslog_facility</varname> (<type>enum</type>)
+ <indexterm>
+ <primary><varname>syslog_facility</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ When logging to syslog is enabled, this parameter determines
+ the syslog <literal>"facility"</literal> to be used.
+ You can choose from LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4,
+ LOCAL5, LOCAL6, LOCAL7; the default is LOCAL0.
+ See also the documentation of your system's syslog daemon.
+ </para>
+
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-syslog-ident" xreflabel="syslog_ident">
+ <term><varname>syslog_ident</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>syslog_ident</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ When logging to syslog is enabled, this parameter determines
+ the program name used to identify <productname>Pgpool-II</productname>
+ messages in syslog logs. The default is <literal>pgpool</literal>.
+ </para>
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+
+ <sect2 id="runtime-config-logging-when-to-log">
+ <title>When To Log</title>
+
+ <variablelist>
+
+ <varlistentry id="guc-client-min-messages" xreflabel="client_min_messages">
+ <term><varname>client_min_messages</varname> (<type>enum</type>)
+ <indexterm>
+ <primary><varname>client_min_messages</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Controls which minimum message levels are sent to the client.
+ Valid values are DEBUG5, DEBUG4, DEBUG3, DEBUG2, DEBUG1,
+ LOG, NOTICE, WARNING and ERROR. Each level includes
+ all the levels that follow it. The default is NOTICE.
+ </para>
+
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-min-messages" xreflabel="log_min_messages">
+ <term><varname>log_min_messages</varname> (<type>enum</type>)
+ <indexterm>
+ <primary><varname>log_min_messages</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Controls which minimum message levels are emitted to log.
+ Valid values are DEBUG5, DEBUG4, DEBUG3, DEBUG2, DEBUG1,
+ INFO, NOTICE, WARNING, ERROR, LOG, FATAL, and PANIC.
+ Each level includes all the levels that follow it.
+ The default is WARNING.
+ </para>
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+
+ <sect2 id="runtime-config-logging-what-to-log">
+ <title>What To Log</title>
+
+ <variablelist>
+
+ <varlistentry id="guc-log-statement" xreflabel="log_statement">
+ <term><varname>log_statement</varname> (<type>boolean</type>)
+ <indexterm>
+ <primary><varname>log_statement</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Setting to on, prints all statements to the log.
+ </para>
+
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-per-node-statement" xreflabel="log_per_node_statement">
+ <term><varname>log_per_node_statement</varname> (<type>boolean</type>)
+ <indexterm>
+ <primary><varname>log_per_node_statement</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Similar to <xref linkend="guc-log-statement">, except that it print the
+ logs for each DB node separately. It can be useful to make sure that
+ replication is working.
+ </para>
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-hostname" xreflabel="log_hostname">
+ <term><varname>log_hostname</varname> (<type>boolean</type>)
+ <indexterm>
+ <primary><varname>log_hostname</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Setting to on, prints the hostname instead of IP address
+ in ps command and connection logs(when <xref linkend="guc-log-connections"> is on).
+ </para>
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-connections" xreflabel="log_connections">
+ <term><varname>log_connections</varname> (<type>boolean</type>)
+ <indexterm>
+ <primary><varname>log_connections</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Setting to on, prints all incoming connections to the log.
+ </para>
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-error-verbosity" xreflabel="log_error_verbosity">
+ <term><varname>log_error_verbosity</varname> (<type>enum</type>)
+ <indexterm>
+ <primary><varname>log_error_verbosity</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Controls the amount of detail emitted for each message that is logged.
+ Valid values are TERSE, DEFAULT, and VERBOSE, each adding more fields
+ to displayed messages. TERSE excludes the logging of DETAIL, HINT,
+ and CONTEXT error information.
+ </para>
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-line-prefix" xreflabel="log_line_prefix">
+ <term><varname>log_line_prefix</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>log_line_prefix</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ This is a printf-style string that is output at the beginning of each log line.
+ <emphasis>%</emphasis> characters begin "escape sequences" that are replaced
+ with information outlined below.
+ All unrecognized escapes are ignored. Other characters are copied straight to
+ the log line. Default is '%t: pid %p: ', which prints timestamp and process id,
+ which keeps backward compatibily with pre<productname>Pgpool-II</productname>
+ <emphasis>V3.4</emphasis>.
+ </para>
+
+ <table id="log-line-prefix-table">
+ <title>log_line_prefix escape options</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Escape</entry>
+ <entry>Effect</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>%a</entry>
+ <entry>Client application name</entry>
+ </row>
+
+ <row>
+ <entry>%p</entry>
+ <entry>Process ID (PID)</entry>
+ </row>
+
+ <row>
+ <entry>%P</entry>
+ <entry>Process name</entry>
+ </row>
+
+ <row>
+ <entry>%t</entry>
+ <entry>Time stamp</entry>
+ </row>
+
+ <row>
+ <entry>%d</entry>
+ <entry>Database name</entry>
+ </row>
+
+ <row>
+ <entry>%u</entry>
+ <entry>User name</entry>
+ </row>
+
+ <row>
+ <entry>%l</entry>
+ <entry>Log line number for each process</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>
+
+ </variablelist>
+ </sect2>
+</sect1>
diff --git a/doc/src/sgml/connection-settings.sgml b/doc/src/sgml/connection-settings.sgml
index 6d30a75bf..5a45ec0c5 100644
--- a/doc/src/sgml/connection-settings.sgml
+++ b/doc/src/sgml/connection-settings.sgml
@@ -3,10 +3,6 @@
<sect1 id="runtime-config-connection">
<title>Connections and Authentication</title>
- <para>
- listen_addresses, num_init_children
- </para>
-
<sect2 id="runtime-config-connection-settings">
<title>Connection Settings</title>
@@ -148,16 +144,17 @@
blocked (not rejected) until a connection to
any <productname>Pgpool-II</productname> process is
closed</emphasis>. Up to
- listen_backlog_multiplier*num_init_children can be queued.
+ <xref linkend="guc-listen-backlog-multiplier">*
+ num_init_children can be queued.
</para>
<para>
The queue is inside the kernel called "listen queue". The
length of the listen queue is called "backlog". There is
an upper limit of the backlog in some systems, and if
- num_init_children*listen_backlog_multiplier exceeds the
- number, you need to set the backlong higher. Otherwise,
- following problems may occur in heavy loaded systems: 1)
- connecting to <productname>Pgpool-II</productname> fails
+ num_init_children*<xref linkend="guc-listen-backlog-multiplier">
+ exceeds the number, you need to set the backlong higher.
+ Otherwise, following problems may occur in heavy loaded systems:
+ 1) connecting to <productname>Pgpool-II</productname> fails
2) connecting to <productname>Pgpool-II</productname> is
getting slow because of retries in the kernel. You can
check if the listen queue is actually overflowed by using
diff --git a/doc/src/sgml/loadbalance.sgml b/doc/src/sgml/loadbalance.sgml
index bca5e4ff8..c126a47e2 100644
--- a/doc/src/sgml/loadbalance.sgml
+++ b/doc/src/sgml/loadbalance.sgml
@@ -3,6 +3,29 @@
<sect1 id="runtime-config-load-balancing">
<title>Load Balancing</title>
+ <para>
+ <productname>Pgpool-II</productname> load balancing of SELECT queries
+ works with Master Slave mode(<xref linkend="runtime-config-master-slave-mode">)
+ and Replication mode(<xref linkend="runtime-config-replication-mode">). When enabled
+ <productname>Pgpool-II</productname> sends the writing queries to the
+ <acronym>Master DB</acronym>, and other queries get load balanced to
+ <acronym>Standby DB nodes</acronym> if possible.
+ </para>
+ <note>
+ <para>
+ Queries sent to Master DB because they cannot be balanced are also accounted for in the load balancing algorithm.
+ </para>
+ </note>
+ <note>
+ <para>
+ If you don't want a query that qualifies for the load balancing to be
+ load balanced by <productname>Pgpool-II</productname>, you can put
+ <emphasis>/*NO LOAD BALANCE*/</emphasis> comment before the <acronym>SELECT
+ </acronym> statement, This will disable the load balance of the particular query
+ and <productname>Pgpool-II</productname> will send it to the Master DB node.
+ </para>
+ </note>
+
<variablelist>
<varlistentry id="guc-load-balance-mode" xreflabel="load_balance_mode">
diff --git a/doc/src/sgml/memcache.sgml b/doc/src/sgml/memcache.sgml
index d3a501425..8be0fd9f1 100644
--- a/doc/src/sgml/memcache.sgml
+++ b/doc/src/sgml/memcache.sgml
@@ -100,7 +100,7 @@
</table>
<para>
- Default is 'shmem'.
+ Default is <literal>'shmem'</literal>.
</para>
<para>
diff --git a/doc/src/sgml/misc-config.sgml b/doc/src/sgml/misc-config.sgml
index a7cbbf1b1..a1a6a4b50 100644
--- a/doc/src/sgml/misc-config.sgml
+++ b/doc/src/sgml/misc-config.sgml
@@ -116,5 +116,46 @@
</listitem>
</varlistentry>
+ <varlistentry id="guc-pid-file-name" xreflabel="pid_file_name">
+ <term><varname>pid_file_name</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>pid_file_name</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+
+ <para>
+ Specifies the full path to a file to store the <productname>Pgpool-II
+ </productname> process id.
+ Default is <literal>"/var/run/pgpool/pgpool.pid"</literal>.
+ </para>
+
+ <para>
+ This parameter can only be set at server start.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-logdir" xreflabel="logdir">
+ <term><varname>logdir</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>logdir</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+
+ <para>
+ Specifies the full path to a directory to store the <literal>pool_status</literal>.
+ Default is <literal>"/tmp"</literal>.
+ </para>
+
+ <para>
+ This parameter can only be set at server start.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
</variablelist>
</sect1>
diff --git a/doc/src/sgml/online-recovery.sgml b/doc/src/sgml/online-recovery.sgml
index cef9ace2a..832d7b8cb 100644
--- a/doc/src/sgml/online-recovery.sgml
+++ b/doc/src/sgml/online-recovery.sgml
@@ -4,13 +4,96 @@
<title>Online Recovery</title>
<para>
- recovery_user, recovery_password,recovery_1st_stage_command,
- recovery_2nd_stage_command,recovery_timeout, client_idle_limit_in_recovery
+ <productname>Pgpool-II</productname>, when in replication mode,
+ can sync a database and attach a node while still servicing the clients.
+ This feature is called <acronym>"online recovery"</acronym>.
</para>
<para>
- <productname>Pgpool-II</productname>
+ For online recovery, a recovery target node must be in the detached state.
+ And if you wish to add a PostgreSQL server dynamically, reload the
+ <filename>pgpool.conf</filename> after adding the
+ <xref linkend="guc-backend-hostname"> and its associated parameters.
+ This is how the <productname>Pgpool-II</productname> will register this
+ new node as a detached backend node.
</para>
+ <caution>
+ <para>
+ Make sure that <command>autovacuum</command> is stopped on the
+ master node (the first node which is up and running) before starting the
+ online recovery. Autovacuum can change the contents of the database which
+ can cause the inconsistency after the online recovery.
+ </para>
+ <para>
+ This applies only if you're recovering with a simple copy mechanism,
+ such as the <command>rsync</command> and doesn't apply when using
+ the PostgreSQL's PITR mechanism.
+ </para>
+ </caution>
+ <note>
+ <para>
+ The target PostgreSQL server must not be running for performing the online recovery.
+ If the target PostgreSQL server has already started, you must shut it down before
+ starting the online recovery.
+ </para>
+ </note>
+ <para>
+ online recovery is performed in two phases, and client connections are
+ not allowd only in second phase of online recovery while the data can be
+ updated or retrieved during the first phase.
+ <productname>Pgpool-II</productname> performs the follows steps in online recovery:
+ </para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ CHECKPOINT.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ First stage of online recovery.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Wait until all clients have disconnected.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ CHECKPOINT.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Second stage of online recovery.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Start up postmaster (perform <literal>pgpool_remote_start</literal>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Node attach
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ <note>
+ <para>
+ There is a restriction in the online recovery. If
+ <productname>Pgpool-II</productname> itself is installed
+ on multiple hosts, online recovery does not work correctly,
+ because <productname>Pgpool-II</productname> has to stop all
+ the clients during the 2nd stage of online recovery.
+ If there are several <productname>Pgpool-II</productname> hosts,
+ only one will have received the online recovery command and will
+ block the connections.
+ </para>
+ </note>
<variablelist>
<varlistentry id="guc-recovery-user" xreflabel="recovery_user">
[parent: 81c092ede250]