## Name

SUBSCRIBE SET — Start replication of Slony-I set

## Synopsis

`SUBSCRIBE SET (options);`

## Description

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` process winds up doing more work than should be strictly necessary:

- It deletes all “old” entries in the table

- Those old entries clutter up the table until it is next `VACUUM`ed 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 is merely “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. 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.

### Note

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.

This uses schemadocsubscribeset( integer, integer, integer, boolean ).

## Example

    SUBSCRIBE SET (
       ID = 1,
       PROVIDER = 1,
       RECEIVER = 3,
       FORWARD = YES
    );

## Forwarding Behaviour

The `FORWARD=boolean` flag indicates whether the subscriber will store log information in tables sl_log_1 and sl_log_2. 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 or FAILOVER 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 or sl_log_2, 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.

## 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, 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.

## Version Information

This command was introduced in Slony-I 1.0