head	1.12;
access;
symbols
	REL7_4_29:1.7
	REL8_0_25:1.10
	REL8_1_21:1.11
	REL7_4_28:1.7
	REL8_0_24:1.10
	REL8_1_20:1.11
	REL7_4_27:1.7
	REL8_0_23:1.10
	REL8_1_19:1.11
	REL7_4_26:1.7
	REL8_0_22:1.10
	REL8_1_18:1.11
	REL7_4_25:1.7
	REL8_0_21:1.10
	REL8_1_17:1.11
	REL7_4_24:1.7
	REL8_0_20:1.10
	REL8_1_16:1.11
	REL7_4_23:1.7
	REL8_0_19:1.10
	REL8_1_15:1.11
	REL7_4_22:1.7
	REL8_0_18:1.10
	REL8_1_14:1.11
	REL7_4_21:1.7
	REL8_0_17:1.10
	REL8_1_13:1.11
	REL7_4_20:1.7
	REL8_0_16:1.10
	REL8_1_12:1.11
	REL7_3_21:1.4.2.1
	REL7_4_19:1.7
	REL8_0_15:1.10
	REL8_1_11:1.11
	REL7_3_20:1.4.2.1
	REL7_4_18:1.7
	REL8_0_14:1.10
	REL8_1_10:1.11
	REL7_3_19:1.4.2.1
	REL7_4_17:1.7
	REL8_0_13:1.10
	REL8_1_9:1.11
	REL8_0_12:1.10
	REL8_1_8:1.11
	REL7_3_18:1.4.2.1
	REL7_4_16:1.7
	REL8_0_11:1.10
	REL8_1_7:1.11
	REL8_0_10:1.10
	REL8_1_6:1.11
	REL7_4_15:1.7
	REL7_3_17:1.4.2.1
	REL8_1_5:1.11
	REL8_0_9:1.10
	REL7_4_14:1.7
	REL7_3_16:1.4.2.1
	REL7_3_15:1.4.2.1
	REL7_4_13:1.7
	REL8_0_8:1.10
	REL8_1_4:1.11
	REL7_3_14:1.4.2.1
	REL7_4_12:1.7
	REL8_0_7:1.10
	REL8_1_3:1.11
	REL7_3_13:1.4.2.1
	REL7_4_11:1.7
	REL8_0_6:1.10
	REL8_1_2:1.11
	REL7_3_12:1.4.2.1
	REL7_4_10:1.7
	REL8_0_5:1.10
	REL8_1_1:1.11
	REL8_1_STABLE:1.11.0.2
	REL8_1_0:1.11
	REL8_1_0RC1:1.11
	REL8_1_0BETA4:1.11
	REL8_1_0BETA3:1.11
	REL7_3_11:1.4.2.1
	REL7_4_9:1.7
	REL8_0_4:1.10
	REL8_1_0BETA2:1.10
	REL8_1_0BETA1:1.10
	REL7_3_10:1.4.2.1
	REL7_4_8:1.7
	REL8_0_3:1.10
	REL8_0_2:1.10
	REL7_3_9:1.4.2.1
	REL7_4_7:1.7
	REL8_0_1:1.10
	REL8_0_STABLE:1.10.0.4
	REL8_0_0:1.10.0.2
	REL8_0_0RC5:1.10
	REL8_0_0RC4:1.10
	REL8_0_0RC3:1.10
	REL8_0_0RC2:1.10
	REL8_0_0RC1:1.10
	REL8_0_0BETA5:1.10
	REL8_0_0BETA4:1.10
	REL7_4_6:1.7
	REL7_3_8:1.4.2.1
	REL8_0_0BETA3:1.9
	REL8_0_0BETA2:1.8
	REL7_4_5:1.7
	REL7_3_7:1.4.2.1
	REL7_4_4:1.7
	REL8_0_0BETA1:1.8
	REL7_4_3:1.7
	REL7_4_2:1.7
	REL7_3_6:1.4.2.1
	REL7_4_1:1.7
	REL7_3_5:1.4.2.1
	REL7_4:1.7
	REL7_4_RC2:1.7
	REL7_4_STABLE:1.7.0.2
	REL7_4_RC1:1.7
	REL7_4_BETA5:1.6
	REL7_4_BETA4:1.6
	REL7_4_BETA3:1.5
	REL7_4_BETA2:1.5
	WIN32_DEV:1.5.0.2
	REL7_4_BETA1:1.5
	REL7_3_4:1.4.2.1
	REL7_3_2:1.4.2.1
	REL7_3_STABLE:1.4.0.2;
locks; strict;
comment	@# @;


