eRServer Installation Guide
Author: Justin Clift

| 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

- Sun JDK 1.2.x, or 1.3.1
- Perl 5.005_04 or greater
- Perl DBI
- Perl DBD::Pg*
- eRServer 1.2
- GNU gcc 2.95.3 or greater
- GNU make 3.79.1 or greater
- PostgreSQL Superuser access to the master and slave database

* 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.