Log Message:
-----------
Documentation improvements

Drew in the material from the wiki about how to modify Slony-I clusters

Dropped out some obsolete material about obsolete Perl scripts that
(badly!) generated listen paths

Tags:
----
REL_1_1_STABLE

Modified Files:
--------------
    slony1-engine/doc/adminguide:
        addthings.sgml (r1.11 -> r1.11.2.1)
        bestpractices.sgml (r1.9.2.2 -> r1.9.2.3)
        faq.sgml (r1.40.2.5 -> r1.40.2.6)
        listenpaths.sgml (r1.16 -> r1.16.2.1)
        logshipping.sgml (r1.9.2.2 -> r1.9.2.3)

-------------- next part --------------
Index: addthings.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/addthings.sgml,v
retrieving revision 1.11
retrieving revision 1.11.2.1
diff -Ldoc/adminguide/addthings.sgml -Ldoc/adminguide/addthings.sgml -u -w -r1.11 -r1.11.2.1
--- doc/adminguide/addthings.sgml
+++ doc/adminguide/addthings.sgml
@@ -7,14 +7,13 @@
 
 <para>This can be fairly easily remedied.</para>
 
-<para>You cannot directly use <xref linkend="slonik">
-<xref linkend="stmtsetaddtable"> or <xref linkend="stmtsetaddsequence">
-in order to add tables and sequences
-to a replication set that is presently replicating; you must instead
-create a new replication set.  Once it is identically subscribed
-(e.g. - the set of providers and subscribers is <emphasis>entirely
-identical</emphasis> to that for the set it is to merge with), the
-sets may be merged together using <xref
+<para>You cannot directly use <xref linkend="slonik"> <xref
+linkend="stmtsetaddtable"> or <xref linkend="stmtsetaddsequence"> in
+order to add tables and sequences to a replication set that is
+presently replicating; you must instead create a new replication set.
+Once it is identically subscribed (e.g. - the set of providers and
+subscribers is <emphasis>entirely identical</emphasis> to that for the
+set it is to merge with), the sets may be merged together using <xref
 linkend="stmtmergeset">.</para>
 
 <para>Up to and including 1.0.2, there was a potential problem where
@@ -45,6 +44,145 @@
 successfully processed before going on to the next.  It's way easier
 to fix one thing that has broken than to piece things together after
 the interaction of five things that have all broken.</para>
