PostgreSQL, Inc. Confidential Document Commercially Sensitive
Do Not Distribute


PostgreSQL Inc.

Enterprise Replication Server 1.2

Installation Guide



1   INTRODUCTION 3
  1.1 General 3
  1.2

 Useful Internet Links 3
2

REQUIREMENTS 4
3

OVERVIEW 5
4   INSTALL THE ERSERVER SOFTWARE 6
  4.1 Create a unix account for eRServer 6
  4.2 Compile and install eRServer 7
  4.3

 Add eRServer commands to your PATH environment variable 7
5   INSTALLATION OF ERSERVER 8
  5.1 Add the PL/pgSQL language to your master database 8
  5.2

 Initial creation of the Replication information tables in the master and slave databases 8
6   INSTALLATION OF ERSERVER ON ADDITIONAL SLAVE DATABASES 9
  6.1

 Creation of the Replication information tables in the slave database(s) 9
7   ADDING TABLES TO THE REPLICATION LIST 10
  7.1 Adding tables 10
  7.2

 Things to remember 10
8   SECURING THE ERSERVER INSTALLATION 11
  8.1 Ensure the replication.cfg file is only readable by the erserver user 11
  8.2

 Ensure the log files are only readable by the erserver user 11
9   STARTING AND STOPPING ERSERVER 12
  9.1 Starting eRServer 12
  9.2

 Stopping eRServer 12
10   Monitoring eRServer 13
  10.1

 The log files 13
11   TUNING ERSERVER INSTALLATIONS 14
  11.1 Tuning PostgreSQL 14
  11.2 Sizing the Java Virtual Machine 14
  11.3

 Data integrity across server crashes on slave databases 14
12   FINAL CHECKLIST 15
  12.1 Ensure debug and verbose mode are turned off in the replication.cfg file 15




1 INTRODUCTION

1.1 General

This document details the installation and configuration of PostgreSQL Inc.'s Enterprise Replication Server (eRServer).  It is geared to an intended audience of System Installers, Unix Administrators and Security Managers / Officers within PostgreSQL, Inc. project and technical support teams.


1.2 Useful Internet Links

eRServer http://www.erserver.com
PostgreSQL http://www.postgresql.org
PostgreSQL, Inc. http://www.pgsql.com
Perl DBD::Pg http://www.perl.com/CPAN-local/modules/by-category/07_Database_Interfaces/DBD/




REQUIREMENTS

A supported Operating System * The Perl DBD:Pg libraries are available from:
http://www.perl.com/CPAN-local/modules/by-category/07_Database_Interfaces/DBD/



OVERVIEW

This section gives an overview of eRServer in an n-tier environment.

This diagram illustrates that those Data processors needing write access to the data use the Master database, whilst the bulk of database access (read only transactions and aggregate queries) access the Slave databases, updated by eRServer.

 In addition to the disaster recovery and business continuity capabilities that replication provides, eRServer enables the offloading of database activity from a single PostgreSQL database server, spreading it across many.  Other supported functions for a Multi-Slave setup include creating Test Environments for live loading of real data, and to support specialized business applications such as EIS/DSS Servers.




INSTALL THE ERSERVER SOFTWARE

Create a unix account for eRServer

For maximum flexibility and security we recommend you create a unix "erserver" user and unix "erserver" group for the eRServer software to be controlled by.

For Solaris and Linux:

# groupadd erserver

# useradd -g erserver

For FreeBSD:

# pw groupadd erserver

# pw user add -m -n erserver

Compile and install eRServer

Extract the eRServer 1.2 tar file in a temporary installation directory.

$ tar xfz erserver12.tar.gz

Enter the extracted directory:

$ cd erserver

Configure the source code:

$ ./configure --with-pgincludes=/opt/pgsql

You need to tell the configuration script where PostgreSQL is installed by including the --with-pgincludes parameter.  In this example, PostgreSQL was already installed in /opt/pgsql.  Optionally, if you want eRServer to install it's files in a specific directory, you can tell it where by using the --prefix parameter in the above command.

For example, if you had wanted eRServer to install it's files in the /opt/erserver directory instead of the default, you would have run this configure command instead:

$ ./configure --prefix=/opt/erserver --with-pgincludes=/opt/pgsql

Compile the configured source code:

$ make

Install the eRServer software in the target installation directory:

$ su
# make install
# exit
$

Add eRServer commands to your PATH environment variable

It is important to add the eRServer commands in the bin subdirectory of your eRServer installation to the environment path for your erserver user. The method of doing this varies depending upon operating system and isn't covered in this manual.



INSTALLATION OF ERSERVER

Add the PL/pgSQL language to your master database

The PostgreSQL functions needed by eRServer are written in the procedural language PL/pgSQL. You need to enable this language for each master database by using this command:

$ createlang plpgsql masterdb

An alternative method is to enable PL/pgSQL for the special template1 database, and any subsequent databases (including the master database) created after this will automatically have it enabled.

