Provided by: slony1-2-doc_2.0.7-3build1_all bug

NAME

       SUBSCRIBE SET - Start replication of Slony-I set

SYNOPSIS

       SUBSCRIBE SET (options);

DESCRIPTION

       This performs one of two actions:

       o Initiates replication for a replication set

         Causes  a  node  (subscriber)  to  start  replicating a set of tables
         either from the origin or from  another  provider  node,  which  must
         itself already be be an active, forwarding subscriber.

         The  application  tables  contained in the set must already exist and
         should ideally be empty. The current  version  of  Slony-I  will  not
         attempt  to  copy  the schema of the set. The replication daemon will
         start copying the current content of the set from the given  provider
         and  then  try  to  catch  up  with any update activity that happened
         during that copy process. After successful subscription,  the  tables
         are  guarded  on  the  subscriber, using triggers, against accidental
         updates by the application.

         If the tables on the subscriber are not  empty,  then  the  COPY  SET
         event  (which  is part of the subscription process) may wind up doing
         more work than should be strictly necessary:

         o It attempts to TRUNCATE the table, which will be efficient.

         o If that fails (a foreign key relationship  might  prevent  TRUNCATE
           from  working),  it  uses DELETE to delete all 'old' entries in the
           table

         o Those old entries clutter up the table until it  is  next  VACUUMed
           after the subscription process is complete

         o The indices for the table will contain entries for the old, deleted
           entries, which will slow the process of inserting new entries  into
           the index.
         Warning

         This operation can take a (potentially distinctly) non-zero period of
         time. If you have a great deal of data in a particular set of tables,
         it  may  take  hours  or  even  (if 'a great deal' indicates 'tens or
         hundreds gigabytes of data') possibly multiple days for this event to
         complete.

         The  SUBSCRIBE  SET  request  will,  nonetheless,  return fairly much
         immediately, even though the work, being  handled  by  the  COPY  SET
         event,  is still in progress. If you need to set up subscriptions for
         a set of cascading nodes, you will need to wait for  each  subscriber
         to  complete subscribing before submitting requests for subscriptions
         that use that node as a provider.

          Slony-I: provider 2 is not an active forwarding node for replication set 1

         In effect, such subscription  requests  will  be  ignored  until  the
         provider is ready.

       o Revising subscription information for already-subscribed nodes.

         If  you  need to revise subscription information for a node, you also
         submit  the  new  information  using  this  command,  and   the   new
         configuration  will be propagated throughout the replication network.
         The normal reason to revise this information is that you want a  node
         to  subscribe to a different provider node, or for a node to become a
         'forwarding' subscriber so it may later become  the  provider  for  a
         later subscriber.

       ID = ival
         ID of the set to subscribe

       PROVIDER = ival
         Node ID of the data provider from which this node draws data.

       RECEIVER = ival
         Node ID of the new subscriber

       FORWARD = boolean
         Flag  whether  or  not  the  new  subscriber  should  store  the  log
         information during replication to make it possible candidate for  the
         provider  role  for  future  nodes. Any node that is intended to be a
         candidate for FAILOVER must have FORWARD = yes.

       OMIT COPY = boolean
         Flag whether or not the subscription process should  omit  doing  the
         COPY  of  the  existing  data  in the set. In effect, use this option
         indicates 'Trust me, the data is already in sync!'

         This is notably useful for the following sorts of cases:

         o Major inter-version upgrades (e.g. - as from Slony-I  1.2  to  2.0)
           may be done quickly.

         o Cloning  a  'master  node'.  SLONIK  CLONE  PREPARE(7)/SLONIK CLONE
           FINISH(7)

         o

       This uses "schemadocsubscribeset(integer,  integer,  integer,  boolean,
       boolean)" [not available as a man page].

EXAMPLE

       SUBSCRIBE SET (
          ID = 1,
          PROVIDER = 1,
          RECEIVER = 3,
          FORWARD = YES
       );
         WAIT FOR EVENT(
           ORIGIN=1,
           CONFIRMED=ALL,
           WAIT ON=1
       );

FORWARDING BEHAVIOUR

       The  FORWARD=boolean  flag  indicates whether the subscriber will store
       log information in tables "sl_log_1" [not available as a man page]  and
       "sl_log_2"  [not  available  as  a man page]. Several implications fall
       from this...

       By storing the data in these tables on the subscriber,  there  is  some
       additional  processing  burden. If you are certain that you would never
       want to SLONIK MOVE  SET(7)  or  SLONIK  FAILOVER(7)  to  a  particular
       subscriber,  it  is  worth  considering  turning off forwarding on that
       node.

       There is, however, a case where having forwarding turned off opens up a
       perhaps-unexpected  failure  condition;  a rule of thumb should be that
       all nodes that connect directly to the origin  should  have  forwarding
       turned on. Supposing one such 'direct subscriber' has forwarding turned
       off, it is possible for that node to be forcibly  lost  in  a  case  of
       failover. The problem comes if that node gets ahead of other nodes.

       Let's  suppose  that the origin, node 1 is at SYNC number 88901, a non-
       forwarding node, node 2 has processed  up  to  SYNC  88897,  and  other
       forwarding  nodes,  3,  4,  and  5, have only processed data up to SYNC
       88895. At that moment, the disk system on the origin node catches fire.
       Node  2  has  the data up to SYNC 88897, but there is no remaining node
       that  contains,  in  "sl_log_1"  [not  available  as  a  man  page]  or
       "sl_log_2"  [not available as a man page], the data for SYNCs 88896 and
       88897, so there is no way to bring nodes 3-5 up to that point.

       At that point, there are only two choices:  To  drop  node  2,  because
       there  is  no  way to continue managing it, or to drop all nodes but 2,
       because there is no way to bring them up to SYNC 88897.

       That dilemma may be avoided by making  sure  that  all  nodes  directly
       subscribing to the origin have forwarding turned on.

DANGEROUS/UNINTUITIVE BEHAVIOUR

       o The  fact  that  the  request  returns  immediately  even  though the
         subscription may take considerable time to  complete  may  be  a  bit
         surprising.

         Processing   of   the   subscription   involves   two   events;   the
         SUBSCRIBE_SET,  initiated  on   the   set   origin   node,   and   an
         ENABLE_SUBSCRIPTION.   This  means that SLONIK WAIT FOR EVENT(7) must
         be used following a SUBSCRIBE SET to wait until the last event on the
         set origin completes.

       o This command has two purposes; setting up subscriptions (which should
         be unsurprising) and revising subscriptions, which isn't  so  obvious
         to intuition.

       o New subscriptions are set up by using DELETE or TRUNCATE to empty the
         table on a subscriber. If you created a new node by copying data from
         an  existing node, it might 'seem intuitive' that that data should be
         kept; that is not the case - the former contents  are  discarded  and
         the node is populated from scratch.

       o The  OMIT  COPY  option has the potential to be a large 'foot gun' in
         that it allows the administrator to  push  replication  sets  out  of
         sync.

LOCKING BEHAVIOUR

       This  operation  does  not  require acquiring any locks on the provider
       node.

       On the subscriber node, it will have the effect of locking every  table
       in  the  replication  set. In version 1.2 or later, exclusive locks are
       acquired at the beginning of the process.

VERSION INFORMATION

       This command was introduced in Slony-I 1.0

       The OMIT COPY option was introduced in Slony-I 2.0.3.

       In Slony-I 2.0.5 the SUBSCRIBE  SET  command  gets  submitted  directly
       against  the  set  origin.  Prior  to this change the SUBSCRIBE SET was
       submitted against the provider

                                3 December 2011        SLONIK SUBSCRIBE SET(7)