1.12
date	2006.09.05.17.20.27;	author tgl;	state dead;
branches;
next	1.11;

1.11
date	2005.10.02.23.50.05;	author tgl;	state Exp;
branches;
next	1.10;

1.10
date	2004.10.12.01.49.48;	author tgl;	state Exp;
branches;
next	1.9;

1.9
date	2004.09.10.04.31.06;	author neilc;	state Exp;
branches;
next	1.8;

1.8
date	2004.02.17.03.34.35;	author momjian;	state Exp;
branches;
next	1.7;

1.7
date	2003.10.27.02.52.45;	author momjian;	state Exp;
branches;
next	1.6;

1.6
date	2003.09.29.18.16.48;	author momjian;	state Exp;
branches;
next	1.5;

1.5
date	2002.11.06.17.50.53;	author momjian;	state Exp;
branches;
next	1.4;

1.4
date	2002.10.19.02.16.40;	author momjian;	state Exp;
branches
	1.4.2.1;
next	1.3;

1.3
date	2002.10.14.04.27.25;	author momjian;	state Exp;
branches;
next	1.2;

1.2
date	2002.09.26.05.24.30;	author momjian;	state Exp;
branches;
next	1.1;

1.1
date	2002.06.23.21.58.07;	author momjian;	state Exp;
branches;
next	;

1.4.2.1
date	2002.11.06.17.51.40;	author momjian;	state Exp;
branches;
next	;


desc
@@


1.12
log
@Remove contrib modules that have been migrated to pgfoundry: adddepend,
dbase, dbmirror, fulltextindex, mac, userlock; or abandoned: mSQL-interface,
tips.
@
text
@DBMirror - PostgreSQL Database Mirroring
===================================================


DBMirror is a database mirroring system developed for the PostgreSQL
database Written and maintained by Steven Singer(ssinger@@navtechinc.com)


(c) 2001-2004 Navtech Systems Support Inc.
ALL RIGHTS RESERVED

  Permission to use, copy, modify, and distribute this software and its
  documentation for any purpose, without fee, and without a written agreement
  is hereby granted, provided that the above copyright notice and this
  paragraph and the following two paragraphs appear in all copies.
 
  IN NO EVENT SHALL THE AUTHOR OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR
  DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING
  LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS
  DOCUMENTATION, EVEN IF THE AUTHOR OR DISTRIBUTORS HAVE BEEN ADVISED OF THE
  POSSIBILITY OF SUCH DAMAGE.
 
  THE AUTHOR AND DISTRIBUTORS SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  ON AN "AS IS" BASIS, AND THE AUTHOR AND DISTRIBUTORS HAS NO OBLIGATIONS TO
  PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.



Overview
--------------------------------------------------------------------

The mirroring system is trigger based and provides the following key features:

-Support for multiple mirror slaves
-Transactions are maintained
-Per table selection of what gets mirrored.


The system is based on the idea that a master database exists where all
edits are made to the tables being mirrored.   A trigger attached to the
tables being mirrored runs logging information about the edit to 
the Pending table and  PendingData table. 

A perl script(DBMirror.pl) runs continuously for each slave database(A database
that the change is supposed to be mirrored to) examining the Pending
table; searching for transactions that need to be sent to that particular slave 
database.  Those transactions are then mirrored to the slave database and
the MirroredTransaction table is updated to reflect that the transaction has
been sent.

If the transaction has been sent to all know slave hosts (All entries
in the MirrorHost table) then all records of it are purged from the
Pending tables.

Requirements:
---------------------------------
-PostgreSQL-8.1 (Older versions are no longer supported)
-Perl 5.6 or 5.8 (Other versions might work)
-PgPerl (http://gborg.postgresql.org/project/pgperl/projdisplay.php)


Upgrading from versions prior to 8.0
---------------------------------------
Users upgrading from a version of dbmirror prior to the one shipped with 
Postgresql 8.0 will need to perform the following steps

1. Dump the database then drop it (dropdb no not use the -C option)
2. Create database with createdb.
3. Run psql databasename -f MirrorSetup.sql
4. Restore the database(do not use the -C option of pg_dump/pg_restore)
5. run the SQL commands: DROP "Pending";DROP "PendingData"; DROP "MirrorHost";
   DROP "MirroredTransaction";

The above steps are needed A) Because the names of the tables used by dbmirror
to store data have changed and B) In order for sequences to be mirrored properly
all serial types must be recreated.



Installation Instructions
------------------------------------------------------------------------



1) Compile pending.c

The file pending.c contains the recordchange trigger.  This runs every
time a row inside of a table being mirrored changes.