+
+<itemizedlist>
+<listitem><para> Adding a table to replication </para>
+
+<para> &slony1; does not allow you to add a table to a replication set
+that is already being replicated. In principle, it would certainly be
+<emphasis>possible;</emphasis> what would happen is that the
+SET_ADD_TABLE event would lead to the relevant code from the
+SUBSCRIBE_SET event being invoked to initialize the table. That would,
+regrettably, significantly complicate the logic of all of these
+components, so this is not permitted. </para>
+
+<para>Instead, what you must do is thus:
+
+<itemizedlist>
+<listitem><para> Add the new table on each node. </para>
+
+<para> In principle, <xref linkend="stmtddlscript"> could be used for
+this, but the fact that this leads to <link linkend="locking"> Locking
+Issues </link> and requires altering <emphasis>all</emphasis> tables
+in some existing replication set, on <emphasis>all</emphasis> nodes,
+makes <xref linkend="stmtddlscript"> an unattractive approach on a
+busy system.  This breaks the &slony1; feature that you <quote>don't
+have to interrupt normal activity to introduce replication.</quote>
+</para>
+
+<para> Instead, you can add the table via
+<application>psql</application> on each node.
+
+</para> </listitem>
+
+<listitem><Para> Create a new replication set <xref linkend="stmtcreateset">
+</para></listitem>
+<listitem><para> 
+Add the table to the new set <xref linkend="stmtsetaddtable"> 
+</para></listitem>
+<listitem><para> 
+Request subscription <xref linkend="stmtsubscribeset"> for this new set. If there are several nodes, you will need to <xref linkend="stmtsubscribeset"> once for each node that should subscribe.
+</para></listitem>
+<listitem><para> 
+Once the subscriptions have all been set up so that the new set has an identical set of subscriptions to the old set, you can merge the new set in alongside the old one via <xref linkend="stmtmergeset">
+</itemizedlist>
+</listitem>
+<listitem><para> How to add columns to a replicated table </para>
+
+<para> This also answers the question <quote>How do I rename columns
+on a replicated table?</quote>, and, more generally, other questions
+to the effect of <quote>How do I modify the definitions of replicated
+tables?</quote></para>
+
+<para>If you change the <quote>shape</quote> of a replicated table, this needs to take place at exactly the same point in all of the <quote>transaction streams</quote> on all nodes that are subscribed to the set containing the table.</para>
+
+<para> Thus, the way to do this is to construct an SQL script consisting of the DDL changes, and then submit that script to all of the nodes via the Slonik command <xref linkend="stmtddlscript">.
+
+<para> There are a number of <quote>sharp edges</quote> to note...
+<itemizedlist>
+    <listitem><para> You absolutely <emphasis>must not</emphasis> include transaction control commands, particularly <command>BEGIN</command> and <command>COMMIT</command>, inside these DDL scripts. &slony1; wraps DDL scripts with a <command>BEGIN</command>/<command>COMMIT</command> pair; adding extra transaction control will mean that parts of the DDL will commit outside the control of &slony1; </para></listitem>
+
+    <listitem><Para> Avoid, if possible, having quotes in the DDL script </para> </listitem>
+</itemizedlist>
+
+</para></listitem>
+<listitem><para> How to remove replication for a node
+<para> You will want to remove the various &slony1; components connected to the database(s).</para>
+
+<para> We will just consider, for now, doing this to one node. If you have multiple nodes, you will have to repeat this as many times as necessary.</para>
+
+<para> Components to be Removed: </para>
+<itemizedlist>
+<listitem><para>    Log Triggers / Update Denial Triggers 
+
+</para></listitem>
+<listitem><para>    The "cluster" schema containing &slony1; tables indicating the state of the node as well as various stored functions 
+</para></listitem>
+<listitem><para>
+    <xref linkend="slon"> process that manages the node 
+</para></listitem>
+<listitem><para>
+    Optionally, the SQL and pl/pgsql scripts and &slony1; binaries that are part of the &postgres; build. (Of course, this would make it challenging to restart replication; it is unlikely that you truly need to do this...) 
+</para></listitem>
+</itemizedlist>
+
+<para> How To Conveniently Handle Removal</para>
+<itemizedlist>
+<listitem><para>
+    You may use the Slonik <xref linkend="stmtdropnode"> command to remove the node from the cluster. This will lead to the triggers and everything in the cluster schema being dropped from the node. The <xref linkend="slon"> process will automatically die off. 
+</para></listitem>
+<listitem><para>
+
+    In the case of a failed node (where you used <xref linkend="stmtfailover"> to switch to another node), you may need to use <xref linkend="stmtuninstallnode"> to drop out the triggers and schema and functions. 
+</para></listitem>
+<listitem><para>
+
+    If the above things work out particularly badly, you could submit the SQL command <command>DROP SCHEMA "_ClusterName" CASCADE;</command>, which will drop out &slony1; functions, tables, and triggers alike. 
+</para></listitem>
+</itemizedlist>
+</listitem>
+
+<listitem><para> Adding A Node To Replication</para>
+
+<para>Things are not fundamentally different whether you are adding a brand new, fresh node, or if you had previously dropped a node and are recreating it. In either case, you are adding a node to replication. </para>
+
+<para>The needful steps are thus... </para>
+<itemizedlist>
+<listitem><para>
+   Determine the node number and any relevant DSNs for the new node.  Use &postgres; command <command>createdb</command> to create the database; add the table definitions for the tables that are to be replicated, as &slony1; does not automatically propagate that information.
+</para></listitem>
+<listitem><para>
+   If the node had been a failed node, you may need to issue the <xref linkend="slonik"> command <xref linkend="stmtdropnode"> in order to get rid of its vestiges in the cluster, and to drop out the schema that &slony1; creates.
+</para></listitem>
+<listitem><para>
+    Issue the slonik command <xref linkend="stmtstorenode"> to establish the new node.
+</para></listitem>
+<listitem><para>
+    At this point, you may start a <xref linkend="slon">  daemon against the new node. It may not know much about the other nodes yet, so the logs for this node may be pretty quiet.
+</para></listitem>
+<listitem><para>
+    Issue the slonik command <xref linkend="stmtstorepath"> to indicate how <xref linkend="slon"> processes are to communicate with the new node.  In &slony1; version 1.1 and later, this will then automatically generate <link linkend="listenpaths"> listen path </link> entries; in earlier versions, you will need to use <xref linkend="stmtstorelisten"> to generate them manually.
+</para></listitem>
+<listitem><para>
+   Issue the slonik command <xref linkend="stmtsubscribeset"> to subscribe the node to some replication set. 
+</para></listitem>
+</itemizedlist>
+</listitem>
+
+<listitem><para> How do I reshape the subscriptions?
+
+<para> For instance, I want subscriber node 3 to draw data from node
+1, when it is presently drawing data from node 2. </para>
+
+<para> This isn't a case for <xref linkend="stmtmoveset">; we're not
+shifting the origin, just reshaping the subscribers. </para>
+
+<para> For this purpose, you can simply submit <xref
+linkend="stmtsubscribeset"> requests to <emphasis>revise</emphasis>
+the subscriptions.  Subscriptions will not be started from scratch;
+they will merely be reconfigured.  </para></listitem>
+
+</itemizedlist>
 </sect1>
 <!-- Keep this comment at the end of the file
 Local variables:
