prestogres 0.1.0

data/pgpool2/doc/pgpool.css

@@ -0,0 +1,280 @@
+ul#navlist
+	{
+	width: 158px>;
+	\width: 160px;
+	w\idth: 158px;
+	padding: 0px;
+	border: 1px solid #808080;
+	border-top: 0px;
+	margin: 0px;
+	font: bold 12px verdana,helvetica,arial,sans-serif;
+	background: #808080;
+	}
+	
+	ul#navlist li
+	{
+	list-style: none;
+	margin: 0px;
+	border: 0px;
+	border-top: 1px solid #808080;
+	font-size:7pt;
+	}
+	
+	ul#navlist li a
+	{
+	display: block;
+	width: 122px;
+	\width: 158px;
+	w\idth: 122px;
+	padding: 4px 8px 4px 8px;
+	border: 0px;
+	border-left: 20px solid #aaaabb;
+	background: #ccccdd;
+	text-decoration: none;
+	text-align: right;
+	
+	}
+	
+	ul#navlist li a:link { color: #666677; }
+	div#navcontainer li a:visited { color: #666677; }
+	
+	ul#navlist li a:hover
+	{
+	border-color: #ff9000;
+	color: #ffffff;
+	background: #000d33;
+	}
+
+	ul#navlist li > ul
+	{
+	margin-left: 0px;
+	padding-left: 0px;
+	}
+	ul#navlist li > ul li a {
+	border-left: 20px solid #B9B9CE;
+	background: #DEDEEF;
+	}
+	
+/* --------------------------- */
+#menu {
+	border-right:1px dotted #cccccc;
+	float: left;
+	padding-top: 20px;
+}
+#navcontainer {
+	margin-bottom: 20px;
+}
+#manual {
+	border-left:1px dotted #cccccc;
+	width: 800px;
+	float: left;
+}
+body {
+	font-family:Verdana, Arial, Helvetica, sans-serif;
+	font-size:9pt;
+	margin: 0px;
+	color: black;
+	border-left: 20px solid #ccc;
+}
+pre {
+	background-color:#f0f0f0;
+	color: brown;
+	padding: 5px;
+	margin-left:40px;
+	margin-right:30px;
+ 	word-wrap: break-word;
+ 	word-break: break-all;
+	overflow: auto;
+}
+h1 {
+	margin-top: 50px;
+	border-bottom: 2px solid #6699CC;
+	padding: 5px;
+	margin-left:10px;
+	background:#6699CC;
+	color: #ffffff;
+}
+h2 {
+	margin-top: 30px;
+	padding: 5px;
+	margin-left:30px;
+	background: #8CD8E2;
+}
+
+h3 {
+	margin-top: 30px;
+	border: 2px solid #8CD8E2;
+	border-left: 10px solid #8CD8E2;
+	padding: 5px;
+	margin-left:40px;
+	background: #F4F8F1;
+}
+
+h4 {
+	border-bottom: 2px solid #8CD8E2;
+	padding: 5px;
+	margin-left:40px;
+	background: #F4F8F1;
+}
+
+p {
+	margin: 3px 25px 3px 40px;
+	text-indent: 1em;
+}
+
+li p, dd p {
+	text-indent: 0em;
+	color: black;
+}
+
+ul, ol,dl {
+	margin-left:40px;
+	padding-right: 30px;
+}
+dt {
+	font-weight:bold;
+}
+
+ul li {
+	padding-right: 30px;
+	list-style:square;
+	color: #663333;
+}
+
+ul li ul li {
+	list-style: circle;
+}
+
+ul li ol li {
+	list-style: decimal;
+}
+
+
+ol li {
+	padding-right: 30px;
+	color: #663333;
+}
+
+
+table {
+	margin-left:40px;
+	border-collapse: collapse;
+	border: #666666 1px solid;
+	margin-bottom: 10px;
+}
+th, td {
+	padding: 5px;
+	font-size:10pt;
+}
+th {
+	font-weight: normal;
+	background-color: #eeeeee;
+}
+th.nodec {
+	text-align: left;
+	white-space: nowrap;
+}
+tr.header th {
+	font-weight: bold;
+	background-color: #cccccc;
+	border-bottom: double;
+}
+tr.center td {
+	text-align: center;
+}
+
+dd {
+	margin-left: 0px;
+}
+	a:link { color: blue; }
+	a:hover { color: red; }
+
+p.top_link {
+	text-align: right;
+}
+p.top_link a {
+	text-decoration: none;
+	border: #aaaaaa 1px solid;
+	border-radius: 3px;
+	background-color: #eeeeee;
+	padding: 1px 5px;
+	color: #666666;
+}
+.header_small {
+	font-size: 0.9em;
+	background-color: #f0f0f0;
+	
+}
+.header_text {
+	border-bottom: 2px solid #663366;
+	padding: 5px;
+	background-color: #E9F8F8;	
+	font-size: 2em;
+	font-weight:bold;
+	padding:25px;
+}
+
+.copyright {
+	padding: 5px;
+	padding:25px;
+	text-align:center;
+}
+.version {
+	font-size: smaller;
+	font-weight: bold;
+	border: 1px solid #B27F00;
+	background-color: orange;
+	padding: 1px 3px;
+	border-radius: 3px;
+	color: white;
+}
+h1 .version {
+	border-radius: 5px;
+	border-color: white;
+}
+.version_notice {
+	border-left: 7px solid orange;
+	border-right: 5px solid orange;
+	padding: 5px;
+}
+.caution {
+	font-weight: bold;
+	color: red;
+}
+dl.flat dt {
+	clear: both;
+	float: left;
+	width: 40px;
+	line-height: 150%;
+}
+dl.flat dd {
+	padding-left: 50px;
+	line-height: 150%;
+}
+dl.flat dd * {
+	margin-left: 0px;
+}
+li dl dt {
+	font-weight: normal;
+	display: list-item;
+	list-style: square outside;
+}
+li dl dd {
+	margin-bottom: 10px;
+}
+ul.flat_ul {
+	margin: 0px;
+	list-style-type: none;
+}
+ul.flat_ul li {
+	display: inline-block;
+	border: 1px solid #666;
+	border-radius: 3px;
+	width: 100px;
+	margin: 3px;
+	padding: 0px;
+	text-align: center;
+}
+ul.flat_ul li a {
+	text-decoration: none;
+}

