A tool to assist with setting up replication in PostgreSQL 9.1+ for the purposes of testing or demonstration.
A tool to assist with setting up replication in PostgreSQL 9.1+ for the purposes of testing or demonstration.
Usage:
pg_rep_test [OPTION]
Options:
-a ARCHIVEDIR create an archive in the named directory
-D DATADIRS comma-separated list of directory names starting with
primary (default: primary,standby1,standby2,...)
-i prompt for input of options interactively
-l LOGFILE write log messages to a file, but it will not log
any pre-check messages
-L enable database logging in every instance
-p PORTS comma-separated list of ports to use starting with
primary (default: 5530,5531,5532,...)
-r REPLICAS number of replicas to create (default: 1)
-R use replication slots
-s fan|tree|chain replication structure (default: fan)
fan = all standbys connect directly to primary
tree = one standby connects directly to primary, the
remaining ones connect to that standby
chain = no more than one standby connects to any node
-S configures all standbys to be synchronous
-T don't generate management tool script file to manage the
new instances
-? show this help then exit
If you don't know where to start, just run:
./pg_rep_test -i
This will provide you with an interactive prompt to configure it however you want.
To create 5 standbys, the first one connecting to the primary, and the rest connecting to the first standby, you would run the following:
./pg_rep_test -r 5 -s tree
This would create a directory named "primary", and 5 directories named "standby1", "standby2"... "standby5". Each standby would be configured to connect to the first standby, and the first standby would connect to the primary.
This would also produce the following ASCII-diagram which displays the configuration they were created in and the port numbers used:
[Primary (5530)]
|
---[Standby 1 (5531)]
|
---[Standby 2 (5532)]
|
---[Standby 3 (5533)]
|
---[Standby 4 (5534)]
|
---[Standby 5 (5535)]
These are ASCII-diagrams of the 3 replication structures.
[Primary (5530)]
|
---[Standby 1 (5531)]
|
---[Standby 2 (5532)]
|
---[Standby 3 (5533)]
|
---[Standby 4 (5534)]
[Primary (5530)]
|
---[Standby 1 (5531)]
|
---[Standby 2 (5532)]
|
---[Standby 3 (5533)]
|
---[Standby 4 (5534)]
[Primary (5530)]
|
---[Standby 1 (5531)]
|
---[Standby 2 (5532)]
|
---[Standby 3 (5533)]
|
---[Standby 4 (5534)]
You can run pg_rep_test without any parameters which will then just create a primary with a single standby.
If a list of ports isn't specified, it will use a list of unused ports starting from 5530. If a port is in use, the next port will be checked and so on, until every instance has a port it can use.
If the default directory names (i.e. primary, standby1, standby2 etc.) already exist in the directory then new ones will be generated with a numeric suffix. (e.g. primary_1, standby1_1 etc.)
All configuration changes that pg_rep_test makes get put into a separate configuration file called custom.conf. This is then referenced by postgresql.conf using an 'include' directive at the end of the file.
A dedicated replication user (with the REPLICATION role attribute) called rep_user will be created automatically in the primary instance. This will then be used by all standbys for streaming replication connections.
A maintenance tool script is generated automatically after creating a set of instances (unless suppressed with -T). The following section describes its use.
A maintenance tool script to manage sets of instances created by pg_rep_test. The name of the tool is unique to a set of instances.
Usage:
./tool.pg_rep_test [OPTION] [ACTION]
Options:
-m MODE shutdown mode (smart, fast or immediate); must be
used with the 'stop' action
-l LOGFILE write log messages to a file
-? show this help then exit
ACTION can be one of:
status list all instances, their ports, data directories and
whether they are running or not
start start all instances
stop stops all instances, which can be used with the -m
option
restart restart all instances
destroy stops (if started) and deletes all instances; also
deletes this maintenance script
To stop all instances managed by the tool script immediately, you would run the following:
./tool.pg_rep_test -m immediate stop
To check the status of all instances managed by the script, you would run:
./tool.pg_rep_test status
This would produce output similar to the following:
Instance | Port | Primary Port | Status | XLog location | Replication lag (bytes)
---------------------------------------------------------------------------------------
primary | 5530 | | ONLINE | 0/3000160 | 0
standby1 | 5531 | 5530 | IN RECOVERY | 0/3000160 | 0
standby2 | 5532 | 5530 | IN RECOVERY | 0/3000160 | 0
standby3 | 5533 | 5530 | IN RECOVERY | 0/3000160 | 0
To stop and delete all instances, and the tool script itself, you would run:
./tool.pg_rep_test destroy
If a set of instances is created by pg_rep_test and a tool.pg_rep_test script already exists in the same directory, the tool script will be given a distinct name. This is so that multiple tool scripts, each associated with a particular set of instances, can exist alongside each other. So after the first script is created, subsequent ones will be named tool_1.pg_rep_test, tool_2... tool_3... etc.
pg_rep_test is licensed under The PostgreSQL License (http://www.opensource.org/licenses/postgresql), which is closely related to the BSD license.