Skip to content
Browse files

Revise documentation to better describe the log trigger handling

by EXECUTE SCRIPT, and the appropriate procedures for manually
altering DDL.
  • Loading branch information...
1 parent f46a9a4 commit b025625736b78ead1559ed39a1fe145974bf281b Christopher Browne committed Jun 15, 2011
Showing with 69 additions and 25 deletions.
  1. +58 −25 doc/adminguide/ddlchanges.sgml
  2. +11 −0 doc/adminguide/slonik_ref.sgml
View
83 doc/adminguide/ddlchanges.sgml
@@ -74,44 +74,77 @@ DDL change succeeds the next time slon attempts it.</para></listitem>
<sect2>
<title>Applying DDL Changes Directly</title>
-<para>DDL changes can be applied directly on a node through an
-application such as psql. The DDL changes will not be replicated by &slony1;
-and therefore must be manually applied to every relevant node.
-The following points should be kept in mind when applying DDL changes
-directly.
+
+<para>DDL changes can be applied directly on a node through an
+application such as <command>psql</command>. The DDL changes will not
+be replicated by &slony1; and therefore must be manually applied to
+every relevant node. The following points should be kept in mind when
+applying DDL changes directly.
+
<itemizedlist>
-<listitem><para>While DDL changes are not replicated any
-INSERT,UPDATE,DELETE statements that you execute will be replicated.
-This means that you should put DDL changes inside of the same script
-as DML commands because the script will then not behave properly when
-you execute it on other nodes</para></listitem>
+
+<listitem><para>While DDL changes are not automatically replicated,
+any <command>INSERT,UPDATE,DELETE</command> statements that you
+execute will be captured for replication, when run against the origin
+node. This means that you should not include DDL changes and DML
+inside the same script when apply DDL directly, because the script
+will not behave properly when you execute it on other nodes.</para>
+
+<para> If you, instead, apply DDL using <command>EXECUTE
+SCRIPT</command>, it is fine to intersperse DDL and DML within the
+script, as &slony1; handles that appropriately.</para>
+
+</listitem>
<listitem><para>You are responsible for ensuring that your scripts get
-applied on all other nodes at the correct point during the replication
-stream. The best way of doing this with respect to adding and deleting
-columns is to make sure that new columns always get added on the
-replica nodes first and that columns being removed get dropped from the
-master before they are dropped from the replicas.</para></listitem>
+applied on all other nodes at the correct point in the replication
+stream (<emphasis>e.g.</emphasis> - on or before the appropriate SYNC
+event). The best way of doing this with respect to adding and
+deleting columns is to make sure that new columns always get added on
+the replica nodes first and that columns being removed are dropped
+from the master before they are dropped from the replicas. That way,
+new columns are always available on the subscriber on or before the
+time they will be needed, and obsolete ones remain on the subscriber
+until after the last possible reference to them has been
+replicated.</para>
+
+<warning><para> If columns being added or dropped are mandatory (NOT
+NULL) or have default values, you will need to go through a longer
+process to ensure constraints are satisfied at each point in time on
+all nodes.</para>
+
+<para> For instance, if dropping a column that has a NOT NULL
+constraint, it may take multiple ALTER TABLE statements on each node
+in order to successfully accomplish this, as the constraint needs to
+be relaxed first.</para>
+
+</warning></listitem>
<listitem><para>DDL changes that rename a replicated table do not
inform &slony1; of the new table name. If you change then name of
a replicated table you must allow &slony1; to find the new table name
by calling <xref linkend="function.updaterelname-integer-integer">
</para>
</listitem>
+
<listitem>
-<para>DDL changes that alter either a primary key, a unique constraint that
-slony is using, or DDL changes that drop columns that come before the
-key or unique constraint that &slony1; is using will require &slony1; too reconfigure the arguments
-on the logtrigger. The function <xref linkend="function.repair-log-triggers-only-locked-boolean"> will reconfigure the trigger arguments of any &slony1; log triggers
-that are out of date. If true is passed to this function it will only adjust
-tables that are already locked by the current transaction (if you perform your
-alter table in a transaction and then call repair_log_triggers as part of the same
-transaction then the altered tables will be locked).
-If you pass false to this function then the function will obtain
-an exclusive lock on any table that needs to be reconfigured.
+<para>DDL changes that alter either a primary key, a unique constraint
+that slony is using, or DDL changes that drop columns that come before
+the key or unique constraint that &slony1; is using will require
+&slony1; too reconfigure the arguments on the logtrigger. The function
+<xref linkend="function.repair-log-triggers-only-locked-boolean"> will
+reconfigure the trigger arguments of any &slony1; log triggers that
+are out of date. If <option>true</option> is passed to this function
+it will only adjust tables that are already locked by the current
+transaction (if you perform your <command>alter table</command> within
+a transaction and then call <function>repair_log_triggers()</function>
+as part of the same transaction then the altered tables will be
+locked). If you pass <option>false</option> to this function then the
+function will obtain an exclusive lock on any table that needs the
+trigger to be reconfigured.
</para>
</listitem>
+
</itemizedlist>
</sect1>
View
11 doc/adminguide/slonik_ref.sgml
@@ -2591,6 +2591,17 @@ EXECUTE SCRIPT (
<para> In version 2.0, the default value for <envar>EVENT
NODE</envar> was removed, so a node must be specified.</para>
+ <para> As of version 2.0.7, the log triggers on all replicated
+ tables are checked to ensure their parameters match the primary key
+ on the table. If they <emphasis>do not</emphasis> match, those
+ tables that are exclusively locked as a result of the DDL request
+ will have the triggers recreated to match the primary key. Tables
+ that do not have an exclusive lock will <emphasis>not</emphasis> be
+ corrected, but a warning message will be generated. The function
+ <xref linkend="function.repair-log-triggers-only-locked-boolean">
+ may be used manually to correct the triggers on those
+ tables.</para>
+
</refsect1>
</refentry>

0 comments on commit b025625

Please sign in to comment.
Something went wrong with that request. Please try again.