pgpool2.git / summary / log / commit / refs
commit c1eb6f42b66a2bb52bae02f8b5c5b136708ac4c4
Author: Tatsuo Ishii <ishii@postgresql.org>
Date: Wed May 25 07:38:18 2016 +0000
Tweak documents and add runtime.sgml.
doc/src/sgml/HTML.index | 62 +++++++++++--
doc/src/sgml/bookindex.sgml | 67 +++++++++++++-
doc/src/sgml/history.sgml | 20 +++--
doc/src/sgml/installation.sgml | 192 ++++++++++++++++++++++++++++++++---------
doc/src/sgml/pgpool.sgml | 2 +-
doc/src/sgml/runtime.sgml | 174 +++++++++++++++++++++++++++++++++++++
doc/src/sgml/version.sgml | 2 +-
7 files changed, 460 insertions(+), 59 deletions(-)
diff --git a/doc/src/sgml/HTML.index b/doc/src/sgml/HTML.index
index b6ee43fb2..9845c010e 100644
--- a/doc/src/sgml/HTML.index
+++ b/doc/src/sgml/HTML.index
@@ -8,21 +8,69 @@ PRIMARY history
SECONDARY of pgpool-II
/INDEXTERM
INDEXTERM installation.html
-INDEXPOINT installation.html#AEN168
-TITLE pgpool-IIInstallation from Source Code
+INDEXPOINT installation.html#AEN169
+TITLE pgpool-II Installation from Source Code
significance NORMAL
ZONE installation.html
-TITLE pgpool-IIInstallation from Source Code
+TITLE pgpool-II Installation from Source Code
PRIMARY installation
/INDEXTERM
-INDEXTERM install-source.html#INSTALL-PGPOOL
-INDEXPOINT install-source.html#AEN200
+INDEXTERM install-requirements.html
+INDEXPOINT install-requirements.html#AEN184
+TITLE Requirements
+significance NORMAL
+PRIMARY make
+/INDEXTERM
+INDEXTERM install-requirements.html
+INDEXPOINT install-requirements.html#AEN217
+TITLE Requirements
+significance NORMAL
+PRIMARY flex
+/INDEXTERM
+INDEXTERM install-requirements.html
+INDEXPOINT install-requirements.html#AEN219
+TITLE Requirements
+significance NORMAL
+PRIMARY lex
+/INDEXTERM
+INDEXTERM install-requirements.html
+INDEXPOINT install-requirements.html#AEN221
+TITLE Requirements
+significance NORMAL
+PRIMARY bison
+/INDEXTERM
+INDEXTERM install-requirements.html
+INDEXPOINT install-requirements.html#AEN223
+TITLE Requirements
+significance NORMAL
+PRIMARY yacc
+/INDEXTERM
+INDEXTERM install-pgpool.html
+INDEXPOINT install-pgpool.html#AEN269
TITLE Installing pgpool-II
significance NORMAL
PRIMARY OpenSSL
/INDEXTERM
+INDEXTERM pgpool-ii-user.html
+INDEXPOINT pgpool-ii-user.html#AEN359
+TITLE The pgpool-II User Account
+significance NORMAL
+PRIMARY pgpool-II user
+/INDEXTERM
+INDEXTERM configuring-pcp-conf.html
+INDEXPOINT configuring-pcp-conf.html#AEN370
+TITLE Configuring pcp.conf
+significance NORMAL
+PRIMARY pcp configuration
+/INDEXTERM
+INDEXTERM configuring-pgpool.html
+INDEXPOINT configuring-pgpool.html#AEN389
+TITLE Configuring pgpool
+significance NORMAL
+PRIMARY pgpool-II configuration
+/INDEXTERM
INDEXTERM pcp-common-options.html
-INDEXPOINT pcp-common-options.html#AEN310
+INDEXPOINT pcp-common-options.html#AEN441
TITLE pcp_common_options
significance NORMAL
ZONE pcp-common-options.html
@@ -30,7 +78,7 @@ TITLE pcp_common_options
PRIMARY pcp_common_options
/INDEXTERM
INDEXTERM pcp-node-count.html
-INDEXPOINT pcp-node-count.html#AEN410
+INDEXPOINT pcp-node-count.html#AEN541
TITLE pcp_node_count
significance NORMAL
ZONE pcp-node-count.html
diff --git a/doc/src/sgml/bookindex.sgml b/doc/src/sgml/bookindex.sgml
index 4c3601c70..fbebac270 100644
--- a/doc/src/sgml/bookindex.sgml
+++ b/doc/src/sgml/bookindex.sgml
@@ -19,6 +19,24 @@
sequences of pages into a range.
-->
+<indexdiv><title>B</title>
+
+<indexentry>
+ <primaryie>bison,
+ <ulink url="install-requirements.html" role="AEN221">Requirements</ulink>
+ </primaryie>
+</indexentry>
+
+</indexdiv>
+<indexdiv><title>F</title>
+
+<indexentry>
+ <primaryie>flex,
+ <ulink url="install-requirements.html" role="AEN217">Requirements</ulink>
+ </primaryie>
+</indexentry>
+
+</indexdiv>
<indexdiv><title>H</title>
<indexentry>
@@ -34,7 +52,25 @@
<indexentry>
<primaryie>installation,
- <ulink url="installation.html" role="installation">pgpool-IIInstallation from Source Code</ulink>
+ <ulink url="installation.html" role="installation">pgpool-II Installation from Source Code</ulink>
+ </primaryie>
+</indexentry>
+
+</indexdiv>
+<indexdiv><title>L</title>
+
+<indexentry>
+ <primaryie>lex,
+ <ulink url="install-requirements.html" role="AEN219">Requirements</ulink>
+ </primaryie>
+</indexentry>
+
+</indexdiv>
+<indexdiv><title>M</title>
+
+<indexentry>
+ <primaryie>make,
+ <ulink url="install-requirements.html" role="AEN184">Requirements</ulink>
</primaryie>
</indexentry>
@@ -43,13 +79,19 @@
<indexentry>
<primaryie>OpenSSL,
- <ulink url="install-source.html#INSTALL-PGPOOL" role="AEN200">Installing pgpool-II</ulink>
+ <ulink url="install-pgpool.html" role="AEN269">Installing pgpool-II</ulink>
</primaryie>
</indexentry>
</indexdiv>
<indexdiv><title>P</title>
+<indexentry>
+ <primaryie>pcp configuration,
+ <ulink url="configuring-pcp-conf.html" role="AEN370">Configuring pcp.conf</ulink>
+ </primaryie>
+</indexentry>
+
<indexentry>
<primaryie>pcp_common_options,
<ulink url="pcp-common-options.html" role="pcp-common-options">pcp_common_options</ulink>
@@ -62,5 +104,26 @@
</primaryie>
</indexentry>
+<indexentry>
+ <primaryie>pgpool-II configuration,
+ <ulink url="configuring-pgpool.html" role="AEN389">Configuring pgpool</ulink>
+ </primaryie>
+</indexentry>
+
+<indexentry>
+ <primaryie>pgpool-II user,
+ <ulink url="pgpool-ii-user.html" role="AEN359">The pgpool-II User Account</ulink>
+ </primaryie>
+</indexentry>
+
+</indexdiv>
+<indexdiv><title>Y</title>
+
+<indexentry>
+ <primaryie>yacc,
+ <ulink url="install-requirements.html" role="AEN223">Requirements</ulink>
+ </primaryie>
+</indexentry>
+
</indexdiv>
</index>
diff --git a/doc/src/sgml/history.sgml b/doc/src/sgml/history.sgml
index 3707aee9d..1ff10eea6 100644
--- a/doc/src/sgml/history.sgml
+++ b/doc/src/sgml/history.sgml
@@ -16,21 +16,23 @@
</para>
<para>
In 2004, <productname>pgpool</productname> 1.0 was released with
- the native replication feature. In the same year 2.0 was release
- with load balancing, and support for version 3 frontend/backend
- protocol. In 2005, automated fail over and master slave mode
- support were added.
+ the native replication feature (SQL statement based
+ replication). In the same year 2.0 was released with load
+ balancing, and support for version 3 frontend/backend protocol. In
+ 2005, automated fail over and master slave mode support were added.
</para>
<para>
In 2006, <productname>pgpool</productname>
became <productname>pgpool-II</productname>. The first release 1.0
- eliminated restrictions, for example the number
- of <productname>PostgreSQL</productname> servers were up to 2 in
+ eliminated many of restrictions
+ in <productname>pgpool</productname>, for example the number
+ of <productname>PostgreSQL</productname> servers was up to 2 in
<productname>pgpool</productname>. Also many new features such as
- parallel query mode and PCP commands were added. Probably most
- imporant change between <productname>pgpool</productname>
+ parallel query mode and PCP commands (PCP stands for "Pgpool
+ Control Protocol") were added. Probably the most important change
+ made between <productname>pgpool</productname>
and <productname>pgpool-II</productname> was that the project was
- changed from the personal project to a group project owned by the
+ changed from a personal project to a group project owned by the
Pgpool Developement Group.
</para>
</sect1>
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 330ee9752..0fae455d5 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1,40 +1,155 @@
<!-- doc/src/sgml/installation.sgml -->
<chapter id="installation">
- <title><productname>pgpool-II</productname>Installation from Source Code</title>
+ <title><productname>pgpool-II</productname> Installation from Source Code</title>
<indexterm zone="installation">
<primary>installation</primary>
</indexterm>
- <para>
- This chapter describes the installtion
- of <productname>pgpool-II</productname>. First, installation from
- source code distribution is explained. Then installtion from RPM
- packages is explained.
- </para>
-
<sect1 id="install-source">
- <title>Installing from the soruce code</title>
+ <title>Installation from Source Code</title>
+ <para>
+ This chapter describes the installtion
+ of <productname>pgpool-II</productname>. First, installation from
+ source code distribution is explained. Then installtion from RPM
+ packages is explained.
+ </para>
+ </sect1>
+
+ <sect1 id="install-requirements">
+ <title>Requirements</title>
+
+ <para>
+ In general, a modern Unix-compatible platform should be able to run
+ <productname>pgpool-II</>. Windows is not supported.
+ </para>
+
+ <para>
+ The following software packages are required for building
+ <productname>pgpool-II</>:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>make</primary>
+ </indexterm>
+
+ <acronym>GNU</> <application>make</> version 3.80 or newer is required; other
+ <application>make</> programs or older <acronym>GNU</> <application>make</> versions will <emphasis>not</> work.
+ (<acronym>GNU</> <application>make</> is sometimes installed under
+ the name <filename>gmake</filename>.) To test for <acronym>GNU</acronym>
+ <application>make</application> enter:
+<screen>
+<userinput>make --version</userinput>
+</screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need an <acronym>ISO</>/<acronym>ANSI</> C compiler (at least
+ C89-compliant). Recent
+ versions of <productname>GCC</> are recommended, but
+ <productname>PostgreSQL</> is known to build using a wide variety
+ of compilers from different vendors.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <application>tar</> is required to unpack the source
+ distribution, in addition to either
+ <application>gzip</> or <application>bzip2</>.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ <para>
+ The following packages are optional. They are not required in the
+ default configuration, but they are needed when certain build
+ options are enabled, as explained below:
+ </para>
+
+ <para>
+ If you are building from a <productname>Git</productname> tree instead of
+ using a released source package, or if you want to do server development,
+ you also need the following packages:
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>flex</primary>
+ </indexterm>
+ <indexterm>
+ <primary>lex</primary>
+ </indexterm>
+ <indexterm>
+ <primary>bison</primary>
+ </indexterm>
+ <indexterm>
+ <primary>yacc</primary>
+ </indexterm>
+
+ GNU <application>Flex</> and <application>Bison</>
+ are needed to build from a Git checkout, or if you changed the actual
+ scanner and parser definition files. If you need them, be sure
+ to get <application>Flex</> 2.5.31 or later and
+ <application>Bison</> 1.875 or later. Other <application>lex</>
+ and <application>yacc</> programs cannot be used.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
<para>
- pgpool-II's source code and RPM packages for Red Hat Enterprise
- Linux and CentOS can be downloaded from:
- <ulink url="http://pgpool.net/mediawiki/index.php/Downloads">pgpool development page</ulink>
+ If you need to get a <acronym>GNU</acronym> package, you can find
+ it at your local <acronym>GNU</acronym> mirror site (see <ulink
+ url="http://www.gnu.org/order/ftp.html"></>
+ for a list) or at <ulink
+ url="ftp://ftp.gnu.org/gnu/"></ulink>.
</para>
<para>
- Installing <productname>pgpool-II</productname> from source code
- requires gcc 2.9 or higher, and GNU make. Also, pgpool-II links
- with the libpq library, so the libpq library and its development
- headers must be installed on the machine used to build pgpool-II.
- Additionally the OpenSSL library and its development headers must
- be present in order to enable OpenSSL support in pgpool-II. Also
- the libmemcached library and its development headers must be
- present in order to enable memcached support
- in <productname>pgpool-II</productname>.
+ Also check that you have sufficient disk space. You will need about
+ 40 MB for the source tree during compilation and about 20 MB for
+ the installation directory. If you are going to
+ run the regression tests you will temporarily need up to an extra
+ 4 GB. Use the <command>df</command> command to check free disk
+ space.
</para>
+ </sect1>
+
+ <sect1 id="install-getsource">
+ <title>Getting The Source</title>
- <sect2 id="install-pgpool">
+ <para>
+ The <productname>pgpool-II</> &version; sources can be obtained
+ from the download section of our
+ website: <ulink url="http://www.pgpool.net"></ulink>. You should
+ get a file
+ named <filename>pgpool-II-&version;.tar.gz</filename>. After you
+ have obtained the file, unpack it:
+<screen>
+<userinput>tar xf pgpool-II-&version;.tar.gz</userinput>
+</screen>
+ This will create a directory
+ <filename>pgpool-II-&version;</filename> under the current directory
+ with the <productname>pgpool-II</> sources.
+ Change into that directory for the rest
+ of the installation procedure.
+ </para>
+
+ </sect1>
+
+ <sect1 id="install-pgpool">
<title>Installing pgpool-II</title>
<para>
After extracting the source tarball, execute the configure script.
@@ -134,12 +249,12 @@ make install
will install pgpool-II. (If you use Solaris or FreeBSD, replace make with gmake)
</para>
- </sect2>
+ </sect1>
- <sect2 id="install-pgpool-recovery">
+ <sect1 id="install-pgpool-recovery">
<title>Installing pgpool_recovery</title>
<para>
- This is required all <productname>pgpool-II</productname>
+ This is required in all <productname>pgpool-II</productname>
installation.
<programlisting>
$ cd pgpool-II-x.x.x/sql/pgpool-recovery
@@ -176,9 +291,9 @@ $ pg_ctl reload -D /usr/local/pgsql/data
</programlisting>
</para>
- </sect2>
+ </sect1>
- <sect2 id="install-pgpool-regclass">
+ <sect1 id="install-pgpool-regclass">
<title>Installing pgpool-regclass</title>
<para>
If you are using <productname>PostgreSQL</productname> 9.4 or
@@ -207,20 +322,21 @@ $ make
$ make install
</programlisting>
After this:
+
<programlisting>
-$ psql -f pgpool-regclass.sql template1
+$ psql template1
+=# CREATE EXTENSION pgpool_regclass;
</programlisting>
- or
+or
<programlisting>
-$ psql template1
-=# CREATE EXTENSION pgpool_regclass;
+$ psql -f pgpool-regclass.sql template1
</programlisting>
- Executing <filename>pgpool-regclass.sql</filename>
- or <command>CREATE EXTENSION</command> should be performed on
- every databases accessed
+ Executing <command>CREATE EXTENSION</command>
+ or <filename>pgpool-regclass.sql</filename> should be performed
+ on every databases accessed
with <productname>pgpool-II</productname>. You do not need to
do this for a database created after the execution of
<command>psql -f pgpool-regclass.sql template1</command>
@@ -228,9 +344,9 @@ $ psql template1
database will be cloned to create new databases.
</para>
- </sect2>
+ </sect1>
- <sect2 id="create-installlock-table">
+ <sect1 id="create-installlock-table">
<title>Creating insert_lock table</title>
<para>
If you plan to use native replication mode and insert_lock,
@@ -259,8 +375,6 @@ $ psql template1
<command>psql -f insert_lock.sql template1</command>, as this
template database will be cloned to create new databases.
</para>
- </sect2>
-
- </sect1>
+ </sect1>
</chapter>
diff --git a/doc/src/sgml/pgpool.sgml b/doc/src/sgml/pgpool.sgml
index ba60703d9..56393a21d 100644
--- a/doc/src/sgml/pgpool.sgml
+++ b/doc/src/sgml/pgpool.sgml
@@ -122,9 +122,9 @@
</partintro>
&installation;
+ &runtime;
<!--
&installw;
- &runtime;
&config;
&client-auth;
&user-manag;
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
new file mode 100644
index 000000000..fcaf70b96
--- /dev/null
+++ b/doc/src/sgml/runtime.sgml
@@ -0,0 +1,174 @@
+<!-- doc/src/sgml/runtime.sgml -->
+
+<chapter id="runtime">
+ <title>Server Setup and Operation</title>
+
+ <para>
+ This chapter discusses how to set up and run the pgpool-II server
+ and its interactions with the operating system.
+ </para>
+
+ <sect1 id="pgpool-II-user">
+ <title>The <productname>pgpool-II</productname> User Account</title>
+
+ <indexterm>
+ <primary>pgpool-II user</primary>
+ </indexterm>
+
+ <para>
+ As with any server daemon that is accessible to the outside world,
+ it is advisable to run <productname>pgpool-II</productname> under a
+ separate user account. This user account should only own the data
+ that is managed by the server, and should not be shared with other
+ daemons. (For example, using the user <literal>nobody</literal> is a bad
+ idea.) It is not advisable to install executables owned by this
+ user because compromised systems could then modify their own
+ binaries.
+ </para>
+
+ <para>
+ To add a Unix user account to your system, look for a command
+ <command>useradd</command> or <command>adduser</command>. The user
+ name <systemitem>pgpool</systemitem> is often used, and is assumed
+ throughout this book, but you can use another name if you like.
+ </para>
+ </sect1>
+
+ <sect1 id="configuring-pcp-conf">
+ <title>Configuring pcp.conf</title>
+
+ <indexterm>
+ <primary>pcp configuration</primary>
+ </indexterm>
+
+ <para>
+ <productname>pgpool-II</productname> provides a control interface
+ where an administrator can
+ collect <productname>pgpool-II</productname> status, and terminate
+ <productname>pgpool-II</productname> processes
+ remotely. <filename>pcp.conf</filename> is the user/password file
+ used for authentication by this interface. All operation modes
+ require the <filename>pcp.conf</filename> file to be set. A
+ <filename>$prefix/etc/pcp.conf.sample</filename> file is created
+ during the installation
+ of <productname>pgpool-II</productname>. Rename the file to
+ <filename>pcp.conf</filename> and add your user name and password
+ to it.
+
+ <programlisting>
+cp $prefix/etc/pcp.conf.sample $prefix/etc/pcp.conf
+ </programlisting>
+
+ An empty line or a line starting with "#" is treated as a
+ comment and will be ignored. A user name and its associated
+ password must be written as one line using the following format:
+
+ <programlisting>
+username:[password encrypted in md5]
+ </programlisting>
+
+[password encrypted in md5] can be produced with the $prefix/bin/pg_md5 command.
+
+ <programlisting>
+pg_md5 -p
+password: your_password
+ </programlisting>
+
+or
+
+ <programlisting>
+./pg_md5 foo
+acbd18db4cc2f85cedef654fccc4a4d8
+ </programlisting>
+
+ The <filename>pcp.conf</filename> file must be readable by the
+ user who executes <productname>pgpool-II</productname>.
+ </para>
+
+ </sect1>
+
+ <sect1 id="configuring-pgpool">
+ <title>Configuring pgpool</title>
+
+ <indexterm>
+ <primary>pgpool-II configuration</primary>
+ </indexterm>
+
+ <sect2 id="configuring-pgpool-conf">
+ <title>Configuring pgpool.conf</title>
+
+ <para>
+ <filename>pgpool.conf</filename> is the main configuration file
+ of <productname>pgpool-II</productname>. You need to specify the
+ path to the file when
+ starting <productname>pgpool-II</productname>
+ using <option>-f</option> option.
+ <filename>pgpool.conf</filename> is located
+ at <filename>$prefix/etc/pgpool.conf</filename> by default.
+ </para>
+ </sect2>
+
+ <sect2 id="running-mode">
+ <title>Running mode of pgpool-II</title>
+
+ <para>
+ There are four different running modes in pgpool-II: streaming
+ replication mode, master slave mode, native replication mode and
+ raw mode. In any mode, pgpool-II provides connection pooling,
+ automatic fail over and online recovery. The sample configuration
+ files for each mode are provied. They are located
+ under <filename>$prefix/etc</filename>. You can copy one of them
+ to <filename>$prefix/etc/pgpool.conf</filename>.
+ </para>
+
+ <para>
+ Those modes are exclusive each other and cannot be changed after
+ starting the server. You should make a decision which to use in
+ the early stage of designing the system. If you are not sure, it
+ is recommended to use the streaming replication mode.
+ </para>
+
+ <para>
+ The streaming replication mode can be used with PostgreSQL servers
+ operating streaming replication. In this mode, PostgreSQL is
+ responsible for synchronizing databases. This mode is widely used
+ and most recommended way to use pgpool-II. Load balancing is
+ possible in the mode. The sample configuration file
+ is <filename>$prefix/etc/pgpool.conf.sample-stream</filename>.
+ </para>
+
+ <para>
+ The master slave mode mode can be used with PostgreSQL servers
+ operating Slony. In this mode, PostgreSQL is responsible for
+ synchronizing databases. This Slony is being obsoletd by streaming
+ replication, we do not recommend to use this mode unless you have
+ specific reason to use Slony. Load balancing is possible in the
+ mode. The sample configuration file
+ is <filename>$prefix/etc/pgpool.conf.sample-master-slave</filename>.
+ </para>
+
+ <para>
+ In the native replication mode, pgpool-II is responsible for
+ synchronizing databases. The advantage for the mode is the
+ synchronization is done in synchronous way: writing to the
+ database does not return until all of PostgreSQL servers finish
+ the write operation. Note, however, read snapshot control is not
+ done and consistent visibility is not guaranteed in the mode.
+ Load balancing is possible in the mode. The sample configuration
+ file <filename>$prefix/etc/pgpool.conf.sample-replication</filename>.
+ </para>
+
+ <para>
+ In the raw mode, pgpool-II does not care about the database
+ synchronization. It's user's responsibility to make the whole
+ system does a meaningfull thing. Load balancing
+ is <emphasis>not</emphasis> possible in the mode. The sample
+ configuration
+ file <filename>$prefix/etc/pgpool.conf.sample</filename>.
+ </para>
+
+ </sect2>
+
+ </sect1>
+
+</chapter>
diff --git a/doc/src/sgml/version.sgml b/doc/src/sgml/version.sgml
index ddccb01c0..e4ad341ff 100644
--- a/doc/src/sgml/version.sgml
+++ b/doc/src/sgml/version.sgml
@@ -1 +1 @@
-<!ENTITY version "3.6 alpha1">
+<!ENTITY version "3.6-alpha1">
[parent: a2d04ab99b8b]