Provided by: slony1-doc_1.2.15-1_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 ei‐
          ther 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  at‐
          tempt  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 dur‐
          ing 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 hun‐
          dreds gigabytes of data’) possibly multiple days for  this  event  to
          complete.
 
          The SUBSCRIBE SET request will, nonetheless, return fairly much imme‐
          diately, 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 com‐
          plete  subscribing  before submitting requests for subscriptions that
          use that node as a provider. If you don’t, it won’t be  a  big  deal:
          slonik  will  check  the  node, discover that it is not yet an active
          provider for the set, and report back:
 
           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 configura‐
          tion  will be propagated throughout the replication network. The nor‐
          mal reason to revise this information is that you want a node to sub‐
          scribe  to a different provider node, or for a node to become a ‘for‐
          warding’ 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 informa‐
          tion during  replication  to  make  it  possible  candidate  for  the
          provider role for future nodes.
 
        This uses “schemadocsubscribeset( integer, integer, integer, boolean )”
        [not available as a man page].
 

EXAMPLE

        SUBSCRIBE SET (
           ID = 1,
           PROVIDER = 1,
           RECEIVER = 3,
           FORWARD = YES
        );
        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  MOVE  SET(7) or 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  for‐
        warding  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 con‐
        tains, 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 sub‐
        scribing to the origin have forwarding turned on.
        · The  fact  that  the request returns immediately even though the sub‐
          scription may take considerable time to complete may be  a  bit  sur‐
          prising.
 
          Processing   of  the  subscription  involves  two  events;  the  SUB     
          SCRIBE_SET, initiated from the provider node, and an ENABLE_SUBSCRIP     
          TION, which is initiated on the subscriber node. This means that WAIT
          FOR EVENT(7) cannot directly wait for completion of  a  subscription.
          If  you  need to wait for completion of a subscription, then what you
          need to do instead is to submit a SYNC(7) request, and wait for  that
          event.
 
        · 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.
        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, exclusive locks are acquired at
        the beginning of the process; in earlier versions, locks were  acquired
        implicitly as activity mandated it, which left some risk of deadlock if
        other applications could access the subscriber database at this time.
        This command was introduced in Slony-I 1.0
 
                                17 November 2008               SUBSCRIBE SET(7)