Log Message:
-----------
Added FAQ entry, revised intro (textual revisions), fixed formatting of
listenpaths.sgml a bit

Modified Files:
--------------
    slony1-engine/doc/adminguide:
        faq.sgml (r1.11 -> r1.12)
        intro.sgml (r1.5 -> r1.6)
        listenpaths.sgml (r1.8 -> r1.9)

-------------- next part --------------
Index: intro.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/intro.sgml,v
retrieving revision 1.5
retrieving revision 1.6
diff -Ldoc/adminguide/intro.sgml -Ldoc/adminguide/intro.sgml -u -w -r1.5 -r1.6
--- doc/adminguide/intro.sgml
+++ doc/adminguide/intro.sgml
@@ -4,87 +4,136 @@
 	<sect1>
 		<title>Why yet another replication system?</title>
 
-		<para><productname>Slony-I</productname> was born from an idea to create a replication system that was not tied
-to a specific version of PostgreSQL, which is allowed to be started and stopped on
-an existing database with out the need for a dump/reload cycle.</para>
-	</sect1>
-	<sect1>
-		<title>What <productname>Slony-I</productname> is</title>
-		<para><productname>Slony-I</productname> is a <quote>master to multiple slaves</quote> replication
-system supporting cascading and slave promotion.  The big picture for
-the development of <productname>Slony-I</productname> is as a master-slave system that includes
-all features and capabilities needed to replicate large databases to a
-reasonably limited number of slave systems.  <quote>Reasonable,</quote> in this
-context, is probably no more than a few dozen servers.  If the number
-of servers grows beyond that, the cost of communications becomes
-prohibitively high.</para>  
+<para><productname>Slony-I</productname> was born from an idea to
+create a replication system that was not tied to a specific version of
+PostgreSQL, which is allowed to be started and stopped on an existing
+database with out the need for a dump/reload cycle.</para> </sect1>
+
+<sect1> <title>What <productname>Slony-I</productname> is</title>
+
+<para><productname>Slony-I</productname> is a <quote>master to
+multiple slaves</quote> replication system supporting cascading and
+slave promotion.  The big picture for the development of
+<productname>Slony-I</productname> is as a master-slave system that
+includes all features and capabilities needed to replicate large
+databases to a reasonably limited number of slave systems.
+<quote>Reasonable,</quote> in this context, is probably no more than a
+few dozen servers.  If the number of servers grows beyond that, the
+cost of communications becomes prohibitively high.</para>
 
 		<para> See also <link linkend="slonylistenercosts"> SlonyListenerCosts
-</link> for a further analysis.</para>
+</link> for a further analysis of costs associated with having many
+nodes.</para>
 
-		<para> <productname>Slony-I</productname> is a system intended for data centers and backup sites,
-where the normal mode of operation is that all nodes are available all
-the time, and where all nodes can be secured.  If you have nodes that
-are likely to regularly drop onto and off of the network, or have
-nodes that cannot be kept secure, <productname>Slony-I</productname> may not be the ideal
+<para> <productname>Slony-I</productname> is a system intended for
+data centers and backup sites, where the normal mode of operation is
+that all nodes are available all the time, and where all nodes can be
+secured.  If you have nodes that are likely to regularly drop onto and
+off of the network, or have nodes that cannot be kept secure,
+<productname>Slony-I</productname> is probably not the ideal
 replication solution for you.</para>
 
+<para> Thus, examples of cases where
+<productname>Slony-I</productname> probably won't work out well would
+include:
+
+<itemizedlist>
+<listitem><para> Sites where connectivity is really <quote>flakey</quote>
+</para></listitem>
+<listitem><para> Replication to nodes that are unpredictably connected.
+
+<para> Replicating a pricing database from a central server to sales
+staff who connect periodically to grab updates.  </para></listitem>
+</itemizedlist>
+
 <para> There are plans for a <quote>file-based log shipping</quote>
 extension where updates would be serialized into files.  Given that,
 log files could be distributed by any means desired without any need
 of feedback between the provider node and those nodes subscribing via
-<quote>log shipping.</quote></para></sect1>
+<quote>log shipping.</quote></para>
 
