Log Message:
-----------
Numerous updates to documentation based on Brian A. Seklecki's recent
questions on the mailing list.
---------------------------------------------------------------------
Brian A. Seklecki wrote:


>>All:
>>
>>One of the big things missing from the "Introduction" docs is a more
>>thorough explanation of "How Slony Works". As a DBA or SysAdmin,
>>that's the first question that I desire to have answered by a manual,
>>and serves to help me better understand all future operations and
>>procedures, especially troubleshooting.

Thanks, you're one of the first to do any "detailed criticism" of the
docs...

>>For example, in introduction.html, it is stated "namely that Slony-I
>>operates using triggers", but what we should probably be saying is:
>>
>>   "For every table, sequence, or database object that is replicated,
>>Slony is able to replicate changes by installing a trigger that
>>catches updates, inserts, and deletes."
>>
>>Also, "sl_log" isn't mentioned until Chapter/Page 3 and then again in
>>7. However, no mention of the "_${repset}_cluster" schema is made at
>>all prior to that point. It's mentioned in Ch/Pg 5, but the purpose
>>isn't explained. Somewhere prior mention of "sl_log_1*", there should
>>be a paragraph explaining design:
>>
>>   "For every database participating in replication, Slony creates a  
>>schema named "_${repset}_cluster" at initialization time to maintain  
>>configuration and status data. Most specifically, nodes acting as     
>>master/sources maintain a _${repset}_cluster.sl_log_{1,2} table to    
>>log/cache of all changes to master which are to be propagated to      
>>slaves." (or something to that effect, check me)

That is in the section on defining clusters, now.

>>Also, it's also not explicitly stated anywhere that only Sequences and 
>>Tables are replicated.  Although that may seem rudimentary, a it's only 
>>briefly touched on.

That is now explicitly mentioned in several places.


>>It should probably be explicitly stated: "A database consists of
>>Casts, Languages, Schemas, Tables, Indexes, Constraints, Sequences,
>>Triggers, Functions, Views, Types, etc.; however Slony only replicates
>>Tables, Indexes, and Sequences. All other objections constitute DDL
>>changes that must be manually replicated by the administrator." (or
>>something to that effect, check me).

I am a little reluctant to try to enumerate *all* types of database
objects. Alan Perlis points out that if you have a procedure with 10
parameters, you probably have missed some :-) . The same is likely true
here. But I have revised the wording about DDL changes a bit to make it
clearer what is and isn't replicated.


>>Another thing to add to the wishlist: Example real-world scenarios
>>DBAs may encountered and recommended procedures to follow.

There is a document called "addthings.sgml" to which I have been adding
such of these scenarios as seem to come along.

Beefing it up with "recipes" for how to do additional things is
certainly fair game.

>>Also, it wouldn't hurt to break out XFig or Dia and add some explanatory 
>>diagrams explaining concepts.

I'm not much of a graphical person, which is why the paucity of diagrams...

