Log Message:
-----------
Added some "best practices" material concerning how to better cope
with DDL changes.

This also pointed to documenting more precisely what the Slonik
"execute script" command does.

Modified Files:
--------------
    slony1-engine/doc/adminguide:
        ddlchanges.sgml (r1.6 -> r1.7)
        slonik_ref.sgml (r1.7 -> r1.8)

-------------- next part --------------
Index: slonik_ref.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/slonik_ref.sgml,v
retrieving revision 1.7
retrieving revision 1.8
diff -Ldoc/adminguide/slonik_ref.sgml -Ldoc/adminguide/slonik_ref.sgml -u -w -r1.7 -r1.8
--- doc/adminguide/slonik_ref.sgml
+++ doc/adminguide/slonik_ref.sgml
@@ -1,4 +1,3 @@
-<!-- $Id$ -->
 <article id="slonikcommands">
   <title>Slonik Command Summary</title>
   <sect1 id="slonikintro">
@@ -1381,9 +1380,9 @@
    <refsect1>
     <title>Description</title>
     
-    <para> Causes a node (subscriber) to start replicating a set of tables
-     either from the origin or from another provider node, which must be an
-     active, forwarding subscriber itself.</para>
+    <para> 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.</para>
     
     <para> The application tables contained in the set must already
      exist and should ideally be empty. The current version of
@@ -1416,13 +1415,13 @@
      
 
      <note><para> If you need to revise subscription information for a
-       node, you may 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 <emphasis>
-	different </emphasis> provider node, or for a node to become a
-       <quote>forwarding</quote> subscriber so it may later become the
-       provider for a later subscriber.</para> </note>
+       node, you <emphasis>also</emphasis> 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
+       <emphasis> different </emphasis> provider node, or for a node to
+       become a <quote>forwarding</quote> subscriber so it may later
+       become the provider for a later subscriber.</para> </note>
 
      <variablelist>
       <varlistentry><term><literal> ID = ival </literal></term>
@@ -1805,6 +1804,16 @@
     <para> See also the warnings in <link linkend="ddlchanges">
     Database Schema Changes (DDL)</link>.</para>
     
+    <para> Note that at the start of this event, all tables in the
+    specified set are unlocked via the function
+    <function>alterTableRestore(tab_id)</function>.  After the SQL
+    script has run, they are returned to <quote>replicating
+    state</quote> using
+    <function>alterTableForReplication(tab_id)</function>.  This means
+    that all of these tables are locked by this <application> slon
+    </application> process for the duration of the SQL script
+    execution.</para>
+    
    </refsect1>
    <refsect1><title>Example</title>
     <programlisting>
@@ -1887,7 +1896,7 @@
    </refsect1>
   </refentry>
  </reference>
-
+</article>
 <!-- Keep this comment at the end of the file
 Local variables:
 mode:sgml
Index: ddlchanges.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/ddlchanges.sgml,v
retrieving revision 1.6
retrieving revision 1.7
diff -Ldoc/adminguide/ddlchanges.sgml -Ldoc/adminguide/ddlchanges.sgml -u -w -r1.6 -r1.7
--- doc/adminguide/ddlchanges.sgml
+++ doc/adminguide/ddlchanges.sgml
@@ -9,18 +9,27 @@
 get rather deranged because they disagree on how particular tables are
 built.</para>
 
-<para>If you pass the changes through <productname>Slony-I</productname>
-via the <command><link linkend="stmtddlscript">EXECUTE SCRIPT</link></command>
- (slonik) /<function>ddlscript(set,script,node)</function> (stored function),
+<para>If you pass the changes through
+<productname>Slony-I</productname> via the <command><link
+linkend="stmtddlscript">EXECUTE SCRIPT</link></command> (slonik)
+/<function>ddlscript(set,script,node)</function> (stored function),
 this allows you to be certain that the changes take effect at the same
 point in the transaction streams on all of the nodes.  That may not be
-too important if you can take something of an outage to do schema
+so important if you can take something of an outage to do schema
 changes, but if you want to do upgrades that take place while
 transactions are still winding their way through your systems, this is
 necessary.</para>
 
-<para>It's worth making a couple of comments on <quote>special things</quote>
-about <command><link linkend="stmtddlscript">EXECUTE SCRIPT</link></command>:</para>
+<para>It is also necessary to use <command> EXECUTE SCRIPT</command>
+if you alter tables so as to change their schemas.  If you do not,
+then you may run into the problems <link linkend="neededexecddl">
+described here </link> where triggers on modified tables do not take
+account of the schema change.  This has the potential to corrupt data
+on subscriber nodes.  </para>
+
+<para>It's worth making a couple of comments on <quote>special
+things</quote> about <command><link linkend="stmtddlscript">EXECUTE
+SCRIPT</link></command>:</para>
 
 <itemizedlist>
 
@@ -68,6 +77,35 @@
 <ulink url="http://www.varlena.com/varlena/GeneralBits/88.php">
 Varlena General Bits</ulink></para>
 
+<sect2><title> Testing DDL Changes </title>
+
+<para> A method for testing DDL changes has been pointed out as a
+likely <quote>best practice.</quote>
+
+<para> You <emphasis>need</emphasis> to test DDL scripts in a
+non-destructive manner.
+
+<para> The problem is that if nodes are, for whatever reason, at all
+out of sync, replication is likely to fall over, and this takes place
+at what is quite likely one of the most inconvenient times, namely the
+moment when you wanted it to <emphasis> work. </emphasis>
+
+<para> You may indeed check to see if schema scripts work well or
+badly, by running them by hand, against each node, adding <command>
+BEGIN; </command> at the beginning, and <command> ROLLBACK; </command>
+at the end, so that the would-be changes roll back.
+
+<para> If this script works OK on all of the nodes, that suggests that
+it should work fine everywhere if executed via Slonik.  If problems
+are encountered on some nodes, that will hopefully allow you to fix
+the state of affairs on those nodes so that the script
+<emphasis>will</emphasis> run without error.
+
+<warning> <para> If the SQL script contains a <command> COMMIT;
+</command> somewhere before the <command> ROLLBACK; </command>, that
+may allow changes to go in unexpectedly.  </para>
+</warning>
+</sect2>
 </sect1>
 </article>
 <!-- Keep this comment at the end of the file