+<para> But <productname>Slony-I</productname>, by only having a single
+origin for each set, is quite unsuitable for <emphasis> really
+</emphasis> asynchronous multiway replication.  For those that could
+use some sort of <quote>asynchronous multimaster replication with
+conflict resolution</quote> akin to what is provided by <productname>
+Lotus <trademark>Notes</trademark></productname> or the
+<quote>syncing</quote> protocols found on PalmOS systems, you will
+really need to look elsewhere.  These sorts of replication models are
+not without merit, but they represent problems that
+<productname>Slony-I</productname> does not attempt to address.</para>
 
-<sect1><title> <productname>Slony-I</productname> is not</title>
+</sect1>
 
-<para><productname>Slony-I</productname> is not a network management system.</para>  
 
-<para> <productname>Slony-I</productname> does not have any functionality within it to detect a
-node failure, or automatically promote a node to a master or other
-data origin.</para>
+<sect1><title> <productname>Slony-I</productname> is not</title>
 
-<para><productname>Slony-I</productname> is not multi-master; it's not a connection broker, and
-it doesn't make you coffee and toast in the morning.</para>
+<para><productname>Slony-I</productname> is not a network management
+system.</para>
 
-<para>(That being said, the plan is for a subsequent system, <productname>Slony-I</productname>I,
-to provide "multimaster" capabilities, and be "bootstrapped" using
-<productname>Slony-I</productname>.  But that is a separate project, and expectations for <productname>Slony-I</productname>
-should not be based on hopes for future projects.)</para></sect1>
+<para> <productname>Slony-I</productname> does not have any
+functionality within it to detect a node failure, or to automatically
+promote a node to a master or other data origin.  It is quite possible
+that you may need to do that; that will require that you combine some
+network tools that evaluate <emphasis> to your satisfaction
+</emphasis> which nodes are <quote>live</quote> and which nodes are
+<quote>dead</quote> along with some local policy to determine what to
+do under those circumstances.  <productname>Slony-I</productname> does
+not dictate policy to you.</para>
+
+<para><productname>Slony-I</productname> is not multi-master; it's not
+a connection broker, and it doesn't make you coffee and toast in the
+morning.</para>
+
+<para>That being said, the plan is for a subsequent system,
+<productname>Slony-II</productname>, to provide
+<quote>multimaster</quote> capabilities.  But that is a separate
+project, and expectations for <productname>Slony-I</productname>
+should not be based on hopes for future projects.</para></sect1>
 
-<sect1><title> Why doesn't <productname>Slony-I</productname> do automatic fail-over/promotion? 
+<sect1><title> Why doesn't <productname>Slony-I</productname> do
+automatic fail-over/promotion?
 </title>
 
 <para>This is the job of network monitoring software, not Slony.
-Every site's configuration and fail-over path is different.  For
+Every site's configuration and fail-over paths are different.  For
 example, keep-alive monitoring with redundant NIC's and intelligent HA
 switches that guarantee race-condition-free takeover of a network
-address and disconnecting the <quote>failed</quote> node vary in every
-network setup, vendor choice, hardware/software combination.  This is
-clearly the realm of network management software and not
-<productname>Slony-I</productname>.</para>
+address and disconnecting the <quote>failed</quote> node will vary
+based on network configuration, vendor choices, and the combinations
+of hardware and software in use.  This is clearly the realm of network
+management software and not <productname>Slony-I</productname>.</para>
+
+<para> Furthermore, choosing what to do based on the
+<quote>shape</quote> of the cluster represents local business policy.
+If <productname>Slony-I</productname> imposed failover policy on you,
+that might conflict with business requirements, thereby making
+<productname>Slony-I</productname> an unacceptable choice.</para>
 
-<para>Let <productname>Slony-I</productname> do what it does best: provide database replication.</para></sect1>
+<para>As a result, let <productname>Slony-I</productname> do what it
+does best: provide database replication.</para></sect1>
 
 <sect1><title> Current Limitations</title>
 