To build the trigger run  make on the "Makefile" in the DBMirror directory.

PostgreSQL-8.0  Make Instructions:

  If you have already run "configure" in the top (pgsql) directory 
  then run "make" in the dbmirror directory to compile the trigger.


You should now have a file named pending.so that contains the trigger.

Install this file in your Postgresql lib directory (/usr/local/pgsql/lib)


2) Run MirrorSetup.sql

This file contains SQL commands to setup the Mirroring environment.  
This includes

-Telling PostgreSQL about the "recordchange" trigger function.
-Creating the dbmirror_Pending,dbmirror_PendingData,dbmirror_MirrorHost, 
dbmirror_MirroredTransaction tables


To execute the script use psql as follows 

"psql -f MirrorSetup.sql  MyDatabaseName"

where MyDatabaseName is the name of the database you wish to install mirroring
on(Your master).


3) Create slaveDatabase.conf files.

Each slave database needs its own configuration file for the 
DBMirror.pl script.  See slaveDatabase.conf for a sample.

The master settings refer to the master database(The one that is
being mirrored).

The slave settings refer to the database that the data is being
mirrored to.

The slaveName setting in the configuration file must match the slave
name specified in the dbmirror_MirrorHost table.

DBMirror.pl can be run in two modes of operation: 

 A) It can connect directly to the slave database.  To do this specify
 a slave database name and optional host and port along with a username
 and password.  See slaveDatabase.conf for details.


 The master user must have sufficient permissions to modify the Pending
 tables and to read all of the tables being mirrored.

 The slave user must have enough permissions on the slave database to
 modify(INSERT,UPDATE,DELETE) any tables on the slave system that are being
 mirrored. 

 B) The SQL statements that should be executed on the slave can be
 written to files which can then be executed slave database through
 psql.  This would be suitable for setups where their is no direct
 connection between the slave database and the master. A file is
 generated for each transaction in the directory specified by
 TransactionFileDirectory. The file name contains the date/time the
 file was created along with the transaction id.


4) Add the trigger to tables.

Execute the SQL code in AddTrigger.sql once for each table that should
be mirrored.   Replace MyTableName with the name of the table that should
be mirrored.

NOTE: DBMirror requires that every table being mirrored have a primary key
defined.

5)  Create the slave database.

The DBMirror system keeps the contents of mirrored tables identical on the
master and slave databases.  When you first install the mirror triggers the
master and slave databases must be the same.

If you are starting with an empty master database then the slave should
be empty as well.  Otherwise use pg_dump to ensure that the slave database
tables are initially identical to the master.

6) Add entries in the dbmirror_MirrorHost table.

Each slave database must have an entry in the dbmirror_MirrorHost table.

The name of the host in the dbmirror_MirrorHost table must exactly match the
slaveHost variable for that slave in the configuration file.

For example
INSERT INTO dbmirror_MirrorHost (SlaveName) VALUES ('backup_system');


6)  Start DBMirror.pl


DBMirror.pl is the perl script that handles the mirroring.  

It requires the Perl library Pg(See http://gborg.postgresql.org/project/pgperl/projdisplay.php)

It takes its configuration file as an argument(The one from step 3)
One instance of DBMirror.pl runs for each slave machine that is receiving
mirrored data.

Any errors are printed to standard out and emailed to the address specified in
the configuration file. 

DBMirror can be run from the master, the slave, or a third machine as long
as it is able to access both the master and slave databases(not
required if SQL files are being generated)

7) Periodically run clean_pending.pl 
clean_pending.pl cleans out any entries from the Pending tables that
have already been mirrored to all hosts in the MirrorHost table.
It uses the same configuration file as DBMirror.pl.

Normally DBMirror.pl will clean these tables as it goes but in some 
circumstances this will not happen.

For example if a transaction has been mirrored to all slaves except for
one, then that host is removed from the MirrorHost table(It stops being
a mirror slave) the transactions that had already been mirrored to 
all the other hosts will not be deleted from the Pending tables by 
DBMirror.pl since DBMirror.pl will run against these transactions again
since they have already been sent to all the other hosts.

clean_pending.pl will remove these transactions.

TODO(Current Limitations)
----------
-Support for selective mirroring based on the content of data.
-Support for BLOB's.
-Support for multi-master mirroring with conflict resolution.
-Better support for dealing with Schema changes.



Significant Changes Since 7.4
----------------
-Support for mirroring SEQUENCE's
-Support for unix domain sockets
-Support for outputting slave SQL statements to a file
-Changed the names of replication tables are now named
dbmirror_pending etc..



Credits
-----------
Achilleus Mantzios <achill@@matrix.gatewaynet.com>