>>Thoughts?
>>
>>(And yes, I'm will to help write docs!) >:}
>>  
---------------------------------------------------------------------

Tags:
----
REL_1_1_STABLE

Modified Files:
--------------
    slony1-engine/doc/adminguide:
        bestpractices.sgml (r1.9.2.3 -> r1.9.2.4)
        cluster.sgml (r1.10 -> r1.10.2.1)
        filelist.sgml (r1.13.2.2 -> r1.13.2.3)
        intro.sgml (r1.17.2.1 -> r1.17.2.2)
        man.sgml (r1.3.2.1 -> r1.3.2.2)
        prerequisites.sgml (r1.18.2.2 -> r1.18.2.3)
        slon.sgml (r1.16.2.1 -> r1.16.2.2)
        slonik_ref.sgml (r1.27.2.5 -> r1.27.2.6)
        slony.sgml (r1.20.2.3 -> r1.20.2.4)

-------------- next part --------------
Index: slon.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/slon.sgml,v
retrieving revision 1.16.2.1
retrieving revision 1.16.2.2
diff -Ldoc/adminguide/slon.sgml -Ldoc/adminguide/slon.sgml -u -w -r1.16.2.1 -r1.16.2.2
--- doc/adminguide/slon.sgml
+++ doc/adminguide/slon.sgml
@@ -298,7 +298,7 @@
      <para>
       <envar>archive_dir</envar> indicates a directory in which to
       place a sequence of <command>SYNC</command> archive files for
-      use in &logship; mode.
+      use in &logshiplink; mode.
      </para>
     </listitem>
    </varlistentry>
Index: slonik_ref.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/slonik_ref.sgml,v
retrieving revision 1.27.2.5
retrieving revision 1.27.2.6
diff -Ldoc/adminguide/slonik_ref.sgml -Ldoc/adminguide/slonik_ref.sgml -u -w -r1.27.2.5 -r1.27.2.6
--- doc/adminguide/slonik_ref.sgml
+++ doc/adminguide/slonik_ref.sgml
@@ -985,8 +985,7 @@
 
     <caution><para> <command>TABLE ADD KEY</command> <emphasis>should
     not be used</emphasis> if you can possibly avoid it.  It is
-    emphatically <emphasis>not</emphasis> a <link
-    linkend="bestpractices"> Best Practice.</link> </para>
+    emphatically <emphasis>not</emphasis> a &bestpracticelink;. </para>
 
     <para> The absence of a proper primary key should be a big red
     flag that the database schema is <emphasis>broken.</emphasis> The
@@ -994,9 +993,8 @@
     proper primary key, not to have &slony1; <quote>fake</quote> one
     up.</para> 
 
-    <para>It is <emphasis>not</emphasis> supported in <link
-    linkend="logshipping"> log shipping </link>, and will not
-    be.</para> </caution>
+    <para>It is <emphasis>not</emphasis> supported in &logshiplink;,
+    and will not be.</para> </caution>
     
     <para> This uses &funtableaddkey;. </para>
    </refsect1>
Index: intro.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/intro.sgml,v
retrieving revision 1.17.2.1
retrieving revision 1.17.2.2
diff -Ldoc/adminguide/intro.sgml -Ldoc/adminguide/intro.sgml -u -w -r1.17.2.1 -r1.17.2.2
--- doc/adminguide/intro.sgml
+++ doc/adminguide/intro.sgml
@@ -136,15 +136,36 @@
 <para>&slony1; does not automatically propagate schema changes, nor
 does it have any ability to replicate large objects.  There is a
 single common reason for these limitations, namely that &slony1;
-operates using triggers, and neither schema changes nor large object
-operations can raise triggers suitable to tell &slony1; when those
-kinds of changes take place.</para>
-
-<para>There is a capability for &slony1; to propagate DDL changes if
-you submit them as scripts via the <application>slonik</application>
-<xref linkend="stmtddlscript"> operation.  That is not
-<quote>automatic;</quote> you have to construct an SQL DDL script and
-submit it, and there are a number of further <link
+collects updates using triggers, and neither schema changes nor large
+object operations are able to triggers suitable to inform &slony1;
+when those sorts of changes take place.  As a result, the only
+database objects where &slony1; can replicate updates are tables and
+sequences.  </para>
+
+<para> Note that with the <emphasis>use</emphasis> of triggers comes
+some additional <emphasis>fiddling around with triggers</emphasis>.
+On the <quote>origin</quote> for each replicated table, an additional
+trigger is added which runs the stored procedure <xref
+linkend="function.logtrigger">.  On each subscriber, tables are
+augmented with a trigger that runs the <xref
+linkend="function.denyaccess"> function; this function prevents
+anything other than the <xref linkend="slon"> process from updating
+data in replicated tables.  In addition, any
+<emphasis>other</emphasis> triggers and rules on replicated tables are
+<emphasis>suppressed</emphasis> on the subscribers: This is done by
+pointing them, in the system table, to the primary key index instead
+of to the table itself.  This represents something of a
+<quote>corruption</quote> of the data dictionary, and is why you
+should not directly use <application>pg_dump</application> to dump
+schemas on subscribers. </para>
+
+<para>There is a capability for &slony1; to propagate other kinds of
+database modifications, notably DDL changes, if you submit them as
+scripts via the <application>slonik</application> <xref
+linkend="stmtddlscript"> operation.  That is not handled
+<quote>automaticly;</quote> you, as a database administrator, will
+have to construct an SQL DDL script and submit it, via <xref
+linkend="stmtddlscript"> and there are a number of further <link
 linkend="ddlchanges"> caveats.</link></para>
 
 <para>If you have those sorts of requirements, it may be worth
@@ -174,8 +195,8 @@
 people.</para>
 
 <para> &slony1; implements a particular model, namely that of
-asynchronous replication, using triggers, where a single
-<quote>origin</quote> may be replicated to multiple
+asynchronous replication, using triggers to collect table updates,
+where a single <quote>origin</quote> may be replicated to multiple
 <quote>subscribers</quote> including cascaded subscribers.</para>
 
 <para> There are a number of other replication models which are
Index: cluster.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/cluster.sgml,v
retrieving revision 1.10
retrieving revision 1.10.2.1
diff -Ldoc/adminguide/cluster.sgml -Ldoc/adminguide/cluster.sgml -u -w -r1.10 -r1.10.2.1
--- doc/adminguide/cluster.sgml
+++ doc/adminguide/cluster.sgml
@@ -8,7 +8,16 @@
 <para>A &slony1; cluster is the basic grouping of database instances
 in which replication takes place.  It consists of a set of &postgres;
 database instances in which is defined a namespace specific to that
-cluster.</para>
+cluster.  For instance, if the cluster is called
+<envar>cbcluster</envar>, then &slony1; will define, at the
+initialization time for each node, a schema called
+<command>_cbcluster</command>, in which it then creates numerous
+tables that store &slony1; configuration and replication state
+information.  See <xref linkend="schema"> for more documentation about
+what is stored in that schema.  More specifically, the tables <xref
+linkend="table.sl-log-1"> and <xref linkend="table.sl-log-2"> log
+changes collected on the origin node as they are replicated to
+subscribers.  </para>
 
 <para>Each database instance in which replication is to take place is
 identified by a node number.</para>
@@ -22,10 +31,12 @@
 correspond to the shape of the environment, as opposed to (say) the
 order in which nodes were initialized.</para>
 
-<para>It may be that in version 1.1, nodes will also have a
-<quote>name</quote> attribute, so that they may be given more mnemonic names.
-In that case, the node numbers might remain somewhat cryptic; it will
-be the node name that is used to organize the cluster.</para>
+<para> In &slony1; version 1.1, the <xref linkend="stmtinclude"> and
+<xref linkend="stmtdefine"> statements allow you to create a sort of
+<quote>symbol table</quote> behind the scenes so that <xref
+linkend="slonik"> scripts can use names for nodes rather than cryptic
+numbers. </para>
+
 </sect1>
 
 <!-- Keep this comment at the end of the file
Index: bestpractices.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/bestpractices.sgml,v
retrieving revision 1.9.2.3
retrieving revision 1.9.2.4
diff -Ldoc/adminguide/bestpractices.sgml -Ldoc/adminguide/bestpractices.sgml -u -w -r1.9.2.3 -r1.9.2.4
--- doc/adminguide/bestpractices.sgml
+++ doc/adminguide/bestpractices.sgml
@@ -250,9 +250,9 @@
 lot of them, they may be a nuisance to read.)</para>
 
 <para> Unfortunately, if you invoke <xref linkend="slon"> from the