-<para><productname>Slony-I</productname> 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 <productname>Slony-I</productname>
-operates using triggers, and neither schema changes nor large object
-operations can raise triggers suitable to tell <productname>Slony-I</productname> when those
-kinds of changes take place.</para>
-
-<para>There is a capability for <productname>Slony-I</productname> to propagate DDL changes if
-you submit them as scripts via the <application>slonik</application>
-<command>EXECUTE SCRIPT</command> operation.  That is not
-<quote>automatic;</quote> you have to construct an SQL DDL script and submit
-it.</para>
+<para><productname>Slony-I</productname> 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 <productname>Slony-I</productname> operates using
+triggers, and neither schema changes nor large object operations can
+raise triggers suitable to tell <productname>Slony-I</productname>
+when those kinds of changes take place.</para>
+
+<para>There is a capability for <productname>Slony-I</productname> to
+propagate DDL changes if you submit them as scripts via the
+<application>slonik</application> <command>EXECUTE SCRIPT</command>
+operation.  That is not <quote>automatic;</quote> you have to
+construct an SQL DDL script and submit it.</para>
 
 <para>If you have those sorts of requirements, it may be worth
-exploring the use of <application>PostgreSQL</application> 8.0 <acronym>PITR</acronym> (Point In Time
-Recovery), where <acronym>WAL</acronym> logs are replicated to remote
-nodes.  Unfortunately, that has two attendant limitations:
+exploring the use of <application>PostgreSQL</application> 8.0
+<acronym>PITR</acronym> (Point In Time Recovery), where
+<acronym>WAL</acronym> logs are replicated to remote nodes.
+Unfortunately, that has two attendant limitations:
 
 <itemizedlist>
 	
@@ -113,26 +162,29 @@
 
 <itemizedlist>
 
-<listitem><para> It is necessary to have a sl_path entry allowing
-connection from each node to every other node.  Most will normally not
-need to be used for a given replication configuration, but this means
-that there needs to be n(n-1) paths.  It is probable that there will
-be considerable repetition of entries, since the path to "node n" is
-likely to be the same from everywherein the network.</para></listitem>
-
-<listitem><para> It is similarly necessary to have a sl_listen entry
-indicating how data flows from every node to every other node.  This
-again requires configuring n(n-1) "listener paths."</para></listitem>
+<listitem><para> It is necessary to have a <envar>sl_path</envar>
+entry allowing connection from each node to every other node.  Most
+will normally not need to be used for a given replication
+configuration, but this means that there needs to be n(n-1) paths.  It
+is probable that there will be considerable repetition of entries,
+since the path to <quote>node n</quote> is likely to be the same from
+everywhere throughout the network.</para></listitem>
+
+<listitem><para> It is similarly necessary to have a
+<envar>sl_listen</envar> entry indicating how data flows from every
+node to every other node.  This again requires configuring n(n-1)
+<quote>listener paths.</quote></para></listitem>
 
 <listitem><para> Each SYNC applied needs to be reported back to all of
 the other nodes participating in the set so that the nodes all know
-that it is safe to purge sl_log_1 and sl_log_2 data, as any
-<quote>forwarding</quote> node could potentially take over as <quote>master</quote>
-at any time.  One might expect SYNC messages to need to travel through
-n/2 nodes to get propagated to their destinations; this means that
-each SYNC is expected to get transmitted n(n/2) times.  Again, this
-points to a quadratic growth in communications costs as the number of
-nodes increases.</para></listitem>
+that it is safe to purge <envar>sl_log_1</envar> and
+<envar>sl_log_2</envar> data, as any <quote>forwarding</quote> node
+could potentially take over as <quote>master</quote> at any time.  One
+might expect SYNC messages to need to travel through n/2 nodes to get
+propagated to their destinations; this means that each SYNC is
+expected to get transmitted n(n/2) times.  Again, this points to a
+quadratic growth in communications costs as the number of nodes
+increases.</para></listitem>
 
 </itemizedlist></para>
 
Index: listenpaths.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/listenpaths.sgml,v
retrieving revision 1.8
retrieving revision 1.9
diff -Ldoc/adminguide/listenpaths.sgml -Ldoc/adminguide/listenpaths.sgml -u -w -r1.8 -r1.9
--- doc/adminguide/listenpaths.sgml
+++ doc/adminguide/listenpaths.sgml
@@ -12,8 +12,9 @@
 usage of cascaded subscribers (<emphasis>e.g.</emphasis> - subscribers
 that are subscribing through a subscriber node), you will have to be
 fairly careful about the configuration of <quote>listen paths</quote>
-via the Slonik <command> <link linkend="stmtstorelisten">STORE LISTEN</link></command> and
-<link linkend="stmtdroplisten"><command>DROP LISTEN</command></link>
+via the Slonik <command> <link linkend="stmtstorelisten">STORE
+LISTEN</link></command> and <link
+linkend="stmtdroplisten"><command>DROP LISTEN</command></link>
 statements that control the contents of the table sl_listen.</para>
 
 <para>The <quote>listener</quote> entries in this table control where
