<!--  -->
<sect1 id="subscribenodes"> <title>Subscribing Nodes</title>

<indexterm><primary>subscribing nodes</primary></indexterm>

<para>Before you subscribe a node to a set, be sure that you have
<xref linkend="slon"> processes running for both the provider and the
new subscribing node. If you don't have slons running, nothing will
happen, and you'll beat your head against a wall trying to figure out
what is going on.</para>

<para>Subscribing a node to a set is done by issuing the <xref
linkend="slonik"> command <xref linkend="stmtsubscribeset">. It may
seem tempting to try to subscribe several nodes to a set within a
single try block like this:

<programlisting>
try {
  echo 'Subscribing sets';
  subscribe set (id = 1, provider=1, receiver=2, forward=yes);
  subscribe set (id = 1, provider=1, receiver=3, forward=yes);
  subscribe set (id = 1, provider=1, receiver=4, forward=yes);
} on error {
  echo 'Could not subscribe the sets!';
  exit -1;
}
</programlisting></para>


<para> But you are just asking for trouble if you try to subscribe
sets in that fashion. The proper procedure is to subscribe one node at
a time, and to check the logs and databases before you move onto
subscribing the next node to the set. It is also worth noting that the
<quote>success</quote> within the above <xref linkend="slonik"> try
block does not imply that nodes 2, 3, and 4 have all been successfully
subscribed. It merely indicates that the slonik commands were
successfully received by the <application>slon</application> running
on the origin node.</para>

<para>A typical sort of problem that will arise is that a cascaded
subscriber is looking for a provider that is not ready yet.  In that
failure case, that subscriber node will <emphasis>never</emphasis>
pick up the provider.  It will get <quote>stuck</quote> waiting for
a past event to take place.  The other nodes will be convinced that it
is successfully subscribed (because no error report ever made it back
to them); a request to unsubscribe the node will be
<quote>blocked</quote> because the node is stuck on the attempt to
subscribe it.</para>

<para>When you subscribe a node to a set, you should see something
like this in your <application>slon</application> logs for the
provider node:

<screen>
DEBUG2 remoteWorkerThread_3: Received event 3,1059 SUBSCRIBE_SET
</screen>
</para>
<para>You should also start seeing log entries like this in the
<application>slon</application> logs for the subscribing node:

<screen>
DEBUG2 remoteWorkerThread_1: copy table public.my_table
</screen>
</para>
<para>It may take some time for larger tables to be copied from the
provider node to the new subscriber. If you check the pg_stat_activity
table on the provider node, you should see a query that is copying the
table to stdout.
</para>
<para>The table <envar>sl_subscribe</envar> on both the provider, and the new
subscriber should contain entries for the new subscription:

<screen>
 sub_set | sub_provider | sub_receiver | sub_forward | sub_active
---------+--------------+--------------+-------------+------------
      1  |            1 |            2 |           t |         t
</screen>
</para>
<para>A final test is to insert a row into one of the replicated
tables on the origin node, and verify that the row is copied to the
new subscriber.
</para>

</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:"slony.sgml"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->
