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:

       · 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:

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

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

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

         · 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.

       · 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:

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

         · Cloning a ‘master node’. SLONIK CLONE PREPARE(7)/SLONIK CLONE FINISH(7)

         ·

       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

       · 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.

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

       · 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.

       · 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)