data/pgpool2/doc/pgpool_remote_start

@@ -0,0 +1,13 @@
+#! /bin/sh
+
+if [ $# -ne 2 ]
+then
+    echo "pgpool_remote_start remote_host remote_datadir"
+    exit 1
+fi
+
+DEST=$1
+DESTDIR=$2
+PGCTL=/usr/local/pgsql/bin/pg_ctl
+
+ssh -T $DEST $PGCTL -w -D $DESTDIR start 2>/dev/null 1>/dev/null < /dev/null &

data/pgpool2/doc/recovery.conf.sample

@@ -0,0 +1,117 @@
+# -------------------------------
+# PostgreSQL recovery config file
+# -------------------------------
+#
+# Edit this file to provide the parameters that PostgreSQL needs to
+# perform an archive recovery of a database, or to act as a log-streaming
+# replication standby.
+#
+# If "recovery.conf" is present in the PostgreSQL data directory, it is
+# read on postmaster startup.  After successful recovery, it is renamed
+# to "recovery.done" to ensure that we do not accidentally re-enter
+# archive recovery or standby mode.
+#
+# This file consists of lines of the form:
+#
+#   name = 'value'
+#
+# (The quotes around the value are NOT optional, but the "=" is.)
+#
+# Comments are introduced with '#'.
+#
+# The complete list of option names and allowed values can be found
+# in the PostgreSQL documentation.
+#
+#---------------------------------------------------------------------------
+# ARCHIVE RECOVERY PARAMETERS
+#---------------------------------------------------------------------------
+#
+# restore_command
+#
+# specifies the shell command that is executed to copy log files
+# back from archival storage.  The command string may contain %f,
+# which is replaced by the name of the desired log file, and %p,
+# which is replaced by the absolute path to copy the log file to.
+#
+# This parameter is *required* for an archive recovery, but optional
+# for streaming replication.
+#
+# It is important that the command return nonzero exit status on failure.
+# The command *will* be asked for log files that are not present in the
+# archive; it must return nonzero when so asked.
+#
+# NOTE that the basename of %p will be different from %f; do not
+# expect them to be interchangeable.
+#
+#restore_command = ''		# e.g. 'cp /mnt/server/archivedir/%f %p'
+#
+#
+# archive_cleanup_command
+#
+# specifies an optional shell command to execute at every restartpoint.
+# This can be useful for cleaning up the archive of a standby server.
+#
+#archive_cleanup_command = ''
+#
+# recovery_end_command
+#
+# specifies an optional shell command to execute at completion of recovery.
+# This can be useful for cleaning up after the restore_command.
+#
+#recovery_end_command = ''
+#
+#---------------------------------------------------------------------------
+# RECOVERY TARGET PARAMETERS
+#---------------------------------------------------------------------------
+#
+# By default, recovery will rollforward to the end of the WAL log.
+# If you want to stop rollforward at a specific point, you
+# must set a recovery target.
+#
+# You may set a recovery target either by transactionId, or
+# by timestamp. Recovery may either include or exclude the
+# transaction(s) with the recovery target value (ie, stop either
+# just after or just before the given target, respectively).
+#
+#recovery_target_time = ''	# e.g. '2004-07-14 22:39:00 EST'
+#
+#recovery_target_xid = ''
+#
+#recovery_target_inclusive = 'true'
+#
+#
+# If you want to recover into a timeline other than the "main line" shown in
+# pg_control, specify the timeline number here, or write 'latest' to get
+# the latest branch for which there's a history file.
+#
+#recovery_target_timeline = 'latest'
+#
+#---------------------------------------------------------------------------
+# STANDBY SERVER PARAMETERS
+#---------------------------------------------------------------------------
+#
+# When standby_mode is enabled, the PostgreSQL server will work as
+# a standby. It tries to connect to the primary according to the
+# connection settings primary_conninfo, and receives XLOG records
+# continuously.
+#
+#standby_mode = 'off'
+#
+#primary_conninfo = ''		# e.g. 'host=localhost port=5432'
+#
+#
+# By default, a standby server keeps streaming XLOG records from the
+# primary indefinitely. If you want to stop streaming and finish recovery,
+# opening up the system in read/write mode, specify path to a trigger file.
+# Server will poll the trigger file path periodically and stop streaming
+# when it's found.
+#
+#trigger_file = ''
+#
+#---------------------------------------------------------------------------
+# HOT STANDBY PARAMETERS
+#---------------------------------------------------------------------------
+#
+# Hot Standby related parameters are listed in postgresql.conf
+#
+#---------------------------------------------------------------------------

data/pgpool2/doc/tutorial-en.html

@@ -0,0 +1,707 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+
+<html>
+
+<head>
+<title>pgpool-II Tutorial</title>
+<meta http-equiv="Content-Type" content="text/html" />
+<link href="pgpool.css" rel="stylesheet" type="text/css" />
+</head>
+
+<body>
+<h1>pgpool-II Tutorial</h1>
+<p>Welcome to the Tutorial for pgpool-II. From here, you can learn how
+to install, setup, and run parallel queries or do replication using
+pgpool-II. We assume that you already know basic PostreSQL operations,
+so please refer to the PostgreSQL document if neccesary.</p>
+
+<dl>
+  <dt><em>Table of Contents</em></dt>
+  <dt>1. <a href="#start">Let's Begin!</a></dt>
+  <dd>1.1. <a href="#install">Installing pgpool-II</a></dd>
+  <dd>1.2. <a href="#config">Configuration Files</a></dd>
+  <dd>1.3. <a href="#pcp-config">Configuring PCP commands</a></dd>
+  <dd>1.4. <a href="#db-node">Preparing Database Nodes</a></dd>
+  <dd>1.5. <a href="#start-shutdown">Starting/Stopping pgpool-II</a></dd>
+  <dt>2. <a href="#replication">Your First Replication</a></dt>
+  <dd>2.1. <a href="#replication-config">Configuring Replication</a></dd>
+  <dd>2.2. <a href="#replication-check">Checking Replication</a></dd>
+  <dt>3. <a href="#parallel">Your First Parallel Query</a></dt>
+  <dd>3.1. <a href="#parallel-config">Configuring Parallel Query</a></dd>
+  <dd>3.2. <a href="#system-db">Configuring the System Database</a></dd>
+  <dd>3.3. <a href="#dist-def">Partitioning Rule Definition</a></dd>
+  <dd>3.4. <a href="#replicate-def">Replication Rule Definition</a></dd>
+  <dd>3.5. <a href="#parallel-check">Checking Parallel Query</a></dd>
+</dl>
+
+
+<h2>1. <a name="start">Let's Begin!</a></h2>
+
+<p>First, we must learn how to install and configure pgpool-II and
+database nodes before using replication or parallel query.</p>
+
+<h3>1.1. <a name="install">Installing pgpool-II</a></h3>
+
+<p>Installing pgpool-II is very easy. In the directory which you have
+extracted the source tar ball, execute the following commands.</p>
+
+<pre>
+$ ./configure
+$ make
+$ make install
+</pre>
+
+<p><code>configure</code> script collects your system information
+and use it for the compilation procedure. You can pass command line
+arguments to <code>configure</code> script to change the default
+behavior, such as the installation directory. pgpool-II will be
+installed to <code>/usr/local</code> directory by default.</p>
+
+<p><code>make</code> command compiles the source code, and <code>make
+install</code> will install the executables. You must have write
+permission on the installation directory.</p>
+
+<p>In this tutorial, we will install pgpool-II in the default
+<code>/usr/local</code> directory.</p>
+
+<p><em>Note</em>: pgpool-II requires libpq library in PostgreSQL 7.4
+or later (version 3 protocol). If the <code>configure</code> script
+displays the following error message, the libpq library may not be
+installed, or it is not of version 3.</p>
+
+<pre>configure: error: libpq is not installed or libpq is old</pre>
+
+<p>If the library is version 3, but the above message is still displayed,
+your libpq library is probably not recognized by
+the <code>configure</code> script.</p>
+
+<p>The <code>configure</code> script searches for libpq library under
+<code>/usr/local/pgsql</code>. If you have installed
+PostgreSQL in a directory other than <code>/usr/local/pgsql</code>,
+use <code>--with-pgsql</code>, or <code>--with-pgsql-includedir</code>
+and <code>--with-pgsql-libdir</code> command line options when you
+execute <code>configure</code>.</p>
+
+<h3>1.2. <a name="config">Configuration Files</a></h3>
+
+<p>pgpool-II configuration parameters are saved in
+the <code>pgpool.conf</code> file. The file is in "<code>parameter =
+value</code>" per line format. When you install pgpool-II,
+<code>pgpool.conf.sample</code> is automatically created. We recommend
+copying and renaming it to <code>pgpool.conf</code>, and edit it as
+you like.</p>
+
+<pre>$ cp /usr/local/etc/pgpool.conf.sample /usr/local/etc/pgpool.conf</pre>
+
+<p>pgpool-II only accepts connections from the local host using port
+9999. If you wish to receive conenctions from other hosts, set
+<code>listen_addresses</code> to '*'.</code></p>
+
+<pre>
+listen_addresses = 'localhost'
+port = 9999
+</pre>
+
+<p>We will use the default parameters in thie tutorial.</p>
+
+<h3>1.3. <a name="pcp-config">Configuring PCP Commands</a></h3>
+
+<p>pgpool-II has an interface for administrative purpose to retrieve
+information on database nodes, shutdown pgpool-II, etc. via
+network. To use PCP commands, user authentication is required. This
+authentication is different from PostgreSQL's user authentication. A
+user name and password need to be defined in the <code>pcp.conf</code>
+file. In the file, a user name and password are listed as a pair on
+each line, and they are separated by a colon (:). Passwords are
+encrypted in md5 hash format.</p>
+
+<pre>postgres:e8a48653851e28c69d0506508fb27fc5</pre>
+<p>
+When you install pgpool-II, <code>pcp.conf.sample</code> is
+automatically created. We recommend copying and renaming it to
+<code>pcp.conf</code>, and edit it.
+</p>
+<pre>$ cp /usr/local/etc/pcp.conf.sample /usr/local/etc/pcp.conf</pre>
+
+<p>To encrypt your password into md5 hash format, use the pg_md5 command,
+which is installed as one of pgpool-II's
+executables. <code>pg_md5</code> takes text as a command line
+argument, and displays its md5-hashed text.</p>
+
+<p>For example, give "postgres" as the command line argument, and
+<code>pg_md5</code> displays md5-hashed text on its standard
+output.</p>
+
+<pre>
+$ /usr/bin/pg_md5 postgres
+e8a48653851e28c69d0506508fb27fc5
+</pre>
+
+<p>PCP commands are executed via network, so the port number must be
+configured with <code>pcp_port</code> parameter in
+<code>pgpool.conf</code> file.</p>
+
+<p>We will use the default 9898 for <code>pcp_port</code> in this tutorial.</p>
+
+<pre>pcp_port = 9898</pre>
+
+<h3>1.4. <a name="db-node">Preparing Database Nodes</a></h3>
+
+<p>Now, we need to set up backend PostgreSQL servers for
+pgpool-II. These servers can be placed within the same host as
+pgpool-II, or on separate machines. If you decide to place the servers
+on the same host, different port numbers must be assigned for each
+server. If the servers are placed on separate machines, they must be
+configured properly so that they can accept network connections from
+pgpool-II.</p>
+
+<p>In this tutorial, we will place three servers within the same host
+as pgpool-II, and assign 5432, 5433, 5434 port numbers
+respectively. To configure pgpool-II, edit <code>pgpool.conf</code> as
+follows.
+
+<pre>
+backend_hostname0 = 'localhost'
+backend_port0 = 5432
+backend_weight0 = 1
+backend_hostname1 = 'localhost'
+backend_port1 = 5433
+backend_weight1 = 1
+backend_hostname2 = 'localhost'
+backend_port2 = 5434
+backend_weight2 = 1
+</pre>
+
+<p>For <code>backend_hostname</code>, <code>backend_port</code>,
+<code>backend_weight</code>, set the node's hostname, port number, and
+ratio for load balancing. At the end of each parameter string, node ID
+must be specified by adding positive integers starting with 0 (i.e. 0,
+1, 2, &hellip;).</p>
+
+<p><code>backend_weight</code> parameters are all 1, meaning that
+SELECT queries are equally distributed among three servers.</p>
+
+<h3>1.5. <a name="start-shutdown">Starting/Stopping pgpool-II</a></h3>
+
+<p>To fire up pgpool-II, execute the following command on a terminal.</p>
+
+<pre>$ pgpool</pre>
+
+<p>The above command, however, prints no log messages because pgpool
+detaches the terminal. If you want to show pgpool log messages, you
+pass <code>-n</code> option to pgpool command so pgpool-II is executed
+as non-daemon process, and the terminal will not be detached.
+</p>
+
+<pre>
+$ pgpool -n &
+</pre>
+
+<p>
+The log messages are printed on the terminal, so the recommended
+options to use the following.
+</p>
+
+<pre>$ pgpool -n -d &gt; /tmp/pgpool.log 2&gt;&1 &</pre>
+
+<p>The <code>-d</code> option enables debug messages to be generated.</p>
+
+<p>
+The above command keeps appending log messages to /tmp/pgpool.log. If
+you need to rotate log files, pass the logs to a external command
+which has log rotation function. 
+
+For example, you can use rotatelogs from Apache2:
+<pre>
+$ pgpool -n 2>&1 | /usr/local/apache2/bin/rotatelogs \
+  -l -f /var/log/pgpool/pgpool.log.%A 86400 &
+</pre>
+This will generate a log file named "pgpool.log.Thursday" then
+rotate it 00:00 at midnight. Rotatelogs adds logs to a file if it already
+exists. To delete old log files before rotation, you could use cron:
+<pre>
+55 23 * * * /usr/bin/find /var/log/pgpool -type f -mtime +5 -exec /bin/rm -f '{}' \;
+</pre>
+Please note that rotatelogs may exist as /usr/sbin/rotatelogs2 in some
+distributions.
+-f option generates a log file as soon as rotatelogs starts and is
+available in apache2 2.2.9 or greater.
+</p>
+<p>
+Also <a
+href="http://www.cronolog.org"><code>cronolog</code></a> can be used.
+</p>
+
+<pre>
+$ pgpool -n 2>&1 | /usr/sbin/cronolog \
+  --hardlink=/var/log/pgsql/pgpool.log \
+  '/var/log/pgsql/%Y-%m-%d-pgpool.log' &
+</pre>
+
+<p>To stop pgpool-II, execute the following command.</p>
+
+<pre>$ pgpool stop</pre>
+
+<p>If any client is still connected, pgpool-II waits for it to
+disconnect, and then terminates itself. Run the following command
+instead if you want to shutdown pgpool-II forcibly.
+
+<pre>$ pgpool -m fast stop</pre>
+
+<h2>2. <a name="replication">Your First Replication</a></h2>
+
+<p>Replication enables the same data to be copied to multiple database
+nodes.</p>
+
+<p>In this section, we'll use three database nodes, which we have
+already set up in section "1. <a href="#start">Let's Begin!</a>", and
+takes you step by step to create a database replication system. Sample
+data to be replicated will be generated by the pgbench benchmark
+program.</p>
+
+<h3>2.1. <a name="replication-config">Configuring Replication</a></h3>
+
+<p>To enable the database replication function, set
+<code>replication_mode</code> to true in <code>pgpool.conf</code>
+file.</p>
+
+<pre>replication_mode = true</pre>
+
+<p>When <code>replication_mode</code> is set to true, pgpool-II will send a
+copy of a received query to all the database nodes.</p>
+
+<p>When <code>load_balance_mode</code> is set to true, pgpool-II will
+distribute SELECT queries among the database nodes.</p>
+
+<pre>load_balance_mode = true</pre>
+
+<p>In this section, we enable both <code>replication_mode</code> and
+<code>load_balance_mode</code>.</p>
+
+<h3>2.2. <a name="replication-check">Checking Replication</a></h3>
+
+<p>To reflect the changes in <code>pgpool.conf</code>, pgpool-II must
+be restarted. Please refer to section "1.5 <a
+href="#start-shutdown">Starting/Stopping pgpool-II</a>".</p>
+
+<p>After configuring <code>pgpool.conf</code> and restarting
+pgpool-II, let's try the actual replication and see if everything is
+working.</p>
+
+<p>First, we need to create a database to be replicated. We will name
+it "bench_replication". This database needs to be created on all the
+nodes. Use the <code>createdb</code> commands through pgpool-II, and the
+database will be created on all the nodes.</p>
+
+<pre>$ createdb -p 9999 bench_replication</pre>
+
+<p>Then, we'll execute pgbench with <code>-i</code>
+option. <code>-i</code> option initializes the database with
+pre-defined tables and data.</p>
+
+<pre>$ pgbench -i -p 9999 bench_replication</pre>
+
+<p>The following table is the summary of tables and data, which will
+be created by <code>pgbench -i</code>. If, on all the nodes, the
+listed tables and data are created, replication is working correctly.
+
+<table border="1" align="center">
+<tr>
+<th>Table Name</th>
+<th>Number of Rows</th>
+</tr>
+<tr>
+<td>branches</td>
+<td>1</td>
+</tr>
+<tr>
+<td>tellers</td>
+<td>10</td>
+</tr>
+<tr>
+<td>accounts</td>
+<td>100000</td>
+</tr>
+<tr>
+<td>history</td>
+<td>0</td>
+</tr>
+</table>
+
+<p>Let's use a simple shell script to check the above on all the
+nodes. The following script will display the number of rows in
+branches, tellers, accounts, and history tables on all the nodes (5432,
+5433, 5434).</p>
+
+<pre>$ for port in 5432 5433 5434; do
+&gt;     echo $port
+&gt;     for table_name in branches tellers accounts history; do
+&gt;         echo $table_name
+&gt;         psql -c &quot;SELECT count(*) FROM $table_name&quot; -p $port bench_replication
+&gt;     done
+&gt; done
+</pre>
+
+<h2>3. <a name="parallel">Your First Parallel Query</a></h2>
+<p>
+Data within the range is stored in two or more data base nodes in a parallel Query. This is called a partitioning. 
+Moreover you could replicate some of tables among database nodes even
+in parallel query mode.
+</p>
+
+<p>To enable parallel query in pgpool-II, you must set up another
+database called "System Database" (we will denote it as SystemDB from
+this point).</p>
+
+<p>SystemDB holds the user-defined rules to decide what data will be
+saved in which database node. Another use of SystemDB is to merge
+results sent back from the database nodes using dblink.</p>
+
+<p>In this section, we will use three database nodes which we have set
+up in section "1. <a href="#start">Let's Begin!</a>", and takes you
+step by step to create a parallel query database system. We will use
+pgbench again to create sample data.</p>
+
+<h3>3.1. <a name="parallel-config">Configuring Parallel Query</a></h3>
+
+<p>To enable the parallel query function, set <code>parallel_mode</code> to true in <code>pgpool.conf</code> file.</p>
+
+<pre>parallel_mode = true</pre>
+
+<p>Setting <code>paralle_mode</code> to true does not start parallel
+query automatically. pgpool-II needs SystemDB and the rules
+to know how to distribute data to the database nodes.</p>
+
+<p>Also, dblink used by SystemDB makes connections to
+pgpool-II. Therefore, <code>listen_addresses</code> needs to be
+configured so that pgpool-II accepts those connections.</p>
+
+<pre>listen_addresses = '*'</pre>
+
+<p>
+Attention: The replication is not done for the table that does the partitioning
+though a parallel Query and the replication can be made effective at the same time. 
+
+<p>
+Attention: You can have both partitioned tables and replicated
+tables. However a table cannot be a partioned and replicated at
+the same time. Because the data structure of partioned tables and
+replicated tables is different, "bench_replication" database created
+in section "2. <a href="#replication">Your First Replication</a>"
+cannot be reused in parallel query mode.</p>
+
+<pre>
+replication_mode = true
+load_balance_mode = false
+</pre>
+<p>
+OR
+</p>
+<pre>
+replication_mode = false
+load_balance_mode = true
+</pre>
+
+<p>In this section, we will set <code>parallel_mode and load_balance_mode</code> to true,
+<code>listen_addresses</code> to '*', <code>replication_mode</code>to false.</p>
+
+<h3>3.2. <a name="system-db">Configuring SystemDB</a></h3>
+
+<p> "System database" is just an ordinaly database. The only
+requirement is that dblink functions and the dist_def table, which
+describes partioning rule, must be installed in the system
+database. You could have a system database on a database node, or you
+could have multiple nodes having system database by using cascade
+configuration in pgpool-II.  </p>
+
+<p>In this section, we will create SystemDB on the 5432 port
+node. The following list is the configuration parameters for
+SystemDB</p>
+
+<pre>
+system_db_hostname = 'localhost'
+system_db_port = 5432
+system_db_dbname = 'pgpool'
+system_db_schema = 'pgpool_catalog'
+system_db_user = 'pgpool'
+system_db_password = ''
+</pre>
+
+<p>Actually, the above are the default settings of
+<code>pgpool.conf</code>. Now, we must create a user called "pgpool",
+and a database called "pgpool" owned by user "pgpool".</p>
+
+<pre>
+$ createuser -p 5432 pgpool
+$ createdb -p 5432 -O pgpool pgpool
+</pre>
+
+<h4><p>3.2.1. Installing dblink</p></h4>
+
+<p>Next, we must install dblink into "pgpool" database. dblink is one
+of the tools included in the <code>contrib</code> directory in the
+PostgreSQL source code.</p>
+
+<p>To install dblink to your system, execute the following commands.</p>
+
+<pre>
+$ USE_PGXS=1 make -C contrib/dblink
+$ USE_PGXS=1 make -C contrib/dblink install
+</pre>
+
+<p>After dblink has been installed into your system, we will define
+dblink functions in the "pgpool" database. If PostgreSQL is installed in
+<code>/usr/local/pgsql</code>, <code>dblink.sql</code> (a file with
+function definitions) should have been installed in
+<code>/usr/local/pgsql/share/contrib</code>. Now, execute the
+following command to define dblink functions.</p>
+
+<pre>$ psql -f /usr/local/pgsql/share/contrib/dblink.sql -p 5432 pgpool</pre>
+
+<h4><p>3.2.2. Defining dist_def table</p></h4>
+<p>
+Define a table called "dist_def", which has the partitioning rule, in
+database called "pgpool".
+After installing pgpool-II, you will have <code>system_db.sql</code>,
+which is the <code>psql</code> script to generate the system database.
+</p>
+<pre>
+$ psql -f /usr/local/share/system_db.sql -p 5432 -U pgpool pgpool
+</pre>
+<p>
+dist_def table is created in pgpool_catalog schema.
+If you have configured
+<code>system_db_schema</code> to use other schema, you need to edit
+<code>system_db.sql</code> accordingly.</p>
+
+<p>The definition for "dist_def" is as shown here, and the table name
+cannot be changed.</p>
+
+<pre>
+CREATE TABLE pgpool_catalog.dist_def (
+    dbname text, -- database name
+    schema_name text, -- schema name
+    table_name text, -- table name
+    col_name text NOT NULL CHECK (col_name = ANY (col_list)), -- distribution key-column
+    col_list text[] NOT NULL, -- list of column names
+    type_list text[] NOT NULL, -- list of column types
+    dist_def_func text NOT NULL, -- distribution function name
+    PRIMARY KEY (dbname, schema_name, table_name)
+);
+</pre>
+
+<p>A tuple stored in "dist_def" can be classified into two types.</p>
+
+<ul>
+<li>Distribution Rule (col_name, dist_def_func)</li>
+<li>Table's meta-information (dbname, schema_name, table_name, col_list, type_list)</li>
+</ul>
+
+<p>A distribution rule decides how to distribute data to a
+particular node. Data will be distributed depending on the value of
+the "col_name" column. "dist_def_func" is a function that takes the value
+of "col_name" as its argument, and returns an integer which
+points to the appropriate database node ID where the data should be
+stored.</p>
+
+<p>A meta-information is used to rewrite queries. Parallel query
+must rewrite queries so that the results sent back from the backend
+nodes can be merged into one result.</p>
+
+<h4><p>3.2.3. Defining replicate_def table</p></h4>
+<p>
+If you want to use replicated tables in SELECT in parallel mode, you
+need to register information about such tables(replication rule) to a table
+called replicate_def.
+The replicate_def table has already been made when making it from the 
+system_db.sql file when dist_def is defined. 
+The replicate_def table is defined as follows.
+</p>
+<pre>
+CREATE TABLE pgpool_catalog.replicate_def (
+    dbname text, -- database name
+    schema_name text, -- schema name
+    table_name text, -- table name
+    col_list text[] NOT NULL, -- list of column names
+    type_list text[] NOT NULL, -- list of column types
+    PRIMARY KEY (dbname, schema_name, table_name)
+);
+</pre>
+<p>
+replicate_def includes table's meta data information(dbname, schema_name, table_name, col_list, type_list).
+</p>
+<p>
+All the query analysis and query rewriting process are dependent on the
+information (table, column and type) stored in dist_def and/or
+replicate_def table.  If the information is not correct, analysis and
+query rewriting process will produce wrong results.
+</p>
+
+<h3>3.3. <a name="dist-def">Defining Distribution Rules</a></h3>
+
+<p>In this tutorial, we will define rules to distribute pgbench's
+sample data into three database nodes. The sample data will be created
+by "pgbench -i -s 3" (i.e. scale factor of 3). We will create a new
+database called "bench_parallel" for this section.</p>
+
+<p>In pgpool-II's source code, you can find the
+<code>dist_def_pgbench.sql</code> file in <code>sample</code>
+directoy. We will use this sample file here to create distribution
+rules for pgbench. Execute the following command in extracted
+pgpool-II source code directory.</p>
+
+<pre>$ psql -f sample/dist_def_pgbench.sql -p 5432 pgpool</pre>
+
+<p>Here is the explanation of <code>dist_def_pgbench.sql</code>.</p>
+
+<p>Inside <code>dist_def_pgbench.sql</code>, we are inserting one
+row into "dist_def" table. There is a distribution
+function for accounts table. 
+For the key-column, aid is defined for accounts respectively (which is the primary keys)</p>
+
+<pre>
+INSERT INTO pgpool_catalog.dist_def VALUES (
+    'bench_parallel',
+    'public',
+    'accounts',
+    'aid',
+    ARRAY['aid', 'bid', 'abalance', 'filler'],
+    ARRAY['integer', 'integer', 'integer', 'character(84)'],
+    'pgpool_catalog.dist_def_accounts'
+);
+</pre>
+
+<p>Now, we must define the distribution function for the accounts table. Note
+that you can use the same function from different tables. Also, you
+can define functions using languages other than SQL (e.g. PL/pgSQL,
+PL/Tcl, etc.).</p>
+
+<p>
+The accounts table when data is initialized specifying 3 scale factor,
+The value of the aid is 1 to 300000.
+The function is defined so that data is evenly distributed to three data base nodes. 
+</p>
+<p>
+An SQL function will be defined as the return of the number of the data base node. 
+</p>
+
+</p>
+<pre>CREATE OR REPLACE FUNCTION pgpool_catalog.dist_def_branches(anyelement)
+RETURNS integer AS $$
+    SELECT CASE WHEN $1 &gt; 0 AND $1 &lt;= 1 THEN 0
+        WHEN $1 &gt; 1 AND $1 &lt;= 2 THEN 1
+        ELSE 2
+    END;
+$$ LANGUAGE sql;
+</pre>
+
+<h3>3.4. <a name="replicate-def">Defining Replication Rules</a></h3>
+<p>
+The replication rule is the one that which table decides the replication whether to be done. 
+</p>
+
+<p>
+Here, it is made with pgbench With the branches table and  tellers  table are registered.
+
+As a result, the accounts table and the inquiry that uses the branches table 
+and the tellers table become possible. 
+</p>
+<pre>
+INSERT INTO pgpool_catalog.replicate_def VALUES (
+    'bench_parallel',
+    'public',
+    'branches',
+    ARRAY['bid', 'bbalance', 'filler'],
+    ARRAY['integer', 'integer', 'character(88)']
+);
+
+INSERT INTO pgpool_catalog.replicate_def VALUES (
+    'bench_parallel',
+    'public',
+    'tellers',
+    ARRAY['tid', 'bid', 'tbalance', 'filler'],
+    ARRAY['integer', 'integer', 'integer', 'character(84)']
+);
+</pre>
+<p>
+Replicate_def_pgbench.sql is prepared in sample directory.
+
+In the directory that progresses the source code to define a replicate rule by using this as follows The psql command is executed. 
+</p>
+<pre>
+$ psql -f sample/replicate_def_pgbench.sql -p 5432 pgpool
+</pre>
+
+<h3>3.5. <a name="parallel-check">Checking Parallel Query</a></h3>
+
+<p>To reflect the changes in <code>pgpool.conf</code>, pgpool-II must
+be restarted. Please refer to section "1.5 <a
+href="#start-shutdown">Starting/Stopping pgpool-II</a>".</p>
+
+<p>After configuring <code>pgpool.conf</code> and restarting
+pgpool-II, let's try and see if parallel query is working.</p>
+
+<p>First, we need to create a database to be distributed. We will name
+it "bench_parallel". This database needs to be created on all the
+nodes. Use the <code>createdb</code> commands through pgpool-II, and the
+databases will be created on all the nodes.</p>
+
+<pre>$ createdb -p 9999 bench_parallel</pre>
+
+<p>Then, we'll execute pgbench with <code>-i -s 3</code>
+options. <code>-i</code> option initializes the database with
+pre-defined tables and data. <code>-s</code> option specifies the
+scale factor for initialization.</p>
+
+<pre>$ pgbench -i -s 3 -p 9999 bench_parallel</pre>
+
+<p>The tables and data created are shown in "3.3. <a
+href="#dist-def">Defining Distribution Rules</a>".</p>
+
+<p>One way to check if the data have been distributed correctly is to
+execute a SELECT query via pgpool-II and directly on the backend, and
+compare two results. If everything is configured right,
+"bench_parallel" should be distributed as follows.</p>
+
+<table border="1" align ="center">
+<tr>
+<th >Table Name</th>
+<th >the number of lines</th>
+</tr>
+<tr>
+		<td>branches</td>
+		<td>3</td>
+</tr>
+<tr>
+		<td>tellers</td>
+		<td>30</td>
+</tr>
+<tr>
+		<td>accounts</td>
+		<td>300000</td>
+</tr>
+<tr>
+		<td>history</td>
+		<td>0</td>
+</tr>
+</table>
+
+<p>Let's use a simple shell script to check the above on all the nodes
+and via pgpool-II. The following script will display the minimum and
+maximum values in accounts table using port 5432, 5433, 5434, and
+9999.</p>
+
+<pre>$ for port in 5432 5433 5434 9999; do
+&gt;     echo $port
+&gt;     psql -c &quot;SELECT min(aid), max(aid) FROM accounts&quot; -p $port bench_parallel
+&gt; done
+</pre>
+
+<div class="copyright">
+<hr>
+<copyright>
+Copyright &copy; 2003 &ndash; 2011 pgpool Global Development Group
+</copyright>
+</div>
+</body>
+</html>