-command line, you could <emphasis>forget</emphasis> to include <link
-linkend="logshipping"> log shipping </link> configuration and thereby
-destroy the sequence of logs for a log shipping node. </para>
+command line, you could <emphasis>forget</emphasis> to include
+&logshiplink; configuration and thereby destroy the sequence of logs
+for a log shipping node. </para>
 </listitem>
 
 <listitem> <para> Unlike when command line options are used, the
@@ -262,8 +262,7 @@
 configuration file.  </para>
 
 <para> By putting the options in a file, you won't forget including
-any of them, so this is safer for <link linkend="logshipping"> log
-shipping. </link> </para>
+any of them, so this is safer for &logshiplink;. </para>
 </listitem>
 
 </itemizedlist>
Index: filelist.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/filelist.sgml,v
retrieving revision 1.13.2.2
retrieving revision 1.13.2.3
diff -Ldoc/adminguide/filelist.sgml -Ldoc/adminguide/filelist.sgml -u -w -r1.13.2.2 -r1.13.2.3
--- doc/adminguide/filelist.sgml
+++ doc/adminguide/filelist.sgml
@@ -36,7 +36,7 @@
 <!entity notation           SYSTEM "notation.sgml">
 <!entity problems           SYSTEM "problems.sgml">
 <!entity slonybook          SYSTEM "slony.sgml">
-<!entity logshipping        SYSTEM "logshipping.sgml">
+<!entity logshipfile        SYSTEM "logshipping.sgml">
 <!entity bestpractices      SYSTEM "bestpractices.sgml">
 <!entity locking            SYSTEM "locking.sgml">
 <!entity supportedplatforms SYSTEM "supportedplatforms.sgml">
Index: man.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/man.sgml,v
retrieving revision 1.3.2.1
retrieving revision 1.3.2.2
diff -Ldoc/adminguide/man.sgml -Ldoc/adminguide/man.sgml -u -w -r1.3.2.1 -r1.3.2.2
--- doc/adminguide/man.sgml
+++ doc/adminguide/man.sgml
@@ -9,7 +9,7 @@
   <!ENTITY slony1 "<PRODUCTNAME>Slony-I</PRODUCTNAME>">
   <!ENTITY postgres "<PRODUCTNAME>PostgreSQL</PRODUCTNAME>">
   <!ENTITY windows "<trademark>Windows</trademark>">
