8.1. Basic Configuration Example

8.1.1.1. Installing Pgpool-II

Installing Pgpool-II is very easy. In the directory which you have extracted the source tar ball, execute the following commands.

     $ ./configure
     $ make
     $ make install
    

configure script collects your system information and use it for the compilation procedure. You can pass command line arguments to configure script to change the default behavior, such as the installation directory. Pgpool-II will be installed to /usr/local directory by default.

make command compiles the source code, and make install will install the executables. You must have write permission on the installation directory. In this tutorial, we will install Pgpool-II in the default /usr/local directory.

If the configure script displays the following error message, the libpq library may not be installed, or it is not of version 3

     configure: error: libpq is not installed or libpq is old
    

If the library is version 3, but the above message is still displayed, your libpq library is probably not recognized by the configure script. The configure script searches for libpq library under /usr/local/pgsql. If you have installed the PostgreSQL in a directory other than /usr/local/pgsql, use --with-pgsql, or --with-pgsql-includedir and --with-pgsql-libdir command line options when you execute configure.

8.1.1.2. Configuration Files

Pgpool-II configuration parameters are saved in the pgpool.conf file. The file is in "parameter = value" per line format. When you install Pgpool-II, pgpool.conf.sample is automatically created. We recommend copying and renaming it to pgpool.conf, and edit it as you like.

     $ cp /usr/local/etc/pgpool.conf.sample /usr/local/etc/pgpool.conf
    

Pgpool-II only accepts connections from the localhost using port 9999 by the default. If you wish to receive connections from other hosts, set listen_addresses to '*'.

      listen_addresses = 'localhost'
      port = 9999
     

We will use the default parameters in this tutorial.

8.1.1.3. Configuring PCP Commands

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 pcp.conf 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.

     postgres:e8a48653851e28c69d0506508fb27fc5
    

When you install Pgpool-II, pcp.conf.sample is automatically created. We recommend copying and renaming it to pcp.conf, and edit it.

     $ cp /usr/local/etc/pcp.conf.sample /usr/local/etc/pcp.conf
    

To encrypt your password into md5 hash format, use the pg_md5 command, which is installed as one of Pgpool-II's executables. pg_md5 takes text as a command line argument, and displays its md5-hashed text. For example, give "postgres" as the command line argument, and pg_md5 displays md5-hashed text on its standard output.

     $ /usr/local/bin/pg_md5 postgres
     e8a48653851e28c69d0506508fb27fc5
    

PCP commands are executed via network, so the port number must be configured with pcp_port parameter in pgpool.conf file. We will use the default 9898 for pcp_port in this tutorial.

       pcp_port = 9898
      

8.1.1.4. Preparing Database Nodes

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. In this example, we create 3 PostgreSQL servers and specify the PostgreSQL information in the following parameters.

     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
    

For backend_hostname, backend_port, backend_weight, 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..).

8.1.1.5. Starting/Stopping Pgpool-II

To fire up Pgpool-II, execute the following command on a terminal.

     $ pgpool
    

The above command, however, prints no log messages because Pgpool-II detaches the terminal. If you want to show Pgpool-II log messages, you pass -n option to pgpool command so Pgpool-II is executed as non-daemon process, and the terminal will not be detached.

     $ pgpool -n &
    

The log messages are printed on the terminal, so it is recommended to use the following options.

     $ pgpool -n -d > /tmp/pgpool.log 2>&1 &
    

The -d option enables debug messages to be generated. 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:

     $ pgpool -n 2>&1 | /usr/local/apache2/bin/rotatelogs \
     -l -f /var/log/pgpool/pgpool.log.%A 86400 &
    

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:

     55 23 * * * /usr/bin/find /var/log/pgpool -type f -mtime +5 -exec /bin/rm -f '{}' \;
    

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. Also cronolog can be used.

     $ pgpool -n 2>&1 | /usr/sbin/cronolog \
     --hardlink=/var/log/pgsql/pgpool.log \
     '/var/log/pgsql/%Y-%m-%d-pgpool.log' &
    

To stop Pgpool-II execute the following command.

     $ pgpool stop
    

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.

     $ pgpool -m fast stop
    

8.1.2.1. Configuring Replication

To enable the database replication function, set replication_mode to on in pgpool.conf file.

      replication_mode = true
     

When replication_mode is on, Pgpool-II will send a copy of a received query to all the database nodes. In addition, when load_balance_mode is set to true, Pgpool-II will distribute SELECT queries among the database nodes.

	load_balance_mode = true
       

In this section, we will enable both replication_mode and load_balance_mode.

8.1.2.2. Checking Replication

To reflect the above changes in pgpool.conf, Pgpool-II must be restarted. Please refer to "Starting/Stopping Pgpool-II" Section 8.1.1.5. After configuring pgpool.conf and restarting the Pgpool-II, let's try the actual replication and see if everything is working. 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 createdb commands through Pgpool-II, and the database will be created on all the nodes.

      $ createdb -p 9999 bench_replication
     

Then, we'll execute pgbench with -i option. -i option initializes the database with pre-defined tables and data.

      $ pgbench -i -p 9999 bench_replication
     

The following table is the summary of tables and data, which will be created by pgbench -i. If, on all the nodes, the listed tables and data are created, replication is working correctly.

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 pgbench_branches, pgbench_tellers, pgbench_accounts, and pgbench_history tables on all the nodes (5432, 5433, 5434).

     $ for port in 5432 5433 5434; do
     >     echo $port
     >     for table_name in pgbench_branches pgbench_tellers pgbench_accounts pgbench_history; do
     >         echo $table_name
     >         psql -c "SELECT count(*) FROM $table_name" -p $port bench_replication
     >     done
     > done