SLONIK SUBSCRIBE SET

Name

Synopsis

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

If you need to revise subscription information for a
set,provider,receiver combination you must 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 if you want to change the FORWARD
status of a set on a particular receiver node. If you want to change
the provider used by a particular node you should use the
SLONIK RESUBSCRIBE NODE command.

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.

Example

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 SLONIK MOVE SET or SLONIK 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.

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

Prior to Slony-I 2.2.0 the SUBSCRIBE SET command could be
used to change the provider of an already subscribed node. As of
2.2.0 the SLONIK RESUBSCRIBE NODE command must be used.