pgpool2.git / summary / log / commit / refs
commit a50fd59cadfa16f1b0b26bcd6fc4ed626e50b5d8
Author: Tatsuo Ishii <ishii@postgresql.org>
Date: Tue Sep 13 09:01:30 2016 +0000
Write some SGML documents.
doc/src/sgml/config.sgml | 2 +-
doc/src/sgml/connection-pooling.sgml | 64 +++++++++++++
doc/src/sgml/connection-settings.sgml | 174 ++++++++++++++++++++++++++++++++++
3 files changed, 239 insertions(+), 1 deletion(-)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 9298ecc84..c6f1810bc 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -10,7 +10,7 @@
<para>
There are many configuration parameters that affect the behavior of
- the database system. In the first section of this chapter we
+ <productname>Pgpool-II</productname>. In the first section of this chapter we
describe how to interact with configuration parameters. The subsequent sections
discuss each parameter in detail.
</para>
diff --git a/doc/src/sgml/connection-pooling.sgml b/doc/src/sgml/connection-pooling.sgml
index 5ddaa0d93..9ed3e60c9 100644
--- a/doc/src/sgml/connection-pooling.sgml
+++ b/doc/src/sgml/connection-pooling.sgml
@@ -3,8 +3,72 @@
<sect1 id="runtime-config-connection-pooling">
<title>Connection Pooling</title>
+ <para>
+ <productname>Pgpool-II</productname> maintains established
+ connections to the PostgreSQL servers, and reuses them whenever a
+ new connection with the same properties (i.e. user name, database,
+ 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>
+
+ <variablelist>
+
+ <varlistentry id="guc-connection-cache" xreflabel="connection_cache">
+ <term><varname>connection_cache</varname> (<type>boolean</type>)
+ <indexterm>
+ <primary><varname>connection_cache</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Caches connections to backends when set to on. Default is on.
+ <emphasis>However, connections to template0, template1, postgres and
+ regression databases are not cached even if connection_cache is
+ on.</emphasis>
+ </para>
+ <para>
+ You need to restart <productname>Pgpool-II</productname>
+ if you change this value.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-max-pool" xreflabel="max_pool">
+ <term><varname>max_pool</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>max_pool</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ The maximum number of cached connections
+ in <productname>Pgpool-II</productname> children
+ processes. <productname>Pgpool-II</productname> reuses the
+ cached connection if an incoming connection is connecting
+ to the same database with the same user name. If not,
+ <productname>Pgpool-II</productname> creates a new
+ connection to the backend. If the number of cached
+ connections exceeds max_pool, the oldest connection will
+ be discarded, and uses that slot for the new connection.
+ </para>
+ <para>
+ Default value is 4. Please be aware that the number of
+ connections from pgpool-II processes to the backends may reach
+ num_init_children * max_pool.
+ </para>
+ <para>
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
</sect1>
diff --git a/doc/src/sgml/connection-settings.sgml b/doc/src/sgml/connection-settings.sgml
index ed013620a..c6b82c11b 100644
--- a/doc/src/sgml/connection-settings.sgml
+++ b/doc/src/sgml/connection-settings.sgml
@@ -3,6 +3,10 @@
<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>
@@ -28,6 +32,176 @@
</para>
</listitem>
</varlistentry>
+
+ <varlistentry id="guc-port" xreflabel="port">
+ <term><varname>port</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>port</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ The port number used
+ by <productname>Pgpool-II</productname> to listen for
+ connections. Default is 9999.
+ </para>
+ <para>
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-socket-dir" xreflabel="socket_dir">
+ <term><varname>socket_dir</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>socket_dir</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ The directory where the UNIX domain socket accepting connections for
+ <productname>Pgpool-II</productname> will be
+ created. Default is <literal>/tmp</literal>. Be aware that this
+ socket might be deleted by a cron job. We recommend to set this
+ value to <literal>/var/run</literal> or such directory.
+ </para>
+ <para>
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-pcp-listen-addresses" xreflabel="pcp_listen_addresses">
+ <term><varname>pcp_listen_addresses</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>pcp_listen_addresses</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Specifies the hostname or IP address, on which pcp process
+ will accept TCP/IP connections. <literal>*</literal>
+ accepts all incoming connections. <literal>"" </literal>
+ disables TCP/IP connections. Default
+ is <literal>*</literal>. Connections via UNIX domain
+ socket are always accepted.
+ </para>
+ <para>
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-pcp-port" xreflabel="pcp_port">
+ <term><varname>pcp_port</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>pcp_port</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ The port number used by <productname>PCP</productname>
+ process to listen for connections. Default is 9898.
+ </para>
+ <para>
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-pcp-socket-dir" xreflabel="pcp_socket_dir">
+ <term><varname>pcp_socket_dir</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>pcp_socket_dir</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ The directory where the UNIX domain socket accepting connections for
+ <productname>PCP</productname> process will be
+ created. Default is <literal>/tmp</literal>. Be aware that
+ this socket might be deleted by a cron job. We recommend
+ to set this value to <literal>/var/run</literal> or such
+ directory.
+ </para>
+ <para>
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-num-init-children" xreflabel="num_init_children">
+ <term><varname>num_init_children</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>num_init_children</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ The number of
+ preforked <productname>Pgpool-II</productname> server
+ processes. Default is 32. num_init_children is also the
+ concurrent connections limit
+ to <productname>Pgpool-II</productname> from clients. If
+ more than num_init_children clients try to connect to
+ <productname>Pgpool-II</productname>, <emphasis>they are
+ 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.
+ </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
+ 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
+ "netstat -s" command. If you find something like:
+ <programlisting>
+535 times the listen queue of a socket overflowed
+ </programlisting>
+ then the listen queue is definitely overflowed.
+ You should increase the backlog in this case (you will be required a super user privilege).
+ <programlisting>
+# sysctl net.core.somaxconn
+net.core.somaxconn = 128
+# sysctl -w net.core.somaxconn = 256
+ </programlisting>
+You could add following to /etc/sysctl.conf instead.
+ <programlisting>
+net.core.somaxconn = 256
+ </programlisting>
+ </para>
+ <para>
+ Number of connections to each PostgreSQL is roughly max_pool*num_init_children.
+ </para>
+
+ <para>
+ Canceling a query creates another
+ connection to the backend; thus, a query cannot be canceled if
+ all the connections are in use. If you want to ensure that queries can
+ be canceled, set this value to twice the expected connections.
+ </para>
+ <para>
+ <productname>PostgreSQL</productname> allows concurrent
+ connections for non superusers up to max_connections -
+ superuser_reserved_connections.
+ </para>
+ <para>
+ In summary, max_pool, num_init_children, max_connections,
+ superuser_reserved_connections must satisfy the following formula:
+ <programlisting>
+max_pool*num_init_children <= (max_connections - superuser_reserved_connections) (no query canceling needed)
+max_pool*num_init_children*2 <= (max_connections - superuser_reserved_connections) (query canceling needed)
+ </programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</sect2>
</sect1>
[parent: 352bba0c5399]