rserv/doc/README.rserv

erServer demonstration implementation
(c) 2000, Vadim Mikheev and Thomas Lockhart, PostgreSQL Inc.

Version 0.1:
  Replicates a master database to a single slave database.
  Tested under Linux (Mandrake 7.2).

Requirements:

- PostgreSQL >= 7.0.X
  A separate Makefile is required for PostgreSQL 7.0.x and earlier
- Perl5 and the PostgreSQL perl interface
- TCL and the PostgreSQL tcl interface (for demo only)


How to compile:

- make all
- make install

Scripts and libraries are installed in places which are consistant
with the way other contrib/ code is installed; underneath the core
items in a contrib/ directory.


The toolset:

MasterInit dbname
  sets up structures and user-defined functions for a master
  database. 

SlaveInit dbname
  sets up structures for a slave database. Does not include triggers,
  but only bookkeeping tables. 

MasterAddTable dbname table column
  sets up triggers for the specified table and column. Note that this
  column must be updated for replication to occur. 

SlaveAddTable dbname table column
  sets up bookkeeping for the specified table and column.

Replicate masterdb slavedb
  actually replicate changes from a master to single slave. Note that
  this must be repeated to replicate to multiple slaves, but the
  bookkeeping for each slave is handled separately so each can be
  updated at different times and with different sets of changes.

GetSyncID [--noverbose] slavedb
  returns the last syncid the specified slave has seen. May be used
  in conjunction with SyncSyncID and CleanLog using the --noverbose
  option.

MasterSync masterdb syncid
  registers a syncid with the specified master database. Used to
  propagate replication success back to the master database.

CleanLog masterdb syncid
  removes obsolete entries in the master database replication log
  table up to the specified replication sequence number.

Other utilities:

PrepareSnapshot
  build a file of replication information from the specified masterdb.

ApplySnapshot
  use a file of replication information to apply to the specified
  slavedb. 


How to run a demo:

Run the InitRservTest script. It will create two local databases
'master' & 'slave' with table 'test' in them. It accepts the following
arguments:
  --help
    Print a usage message and quit.
  --user name
    Access the database with another username.
  --host name
    Access a remote database. Note that the shared library *must* be
    visible in the same path as installed on the build machine.
  masterdb
  slavedb
    Names of test databases. Defaults to 'master' and 'slave',
        respectively.

Once the test databases are set up, simply updating the master table
is sufficient to log a replication event. You can update the table
test then run "Replicate master slave", or you can use the demo
program RservTest.

Run the tcl/tk GUI demo program, RservTest. It has a single window,
which has four buttons and three data entry boxes.

  --------------------------------------------------
 |   PostgreSQL Asynchronous Replication            |
 |        Master          Slave                     |
 |      < master    >   < slave      >              |
 |                                                  |
 |  [ Update    ]   <                         >     |
 |  [ Replicate ]                                   |
 |  [ Show      ]   ____________                    |
 |                                                  |
 |            [ Quit ]                              |
 |                                                  |
  --------------------------------------------------

The demo has the following behaviors:

If you enter a string into the data entry field to the right of
[Update], then that string will be used to either update the master
database or to query the slave database.

If you click [Update], then the string in the data entry box will be
entered into the master database.

If you click [Replicate], then all changes since the last replication
will be propagated to the slave database.

If you click [Show], then the slave database will be queried to find
the string in the data entry box to the right of the [Update]
button. If the string does not (yet) exist in the slave database, then
"n/a" will appear to the right of the [Show] button. If the string
does exist in the slave database, then it will be printed to the right
of the [Show] button.