@@ -22,20 +23,20 @@
 <quote>parent</quote> from whom they are getting updates, but in
 reality, they need to be able to receive messages from
 <emphasis>all</emphasis> nodes in order to be able to conclude that
-<command>sync</command>s have been received everywhere, and that, therefore,
-entries in sl_log_1 and sl_log_2 have been applied everywhere, and can
-therefore be purged.  this extra communication is needful so
-<productname>Slony-I</productname> is able to shift origins to other
-locations.</para>
+<command>sync</command>s have been received everywhere, and that,
+therefore, entries in sl_log_1 and sl_log_2 have been applied
+everywhere, and can therefore be purged.  this extra communication is
+needful so <productname>Slony-I</productname> is able to shift origins
+to other locations.</para>
 
 <sect2><title>how listening can break</title>
 
 <para>On one occasion, I had a need to drop a subscriber node (#2) and
 recreate it.  That node was the data provider for another subscriber
 (#3) that was, in effect, a <quote>cascaded slave.</quote> Dropping
-the subscriber node initially didn't work, as
-<link linkend="slonik"><command>slonik</command></link> informed me that there was a
-dependant node.  I repointed the dependant node to the
+the subscriber node initially didn't work, as <link
+linkend="slonik"><command>slonik</command></link> informed me that
+there was a dependant node.  I repointed the dependant node to the
 <quote>master</quote> node for the subscription set, which, for a
 while, replicated without difficulties.</para>
 
@@ -126,10 +127,11 @@
 <para>When on the <quote>receiver</quote> node, look to the <quote>provider</quote>
 node to provide events coming from the <quote>origin</quote> node.</para>
 
-<para>The tool <filename>init_cluster.pl</filename> in the <filename>altperl</filename>
-scripts produces optimized listener networks in both the tabular form
-shown above as well as in the form of <link linkend="Slonik">
-<application>slonik</application></link> statements.</para>
+<para>The tool <filename>init_cluster.pl</filename> in the
+<filename>altperl</filename> scripts produces optimized listener
+networks in both the tabular form shown above as well as in the form
+of <link linkend="Slonik"> <application>slonik</application></link>
+statements.</para>
 
 <para>There are three <quote>thorns</quote> in this set of roses:
 
@@ -138,28 +140,30 @@
 <listitem><para> If you change the shape of the node set, so that the
 nodes subscribe differently to things, you need to drop sl_listen
 entries and create new ones to indicate the new preferred paths
-between nodes.  Until <productname>Slony-I</productname>, there is no automated way
-at this point to do this <quote>reshaping</quote>.</para></listitem>
-
-<listitem><para> If you <emphasis>don't</emphasis> change the sl_listen entries,
-events will likely continue to propagate so long as all of the nodes
-continue to run well.  the problem will only be noticed when a node is
-taken down, <quote>orphaning</quote> any nodes that are listening through it.</para></listitem>
+between nodes.  Until <productname>Slony-I</productname>, there is no
+automated way at this point to do this
+<quote>reshaping</quote>.</para></listitem>
+
+<listitem><para> If you <emphasis>don't</emphasis> change the
+sl_listen entries, events will likely continue to propagate so long as
+all of the nodes continue to run well.  the problem will only be
+noticed when a node is taken down, <quote>orphaning</quote> any nodes
+that are listening through it.</para></listitem>
 
 <listitem><para> you might have multiple replication sets that have
-<emphasis>different</emphasis> shapes for their respective trees of subscribers.
-there won't be a single <quote>best</quote> listener configuration in that
-case.</para></listitem>
+<emphasis>different</emphasis> shapes for their respective trees of
+subscribers.  there won't be a single <quote>best</quote> listener
+configuration in that case.</para></listitem>
 
 <listitem><para> In order for there to be an sl_listen path, there
-<emphasis>must</emphasis> be a series of sl_path entries connecting the origin
-to the receiver.  this means that if the contents of sl_path do not
-express a <quote>connected</quote> network of nodes, then some nodes will not
-be reachable.  this would typically happen, in practice, when you have
-two sets of nodes, one in one subnet, and another in another subnet,
-where there are only a couple of <quote>firewall</quote> nodes that can talk
-between the subnets.  cut out those nodes and the subnets stop
-communicating.</para></listitem>
+<emphasis>must</emphasis> be a series of sl_path entries connecting
+the origin to the receiver.  this means that if the contents of
+sl_path do not express a <quote>connected</quote> network of nodes,
+then some nodes will not be reachable.  this would typically happen,
+in practice, when you have two sets of nodes, one in one subnet, and
+another in another subnet, where there are only a couple of
+<quote>firewall</quote> nodes that can talk between the subnets.  cut
+out those nodes and the subnets stop communicating.</para></listitem>
 
 </itemizedlist>
 
Index: faq.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/faq.sgml,v
retrieving revision 1.11
retrieving revision 1.12
diff -Ldoc/adminguide/faq.sgml -Ldoc/adminguide/faq.sgml -u -w -r1.11 -r1.12
--- doc/adminguide/faq.sgml
+++ doc/adminguide/faq.sgml
@@ -836,6 +836,56 @@
 <envar>pg_rewrite</envar> <envar>tgrelid</envar> column on the
 affected node.</para></answer>
 </qandaentry>
+<qandaentry>
+<question><para> After notification of a subscription on
+<emphasis>another</emphasis> node, replication falls over, starting
+with the following error message:
+
+<screen>
+ERROR  remoteWorkerThread_1: "begin transaction; set transaction isolation level serializable; lock table "_livesystem".sl_config_lock; select "_livesystem".enableSubscription(25506, 1, 501); notify "_livesystem_Event"; notify "_livesystem_Confirm"; insert into "_livesystem".sl_event     (ev_origin, ev_seqno, ev_timestamp,      ev_minxid, ev_maxxid, ev_xip, ev_type , ev_data1, ev_data2, ev_data3, ev_data4    ) values ('1', '4896546', '2005-01-23 16:08:55.037395', '1745281261', '1745281262', '', 'ENABLE_SUBSCRIPTION', '25506', '1', '501', 't'); insert into "_livesystem".sl_confirm      (con_origin, con_received, con_seqno, con_timestamp)    values (1, 4, '4896546', CURRENT_TIMESTAMP); commit transaction;" PGRES_FATAL_ERROR ERROR:  insert or update on table "sl_subscribe" violates foreign key constraint "sl_subscribe-sl_path-ref"
+DETAIL:  Key (sub_provider,sub_receiver)=(1,501) is not present in table "sl_path".
+</screen>
+
+<para> This is then followed by a series of failed syncs as the
+<application> <link linkend="slon"> slon </link> </application> shuts
+down:
+
+<screen>
+DEBUG2 remoteListenThread_1: queue event 1,4897517 SYNC
+DEBUG2 remoteListenThread_1: queue event 1,4897518 SYNC
+DEBUG2 remoteListenThread_1: queue event 1,4897519 SYNC
+DEBUG2 remoteListenThread_1: queue event 1,4897520 SYNC
+DEBUG2 remoteWorker_event: ignore new events due to shutdown
+DEBUG2 remoteListenThread_1: queue event 1,4897521 SYNC
+DEBUG2 remoteWorker_event: ignore new events due to shutdown
+DEBUG2 remoteListenThread_1: queue event 1,4897522 SYNC
+DEBUG2 remoteWorker_event: ignore new events due to shutdown
+DEBUG2 remoteListenThread_1: queue event 1,4897523 SYNC
+</screen>
+
+</para></question>
+
+<answer><para> If you see a <application> <link linkend="slon"> slon
+</link> </application> shutting down with <emphasis>ignore new events
+due to shutdown</emphasis> log entries, you'll typically have to step
+back to <emphasis>before</emphasis> they started failing to see
+indication of the root cause of the problem.
+
+</para></answer>
+
+<answer><para> In this particular case, the problem was that some of
+the <link linkend="stmtstorepath"> <command>STORE PATH </command>
+</link> commands had not yet made it to node 4 before the <link
+linkend="stmtsubscribeset"> <command>SUBSCRIBE SET </command> </link>
+command propagated. </para>
+
+<para>This is yet another example of the need to not do things too
+terribly quickly; you need to be sure things are working right
+<emphasis>before</emphasis> making further configuration changes.
+</para></answer>
+
+</qandaentry>
+
 
 <qandaentry>