-  <!ENTITY logship "log shipping">
+  <!ENTITY logshiplink "log shipping">
   <!ENTITY rlocking " locking ">
   <!ENTITY rddlchanges "distribution documentation on DDL changes">
   <!ENTITY rplainpaths "distribution documentation on plain paths">
@@ -43,6 +43,7 @@
   <!ENTITY funsubscribeset "<function>subscribeset(integer,integer,integer,boolean)</function>">
   <!ENTITY slnode "<envar>sl_node</envar>">
   <!ENTITY slconfirm "<envar>sl_confirm</envar>">
+  <!ENTITY bestpracticelink "Best Practice">
 ]>
 
 <book id="slony">
Index: prerequisites.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/prerequisites.sgml,v
retrieving revision 1.18.2.2
retrieving revision 1.18.2.3
diff -Ldoc/adminguide/prerequisites.sgml -Ldoc/adminguide/prerequisites.sgml -u -w -r1.18.2.2 -r1.18.2.3
--- doc/adminguide/prerequisites.sgml
+++ doc/adminguide/prerequisites.sgml
@@ -230,16 +230,15 @@
 cluster as a whole.</para>
 
 <para>New in &slony1; version 1.1 is a feature whereby updates for a
-particular replication set may be serialized via a scheme called <link
-linkend="logshipping">log shipping. </link> The data stored in
-<envar>sl_log_1</envar> and <envar>sl_log_2</envar> is also written
-out to log files on disk.  These files may then be transmitted in any
-manner desired, whether via scp, FTP, burning them onto DVD-ROMs and
-mailing them, or, at the frivolous end of the spectrum, by recording
-them on a USB <quote>flash device</quote> and attaching them to birds,
-allowing some equivalent to <ulink
-url="http://www.faqs.org/rfcs/rfc1149.html"> transmission of IP
-datagrams on avian carriers - RFC 1149.</ulink> But whatever the
+particular replication set may be serialized via a scheme called
+&logshiplink;.  The data stored in <envar>sl_log_1</envar> and
+<envar>sl_log_2</envar> is also written out to log files on disk.
+These files may then be transmitted in any manner desired, whether via
+scp, FTP, burning them onto DVD-ROMs and mailing them, or, at the
+frivolous end of the spectrum, by recording them on a USB <quote>flash
+device</quote> and attaching them to birds, allowing some equivalent
+to <ulink url="http://www.faqs.org/rfcs/rfc1149.html"> transmission of
+IP datagrams on avian carriers - RFC 1149.</ulink> But whatever the
 transmission mechanism, this allows one way communications such that
 subscribers that use log shipping have no need of access to other
 &slony1; nodes.</para>
Index: slony.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/slony.sgml,v
retrieving revision 1.20.2.3
retrieving revision 1.20.2.4
diff -Ldoc/adminguide/slony.sgml -Ldoc/adminguide/slony.sgml -u -w -r1.20.2.3 -r1.20.2.4
--- doc/adminguide/slony.sgml
+++ doc/adminguide/slony.sgml
@@ -10,7 +10,7 @@
   <!ENTITY postgres "<PRODUCTNAME>PostgreSQL</PRODUCTNAME>">
   <!ENTITY nagios "<PRODUCTNAME>Nagios</PRODUCTNAME>">
   <!ENTITY windows "<trademark>Windows</trademark>">
-  <!ENTITY logship "<link linkend=logshipping>log shipping</link>">
+  <!ENTITY logshiplink "<link linkend=logshipping>log shipping</link>">
   <!ENTITY rlocking "<link linkend=locking> locking </link>">
   <!ENTITY rddlchanges "<xref linkend=ddlchanges>"> 
   <!ENTITY fundroplisten "<xref linkend=function.droplisten-integer-integer-integer>">
@@ -39,6 +39,7 @@
 <!ENTITY fununinstallnode "<xref linkend=function.uninstallnode>">
 <!ENTITY fununlockset "<xref linkend=function.unlockset-integer>">
 <!ENTITY fununsubscribeset "<xref linkend=function.unsubscribeset-integer-integer>">
+  <!ENTITY bestpracticelink "<link linkend=bestpractices>Best Practice</link>">
   <!ENTITY rmissingoids "<link linkend=missingoids>error messages indicating missing OIDs</link>">
   <!ENTITY slnode "<xref linkend=table.sl-node>">
   <!ENTITY slconfirm "<xref linkend=table.sl-confirm>">
@@ -89,7 +90,7 @@
  &locking;
  &addthings;
  &dropthings;
- &logshipping;
+ &logshipfile;
  &ddlchanges;
  &usingslonik;
  &adminscripts;