Todo:
1. Support for multiple slave servers.
2. Explicit support for master/slave failover.
3. More docs.
1	erServer demonstration implementation
2	(c) 2000, Vadim Mikheev and Thomas Lockhart, PostgreSQL Inc.
3
4	Version 0.1:
5	Replicates a master database to a single slave database.
6	Tested under Linux (Mandrake 7.2).
7
8	Requirements:
9
10	- PostgreSQL >= 7.0.X
11	A separate Makefile is required for PostgreSQL 7.0.x and earlier
12	- Perl5 and the PostgreSQL perl interface
13	- TCL and the PostgreSQL tcl interface (for demo only)
14
15
16	How to compile:
17
18	- make all
19	- make install
20
21	Scripts and libraries are installed in places which are consistant
22	with the way other contrib/ code is installed; underneath the core
23	items in a contrib/ directory.
24
25
26	The toolset:
27
28	MasterInit dbname
29	sets up structures and user-defined functions for a master
30	database.
31
32	SlaveInit dbname
33	sets up structures for a slave database. Does not include triggers,
34	but only bookkeeping tables.
35
36	MasterAddTable dbname table column
37	sets up triggers for the specified table and column. Note that this
38	column must be updated for replication to occur.
39
40	SlaveAddTable dbname table column
41	sets up bookkeeping for the specified table and column.
42
43	Replicate masterdb slavedb
44	actually replicate changes from a master to single slave. Note that
45	this must be repeated to replicate to multiple slaves, but the
46	bookkeeping for each slave is handled separately so each can be
47	updated at different times and with different sets of changes.
48
49	GetSyncID [--noverbose] slavedb
50	returns the last syncid the specified slave has seen. May be used
51	in conjunction with SyncSyncID and CleanLog using the --noverbose
52	option.
53
54	MasterSync masterdb syncid
55	registers a syncid with the specified master database. Used to
56	propagate replication success back to the master database.
57
58	CleanLog masterdb syncid
59	removes obsolete entries in the master database replication log
60	table up to the specified replication sequence number.
61
62	Other utilities:
63
64	PrepareSnapshot
65	build a file of replication information from the specified masterdb.
66
67	ApplySnapshot
68	use a file of replication information to apply to the specified
69	slavedb.
70
71
72	How to run a demo:
73
74	Run the InitRservTest script. It will create two local databases
75	'master' & 'slave' with table 'test' in them. It accepts the following
76	arguments:
77	--help
78	Print a usage message and quit.
79	--user name
80	Access the database with another username.
81	--host name
82	Access a remote database. Note that the shared library must be
83	visible in the same path as installed on the build machine.
84	masterdb
85	slavedb
86	Names of test databases. Defaults to 'master' and 'slave',
87	respectively.
88
89	Once the test databases are set up, simply updating the master table
90	is sufficient to log a replication event. You can update the table
91	test then run "Replicate master slave", or you can use the demo
92	program RservTest.
93
94	Run the tcl/tk GUI demo program, RservTest. It has a single window,
95	which has four buttons and three data entry boxes.
96
97	--------------------------------------------------
98	\| PostgreSQL Asynchronous Replication \|
99	\| Master Slave \|
100	\| < master > < slave > \|
101	\| \|
102	\| [ Update ] < > \|
103	\| [ Replicate ] \|
104	\| [ Show ] ____________ \|
105	\| \|
106	\| [ Quit ] \|
107	\| \|
108	--------------------------------------------------
109
110	The demo has the following behaviors:
111
112	If you enter a string into the data entry field to the right of
113	[Update], then that string will be used to either update the master
114	database or to query the slave database.
115
116	If you click [Update], then the string in the data entry box will be
117	entered into the master database.
118
119	If you click [Replicate], then all changes since the last replication
120	will be propagated to the slave database.
121
122	If you click [Show], then the slave database will be queried to find
123	the string in the data entry box to the right of the [Update]
124	button. If the string does not (yet) exist in the slave database, then
125	"n/a" will appear to the right of the [Show] button. If the string
126	does exist in the slave database, then it will be printed to the right
127	of the [Show] button.
128
129
130	Todo:
131	1. Support for multiple slave servers.
132	2. Explicit support for master/slave failover.
133	3. More docs.