Steven Singer
Navtech Systems Support Inc.
ssinger@@navtechinc.com
@


1.11
log
@Change nextval and other sequence functions to specify their sequence
argument as a 'regclass' value instead of a text string.  The frontend
conversion of text string to pg_class OID is now encapsulated as an
implicitly-invocable coercion from text to regclass.  This provides
backwards compatibility to the old behavior when the sequence argument
is explicitly typed as 'text'.  When the argument is just an unadorned
literal string, it will be taken as 'regclass', which means that the
stored representation will be an OID.  This solves longstanding problems
with renaming sequences that are referenced in default expressions, as
well as new-in-8.1 problems with renaming such sequences' schemas or
moving them to another schema.  All per recent discussion.
Along the way, fix some rather serious problems in dbmirror's support
for mirroring sequence operations (int4 vs int8 confusion for instance).
@
text
@@


1.10
log
@Update reference to pgsql-server.
@
text
@d59 1
a59 1
-PostgreSQL-7.4 (Older versions are no longer supported)
d180 1
a180 1
6) Add entries in the MirrorHost table.
d182 1
a182 1
Each slave database must have an entry in the MirrorHost table.
d184 1
a184 1
The name of the host in the MirrorHost table must exactly match the
d188 1
a188 1
INSERT INTO "MirrorHost" ("SlaveName") VALUES ('backup_system');
@


1.9
log
@Apply patch from Steven Singer for contrib/dbmirror. Changes:

-It fixes up some bugs with handling setval calls
-Adds upgrade instructions from prior versions
-Improved the sample config file
-Fixed some things in the clean_pending script
@
text
@d57 1
a57 1
Requirments:
d95 1
a95 1
PostgreSQL-7.4  Make Instructions:
d97 1
a97 1
  If you have already run "configure" in the pgsql-server directory 
@


1.8
log
@Please apply this patch to contrib/dbmirror
In incorperates changes from myself and a number of contributors.

This update to dbmirror provides:

-replication of sequence operations via setval/nextval
-DBMirror.pl support for logging to syslog
-changed the names of the tables to dbmirror_*  (no quotes required)
-Support for writitng SQL statements to files instead of directly to
 a slave database
-More options for DBMirror.pl in the config files.

Steven Singer
@
text
@d64 18
d86 1
@


1.7
log
@Here is an update to the dbmirror README file.

-References to older versions of PostgreSQL have been removed(It no
longer
compiles against older versions)
-Added a link to PgPerl at GBorg.

Steven Singer
@
text
@d9 1
a9 1
(c) 2001-2002 Navtech Systems Support Inc.
d60 1
a60 1
-Perl 5.6(Other versions might work)
d84 1
a84 1
Install this file in /usr/local/pgsql/lib  (or another suitable location).
a85 5
If you choose a different location the MirrorSetup.sql script will need
to be modified to reflect your new location.   The CREATE FUNCTION command
in the MirrorSetup.sql script associates the trigger function with the
pending.so shared library.  Modify the arguments to this command if you
choose to install the trigger elsewhere.
d93 2
a94 1
-Creating the Pending,PendingData, MirrorHost, MirroredTransaction tables
d113 28
a140 11
The slave settings refer to the database that the data is being mirrored to.
The slaveHost parameter must refer to the machine name of the slave (Either
a resolvable hostname or an IP address).  The value for slave host
must match the Hostname field in the MirrorHost table(See step 6).

The master user must have sufficient permissions to modify the Pending
tables and to read all of the tables being mirrored.

The slave user must have enough permissions on the slave database to
modify(INSERT,UPDATE,DELETE) any tables on the slave system that are being
mirrored. 
d169 1
a169 1
INSERT INTO "MirrorHost" ("HostName") VALUES ('mySlaveMachine.mycompany.com');
d187 2
a188 1
as it is able to access both the master and slave databases.
d211 1
a211 2
-Support for conflict resolution.
-Batching SQL commands in DBMirror for better performance over WAN's.
d213 18
@


1.6
log
@A) Fixes a bug that prevented mirroring of data on a table that has had
a column dropped.

B) Updated the documentation for the 7.4 release.

Steven Singer
@
text
@d1 1
a1 1
DBMirror - Postgres Database Mirroring
d5 1
a5 1
DBMirror is a database mirroring system developed for the Postgres
d57 7
d76 1
a76 1
Postgres-7.3 & 7.4  Make Instructions:
a80 22
Postgres-7.1 & Postgres-7.2 Make Instructions:

  The included Makefile is not compatible with postgres 7.1 and 7.2
  The trigger will need to be built by hand.

  Run the following commands

  gcc -fpic -I/usr/local/pgsql/include/server -c pending.c -DNOSCHEMAS -DNODROPCOLUMN
  ld -shared -o pending.so pending.o

  Assuming the postgres include files are in /usr/local/pgsql/include/server.  

