Provided by: slony1-2-doc_2.1.4-1ubuntu1_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)

         •

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  and  later,  exclusive  locks are acquired at the beginning of the
       process.

SLONIK EVENT CONFIRMATION BEHAVIOUR

       Slonik waits until the provider has confirmed all outstanding  configuration  events  from
       any  other  node  before  contacting the provider to determine the set origin. Slonik then
       waits for the command submitted to the previous event node to be confirmed on  the  origin
       before submitting this command to the origin.

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

                                         6 February 2014                  SLONIK SUBSCRIBE SET(7)