Index: bestpractices.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/bestpractices.sgml,v
retrieving revision 1.9.2.2
retrieving revision 1.9.2.3
diff -Ldoc/adminguide/bestpractices.sgml -Ldoc/adminguide/bestpractices.sgml -u -w -r1.9.2.2 -r1.9.2.3
--- doc/adminguide/bestpractices.sgml
+++ doc/adminguide/bestpractices.sgml
@@ -145,10 +145,11 @@
 <emphasis>acceptable</emphasis> to use a <quote>candidate primary key.</quote></para>
 
 <para> It is <emphasis>not recommended</emphasis> that a
-&slony1;-defined key be used to introduce a candidate primary key, as
-this introduces the possibility that updates to this table can fail
-due to the introduced unique index, which means that &slony1; has
-introduced a new failure mode for your application.</para>
+&slony1;-defined key (created via <xref linkend="stmttableaddkey">) be
+used to introduce a candidate primary key, as this introduces the
+possibility that updates to this table can fail due to the introduced
+unique index, which means that &slony1; has introduced a new failure
+mode for your application.</para>
 </listitem>
 
 <listitem>
Index: logshipping.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/logshipping.sgml,v
retrieving revision 1.9.2.2
retrieving revision 1.9.2.3
diff -Ldoc/adminguide/logshipping.sgml -Ldoc/adminguide/logshipping.sgml -u -w -r1.9.2.2 -r1.9.2.3
--- doc/adminguide/logshipping.sgml
+++ doc/adminguide/logshipping.sgml
@@ -168,7 +168,9 @@
 <command>SET_ADD_TABLE</command>,
 <command>SET_ADD_SEQUENCE</command>,
 <command>STORE_TRIGGER</command>,
-<command>DROP_TRIGGER</command>,</para></listitem>
+<command>DROP_TRIGGER</command>,
+<command>TABLE_ADD_KEY</command>
+</para></listitem>
 
 </itemizedlist>
 </para>
Index: listenpaths.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/listenpaths.sgml,v
retrieving revision 1.16
retrieving revision 1.16.2.1
diff -Ldoc/adminguide/listenpaths.sgml -Ldoc/adminguide/listenpaths.sgml -u -w -r1.16 -r1.16.2.1
--- doc/adminguide/listenpaths.sgml
+++ doc/adminguide/listenpaths.sgml
@@ -203,12 +203,6 @@
 <function>RebuildListenEntries()</function> will be called to revise
 the listener paths.</para>
 
-<para> If you are running an earlier version of &slony1;, you may want
-to take a look at <xref linkend="regenlisten">, a Perl script which
-duplicates the functionality of the stored procedure in the form of a
-script that generates the <xref linkend="slonik"> requests to
-generate the listener paths.</para></sect2>
-
 </sect1>
 <!-- Keep this comment at the end of the file
 Local variables:
Index: faq.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/faq.sgml,v
retrieving revision 1.40.2.5
retrieving revision 1.40.2.6
diff -Ldoc/adminguide/faq.sgml -Ldoc/adminguide/faq.sgml -u -w -r1.40.2.5 -r1.40.2.6
--- doc/adminguide/faq.sgml
+++ doc/adminguide/faq.sgml
@@ -593,15 +593,9 @@
 structure of the replication <quote>tree</quote>
 changes.</para></listitem>
 
-<listitem><para> Version 1.1 should provide better tools to help
-manage this.</para>
-
-<para> In fact, it does.  <xref linkend="autolisten"> provides a
-heuristic to generate listener entries.  If you are still tied to
-earlier versions, a Perl script, <xref linkend="regenlisten">,
-provides a way of querying a live &slony1; instance and generating the
-<xref linkend="slonik"> commands to generate the listen path
-network.</para></listitem>
+<listitem><para> Version 1.1 provides better tools to help manage
+this.</para>
+</listitem>
 
 </itemizedlist></para>