Postgres-7.1.x installations should change this to
/usr/local/pgsql/include  (The server part is for 7.2+)

If you have installed the postgres include files to another location then
  modify the include path to reflect this.

  Compiling the trigger by hand requires that all postgres headers be installed
  ,this is accomplished in postgresql(7.1 or 7.2) by running 
  "make install-all-headers" in the postgres source directory.

d97 1
a97 1
-Telling Postgres about the "recordchange" trigger function.
a107 9
Postgres-7.1 and 7.2 Notes:
  -The syntax for creating a trigger function changed in Postgres-7.3. 
  Change the line in MirrorSetup.sql from 

  CREATE FUNCTION "recordchange" () RETURNS trigger AS

  to 
  CREATE FUNCTION "recordchange" () RETURNS OPAQUE AS

d164 1
a164 2
It requires the Perl library Pg(See src/interfaces/perl5 in the postgres 
source distribution).
a199 16

Tested Platforms:
------------------

DBMirror has been tested on the following configurations but should
work on any platform with Postgres >= 7.1 and Perl 5.6. 

RedHat Linux 7.1 & 6.2
 -Postgres 7.1.2
 -Perl 5.6

Mandrake Linux 8.0(Limited Testing)
 -Postgres 7.2
 -Postgres 7.3
 -Postgres 7.4
 -Perl 5.6
@


1.5
log
@Change dbmirror lincense to BSD.
@
text
@d69 1
a69 1
Postgres-7.3 Make Instructions:
d81 1
a81 1
  gcc -fpic -I/usr/local/pgsql/include/server -c pending.c -DNOSCHEMAS
d239 1
@


1.4
log
@It includes
-Support for mirroring tables in different Schema's
-Improved documentation for compiling with 7.1.x and 7.2.x
-Fixes a buffer overrun bug.

Steven Singer
@
text
@d10 1
a10 1
Released under the GNU Public License version 2. See COPYING.
d12 16
a27 5

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
@


1.4.2.1
log
@Change dbmirror lincense to BSD.
@
text
@d10 1
a10 1
ALL RIGHTS RESERVED
d12 5
a16 16
  Permission to use, copy, modify, and distribute this software and its
  documentation for any purpose, without fee, and without a written agreement
  is hereby granted, provided that the above copyright notice and this
  paragraph and the following two paragraphs appear in all copies.
 
  IN NO EVENT SHALL THE AUTHOR OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR
  DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING
  LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS
  DOCUMENTATION, EVEN IF THE AUTHOR OR DISTRIBUTORS HAVE BEEN ADVISED OF THE
  POSSIBILITY OF SUCH DAMAGE.
 
  THE AUTHOR AND DISTRIBUTORS SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  ON AN "AS IS" BASIS, AND THE AUTHOR AND DISTRIBUTORS HAS NO OBLIGATIONS TO
  PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
@


1.3
log
@This trivial patch fixes a bunch of spelling mistakes in the
contrib/dbmirror/README.dbmirror doc file.

Neil Conway
@
text
@d49 1
d58 16
a73 2
The Makefile supplied assumes that the postgres include files are in 
/usr/local/pgsql/include/server.  
d79 5
a83 1
modify the Makefile to reflect this.
a84 3
The trigger requires that all postgres headers be installed, this is
accomplished in postgresql(7.1 or 7.2) by running "make install-all-headers"
in the postgres source directory.
d86 1
a86 1
The Makefile should create a file named pending.so that contains the trigger.
d112 9
d227 1
@


1.2
log
@Attached is a patch to contrib/dbmirror that fixes a bug that was
causing  the postmaster to crash when the trigger was running on a table
without a  primary key.

I've also updated the docs to explicitly say that tables need primary
keys.

Steven Singer
@
text
@d6 1
a6 1
database Written and maintened by Steven Singer(ssinger@@navtechinc.com)
d20 1
a20 1
Overrview
d30 2
a31 2
The system is based on the idea that a master database exist where all
edits are made to the tables being mirrored.   A trigger attatched to the
d35 1
a35 1
A perl script(DBMirror.pl) runs continiously for each slave database(A database
d80 1
a80 1
2) Run MirroSetup.sql
@


1.1
log
@Add dbmirror to /contrib.  Minor C cleanups and Makefile.

Steven Singer
@
text
@d123 3
@
