README
$Id: README,v 1.6.2.2 2004/10/01 20:43:25 cbbrowne Exp $

Christopher Browne
Database Administrator
Afilias Canada

This is a "second system" set of scripts for managing a set of Slony-I
instances.

Unlike the shell scripts that have previously been used, these scripts
support having an arbitrary number of Slony-I nodes.  They are
configured in the [cluster].nodes file (e.g. - environment variable
SLONYNODES) by calling add_node() once indicating the configuration
for each node that is needed.

The following configuration is set up:

 Host Level Configuration
--------------------------------------

This configuration will normally apply to all clusters being managed
on a particular host, so it would probably make sense to modify it
directly in slon.env.

 $SLON_BIN_PATH is the path to use to find the slon and slonik
   binaries.

 $APACHE_ROTATOR is an optional reference to the location of the
   Apache log rotator; if you set it to a path to an Apache "rotatelog"
   program, that will be used to keep log file size down to a "dull
   roar".
  <http://httpd.apache.org/docs-2.0/programs/rotatelogs.html>

 $LOGDIR is the directory in which to put log files.  The script will
   generate a subdirectory for each node.

 Node Level Configuration
--------------------------------------

This configuration should be set up in the file represented in the
environment variable SLONYNODES.

 $SETNAME represents the name of the cluster.  In each database
  involved in the replication set, you will find the namespace
  "_$SETNAME" that contains Slony-I's configuration tables

 $MASTERNODE is the number of the "master" node.  It defaults to 1, if
 not otherwise set.

 Set Level Configuration
-----------------------------------

The configuration of the tables, sequences and such are stored in the
file pointed to by the environment variable SLONYSET, in the following
Perl variables:

  $TABLE_ID - where to start numbering table IDs

   The table IDs are required to be unique across all sets in a
   Slony-I cluster, so if you add extra sets, you need to set
   $TABLE_ID to a value that won't conflict, typically something
   higher than largest value used in earlier sets.

  @PKEYEDTABLES contains all of the tables that have primary keys

  %KEYEDTABLES contains tables with candidate primary keys associated
    with the index you _want_.

  @SERIALTABLES contains tables that do not have a unique key
                to which Slony-I will need to add and populate
                a unique key

  @SEQUENCES lists all of the application sequences that are to be
             replicated.

The values in slon.env are "hardcoded" as far as the tools are
concerned.

To make this more flexible, slon.env also looks at the environment
variables SLONYNODES and SLONYSET as alternative sources for
configuration.

That way, you may do something like:

   for i in `seq 10`; do
      SLONYNODES="./node$i.config" ./init_cluster.pl
   done

- Such an "alternative cluster.nodes" might import Pg, and do queries
against a database to be replicated in order to populate the sets of
tables and such.

- The "alternative cluster.nodes" might search some sort of 'registry' for
the set of nodes to be replicated.

Parallel to SLONYNODES is the environment variable SLONYSET, which
controls the contents of replication sets.  It looks as though it
should be usual for there to be just one "intentionally active"
subscription set at any given time, with other sets being set up in
order to be merged with the "main" set.

Steps to start up replication
-------------------------------

0.  Dump from source system to destination
 pg_dump -s -c  flex1 | psql flex2
  
1. Initializes the Slony cluster
  ./init_cluster.pl

  This sets up a FULL cross-join set of paths and listeners, doing
  something of a shortest-path evaluation of which "store listens" to
  set up.

2. Start up slon servers for both DB instances
  ./slon_start.pl node1
  ./slon_start.pl node2

3. Sets up all the tables for "set 1" for FlexReg 2.0  
  ./create_set.pl set1
    
4. Subscribe Node #2 to Set #1
  ./subscribe_set.pl set1 node2
     This is the Big One...

That SHOULD be it, although "should" is probably too strong a word :-)

There are numerous other tools for adding/dropping Slony-I
configuration, and scripts that might manage simple forms of
switchover/failover.