$ createlang plpgsql template1

Initial creation of the Replication information tables in the master and slave databases

Each master and slave database uses several tables to hold and co-ordinate the replication.  You should create these up by running the ers_setup script, passing it the needed parameters.

Parameter Description
--masterserver The name of the server that the master database is on.
--masterport The TCP port number that the master database is on. The default is 5432.
--masterdb The name of the master database.
--masteruser The PostgreSQL username to connect to the master database with.
--masterpass The password for the master database user.
--slaveserver The name of the server that the first slave database is on.
--slaveport The TCP port number that the first slave database is on.  The default is 5432.
--slavedb The name of the first slave database.
--slaveuser The PostgreSQL username to connect to the first slave database with.
--slavepass The password for the first slave database user.


For example:

$ ers_setup --masterserver=servername \
   --masterdb=accounts --masteruser=someuser \
   --masterpass=apasswd --slaveserver=otherserver \
   --slavedb=erp --slaveuser=anotheruser --slavepass=foo



INSTALLATION OF ERSERVER ON ADDITIONAL SLAVE DATABASES

This needs to be done for each slave database.

Creation of the Replication information tables in the slave database(s)

Each slave database uses two tables for holding replication co-ordination data, created by running the ers_addslave command and telling it how to connect to the slave database.

The connection information you give is also saved to eRServer's replication.cfg file, so the new slave database will be included in the replication process with the next restart of eRServer.

A point to note is that the owner of the slave database needs to have PostgreSQL super-user status.

$ ers_addslave --slaveserver=slavehost --slavedb=dbname --slaveuser=slaveuser --slavepass=slavepw



ADDING TABLES TO THE REPLICATION LIST

Adding tables

Adding tables to the replication list is done with the ers_addtable command.  You tell it the name of the table you want added to the replication list, then it will automatically go through all of the master and slave servers that have been defined and add it to their lists.

$ ers_addtable --table=tablename

Things to remember

Every table for replication must have an integer based column for co-ordinating changes.  The eRServer installation scripts will add an _ers_uniq column for this to all of the tables marked for replication.  Do not change this column with your SQL queries.

All the tables to be replicated should have the same definition on both the master and slave databases.

Sequences in the master database aren't updated on the slave database(s).

If you have tables in the master database that use Sequences for number generation, the corresponding Sequences in the slave database(s) will remain unchanged regardless of how much data is replicated.

In a failover situation where a slave database needs to become the master database, the Sequences in the slave database have to be updated to current values before its operation as a master begins, otherwise duplicate sequence numbers will occur and insertions into the database will fail.

This is done through using the setval() and max() commands on the slave database at failover time, prior to it becoming a master.



SECURING THE ERSERVER INSTALLATION

Ensure the replication.cfg file is only readable by the erserver user

Because the replication.cfg file contains the passwords used to connect to your remote master and slave databases, you need to take care that it's only readable by the erserver user.

$ chmod 600 [erserver base installation directory]/etc/replication.cfg

Ensure the log files are only readable by the erserver user

Because sensitive information can sometimes be present in the eRServer log files, you need to take care that they too are only readable by the erserver user.

$ chmod 700 [erserver base installation directory]/log
$ chmod 600 [erserver base installation directory]/log/*



STARTING AND STOPPING ERSERVER

Starting eRServer

eRServer requires the Sun JDK 1.2.x or 1.3.x, and is recommended to be run on the same server as the master database.

You start it as the erserver user, as follows:

$ ers_ctl start

Stopping eRServer

You stop eRServer as the erserver user, as follows:

$ ers_ctl stop



Monitoring eRServer

The log files

As it runs, eRServer will generate a log file called "replication.log" in the log sub-directory of your eRServer installation.  You can check this file to verify the operation of eRServer, and to watch for errors if you ever have problems.



TUNING ERSERVER INSTALLATIONS

Tuning PostgreSQL

You should run this SQL command at least once on PostgreSQL installations as a PostgreSQL superuser, otherwise performance may be sub-optimal.

UPDATE pg_class SET relpages=1000, reltuples=100000 WHERE relname like '_rserv_log___'


Sizing the Java Virtual Machine

In the ers_ctl script, there is a variable called JVM_MAX tells the Java Virtual Machine running eRServer the maximum amount of memory it should ever use. The default at installation time is 512MB, but can be changed if needed. One reference installation uses this set to 2000MB.


Data integrity across server crashes on slave databases

For slave databases that have no need of data integrity in the event of a crash, it may be worthwhile turning off the PostgreSQL fsync() call for improved disk performance. This setting is adjustable in the main PostgreSQL configuration file and is documented in the main PostgreSQL manuals.



FINAL CHECKLIST

Ensure debug and verbose mode are turned off in the replication.cfg file.

Both of these modes have a performance hit when used, although the verbose mode is negligible.

An additional reason to turn them off in a production environment is because of the large amount of log files they generate.

Copyright © 2002 PostgreSQL, Inc.