Update of /home/cvsd/slony1/slony1-engine/doc/adminguide
In directory main.slony.info:/tmp/cvs-serv13051

Modified Files:
	addthings.sgml ddlchanges.sgml defineset.sgml faq.sgml 
	firstdb.sgml installation.sgml intro.sgml listenpaths.sgml 
	loganalysis.sgml monitoring.sgml prerequisites.sgml 
	usingslonik.sgml 
Log Message:
Added documentation for problem with PG 8.1.[0-3], linked it into docs,
added various additional index entries.


Index: ddlchanges.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/ddlchanges.sgml,v
retrieving revision 1.29
retrieving revision 1.30
diff -C2 -d -r1.29 -r1.30
*** ddlchanges.sgml	6 Oct 2006 20:19:43 -0000	1.29
--- ddlchanges.sgml	11 Jun 2007 16:02:50 -0000	1.30
***************
*** 263,266 ****
--- 263,268 ----
  <sect2><title> Testing DDL Changes </title>
  
+ <indexterm><primary> testing DDL changes </primary></indexterm>
+ 
  <para> A method for testing DDL changes has been pointed out as a
  likely <quote>best practice.</quote></para>

Index: defineset.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/defineset.sgml,v
retrieving revision 1.27
retrieving revision 1.28
diff -C2 -d -r1.27 -r1.28
*** defineset.sgml	18 Apr 2007 15:03:51 -0000	1.27
--- defineset.sgml	11 Jun 2007 16:02:50 -0000	1.28
***************
*** 95,98 ****
--- 95,100 ----
  <sect2 id="definesets"><title>Grouping tables into sets</title>
  
+ <indexterm><primary> grouping tables into replication sets </primary></indexterm>
+ 
  <para> It will be vital to group tables together into a single set if
  those tables are related via foreign key constraints.  If tables that

Index: prerequisites.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/prerequisites.sgml,v
retrieving revision 1.27
retrieving revision 1.28
diff -C2 -d -r1.27 -r1.28
*** prerequisites.sgml	5 Dec 2006 20:39:34 -0000	1.27
--- prerequisites.sgml	11 Jun 2007 16:02:50 -0000	1.28
***************
*** 1,7 ****
  <!-- $Id -->
  <sect1 id="requirements">
! <title>System Requirements</title> <para>Any platform that can run
! &postgres; should be able to run
! &slony1;.</para>
  
  <para>The platforms that have received specific testing at the time of
--- 1,10 ----
  <!-- $Id -->
  <sect1 id="requirements">
! <title>System Requirements</title> 
! 
! <para>Any platform that can run &postgres; should be able, in
! principle, to run &slony1;.</para>
! 
! <indexterm><primary> platforms where &slony1; runs </primary> </indexterm>
  
  <para>The platforms that have received specific testing at the time of
***************
*** 15,18 ****
--- 18,23 ----
  <title> &slony1; Software Dependancies</title>
  
+ <indexterm><primary> software dependancies </primary> </indexterm>
+ 
  <para> At present, &slony1; <emphasis>as well as &postgres;</emphasis>
  need to be able to be compiled from source at your site.</para>
***************
*** 56,59 ****
--- 61,70 ----
  </para>
  
+ <para> If you are running versions 8.1.0 thru 8.1.3, there is a bug
+ (addressed in 8.1.4) which prevents <xref
+ linkend="stmtupdatefunctions"> from running properly.  For more
+ details see the <xref linkend="FAQ">, <link
+ linkend="pg81funs"> on &postgres; 8.1.[0-3] </link>. </para>
+ 
  </listitem>
  
***************
*** 103,109 ****
  <title> Getting &slony1; Source</title>
  
  <para>You can get the &slony1; source from <ulink
!     url="http://developer.postgresql.org/~wieck/slony1/download/">
! http://developer.postgresql.org/~wieck/slony1/download/</ulink>
  </para>
  
--- 114,122 ----
  <title> Getting &slony1; Source</title>
  
+ <indexterm><primary>downloading &slony1; sources</primary></indexterm>
+ 
  <para>You can get the &slony1; source from <ulink
!     url="http://main.slony.info/downloads/">
! http://main.slony.info/downloads/</ulink>
  </para>
  
***************
*** 113,116 ****
--- 126,131 ----
  <title> Database Encoding </title>
  
+ <indexterm><primary> database encodings</primary></indexterm>
+ 
  <para> &postgres; databases may be created in a number of language
  encodings, set up via the <command>createdb --encoding=$ENCODING
***************
*** 147,150 ****
--- 162,167 ----
  <title> Time Synchronization</title>
  
+ <indexterm><primary> time synchronization</primary></indexterm>
+ 
  <para> All the servers used within the replication cluster need to
  have their Real Time Clocks in sync. This is to ensure that <xref
***************
*** 199,202 ****
--- 216,221 ----
  <sect2><title> Network Connectivity</title>
  
+ <indexterm><primary> network connectivity</primary></indexterm>
+ 
  <para>It is necessary that the hosts that are to replicate between one
  another have <emphasis>bidirectional</emphasis> network communications

Index: intro.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/intro.sgml,v
retrieving revision 1.27
retrieving revision 1.28
diff -C2 -d -r1.27 -r1.28
*** intro.sgml	1 Dec 2006 23:15:43 -0000	1.27
--- intro.sgml	11 Jun 2007 16:02:50 -0000	1.28
***************
*** 3,6 ****
--- 3,8 ----
  <title>Introduction to &slony1;</title>
  
+ <indexterm><primary> introduction to &slony1; </primary></indexterm>
+ 
  <sect2> <title>What &slony1; is</title>
  

Index: monitoring.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/monitoring.sgml,v
retrieving revision 1.36
retrieving revision 1.37
diff -C2 -d -r1.36 -r1.37
*** monitoring.sgml	9 May 2007 19:20:03 -0000	1.36
--- monitoring.sgml	11 Jun 2007 16:02:50 -0000	1.37
***************
*** 168,171 ****
--- 168,173 ----
  <sect2 id="search-logs"> <title> <command>search-logs.sh</command> </title>
  
+ <indexterm><primary> search &slony1; logs using search-logs.sh </primary></indexterm>
+ 
  <para> This script is constructed to search for &slony1; log files at
  a given path (<envar>LOGHOME</envar>), based both on the naming
***************
*** 187,190 ****
--- 189,194 ----
  <sect2 id="wikigen"> <title> Building MediaWiki Cluster Summary </title>
  
+ <indexterm><primary> generating Wiki documentation of a cluster </primary></indexterm>
+ 
  <para> The script <filename>mkmediawiki.pl </filename>, in
  <filename>tools</filename>, may be used to generate a cluster summary

Index: firstdb.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/firstdb.sgml,v
retrieving revision 1.23
retrieving revision 1.24
diff -C2 -d -r1.23 -r1.24
*** firstdb.sgml	13 Mar 2007 16:06:28 -0000	1.23
--- firstdb.sgml	11 Jun 2007 16:02:50 -0000	1.24
***************
*** 144,147 ****
--- 144,149 ----
  <sect3><title>Using the altperl scripts</title>
  
+ <indexterm><primary> altperl script usage </primary></indexterm>
+ 
  <para>
  Using the <xref linkend="altperl"> scripts is an easy way to get started.  The
***************
*** 174,180 ****
  
  <sect3><title>Using slonik command directly</title>
- <para>The traditional approach to administering slony is to craft slonik
- commands directly. An example of this given here. </para>
  
  
  <para> The script to create
--- 176,182 ----
  
  <sect3><title>Using slonik command directly</title>
  
+ <para>The traditional approach to administering slony is to craft
+ slonik commands directly. An example of this given here. </para>
  
  <para> The script to create

Index: usingslonik.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/usingslonik.sgml,v
retrieving revision 1.18
retrieving revision 1.19
diff -C2 -d -r1.18 -r1.19
*** usingslonik.sgml	2 Aug 2006 18:34:59 -0000	1.18
--- usingslonik.sgml	11 Jun 2007 16:02:50 -0000	1.19
***************
*** 93,96 ****
--- 93,98 ----
  <sect1 id="slonikshell"><title> Embedding Slonik in Shell Scripts </title>
  
+ <indexterm><primary> embedding slonik in shell scripts </primary></indexterm>
+ 
  <para> As mentioned earlier, there are numerous &slony1; test scripts
  in <filename>src/ducttape</filename> that embed the generation of
***************
*** 277,280 ****
--- 279,284 ----
  Functions </title>
  
+ <indexterm><primary> bare metal &slony1; functions </primary></indexterm>
+ 
  <para> There are cases where it may make sense to directly use the
  stored functions that implement the various pieces of &slony1;.

Index: listenpaths.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/listenpaths.sgml,v
retrieving revision 1.19
retrieving revision 1.20
diff -C2 -d -r1.19 -r1.20
*** listenpaths.sgml	2 Aug 2006 18:34:58 -0000	1.19
--- listenpaths.sgml	11 Jun 2007 16:02:50 -0000	1.20
***************
*** 4,12 ****
  <indexterm><primary>listen paths</primary></indexterm>
  
! <note><para> If you are running version
! &slony1; 1.1 or later it should be
! <emphasis>completely unnecessary</emphasis> to read this section as it
! introduces a way to automatically manage this part of its
! configuration.  For earlier versions, however, it is needful.</para>
  </note>
  
--- 4,12 ----
  <indexterm><primary>listen paths</primary></indexterm>
  
! <note><para> If you are running version &slony1; 1.2 or later it
! should be <emphasis>completely unnecessary</emphasis> to read this
! section as it introduces a way to automatically manage this part of
! its configuration.  For earlier versions, however, it is
! needful.</para>
  </note>
  
***************
*** 34,37 ****
--- 34,39 ----
  <sect2><title>How listening can break</title>
  
+ <indexterm><primary> listening breakage </primary></indexterm>
+ 
  <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
***************
*** 175,178 ****
--- 177,182 ----
  <sect2 id="autolisten"><title>Automated Listen Path Generation</title>
  
+ <indexterm><primary> automated listen path generation </primary></indexterm>
+ 
  <para> In &slony1; version 1.1, a heuristic scheme is introduced to
  automatically generate <envar>sl_listen</envar> entries.  This

Index: faq.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/faq.sgml,v
retrieving revision 1.70
retrieving revision 1.71
diff -C2 -d -r1.70 -r1.71
*** faq.sgml	18 Apr 2007 15:03:51 -0000	1.70
--- faq.sgml	11 Jun 2007 16:02:50 -0000	1.71
***************
*** 162,165 ****
--- 162,235 ----
  </qandaentry>
  
+ <qandaentry id="pg81funs">
+ 
+ <question> <para> I'm trying to upgrade to a newer version of &slony1;
+ and am running into a problem with <xref
+ linkend="stmtupdatefunctions">.  When I run <xref
+ linkend="stmtupdatefunctions">, my
+ <application>postmaster</application> falls over with a Signal 11.
+ There aren't any seeming errors in the log files, aside from the
+ &postgres; logs indicating that, yes indeed, the postmaster fell
+ over.</para>
+ 
+ <para> I connected a debugger to the core file, and it indicates that
+ it was trying to commit a transaction at the time of the
+ failure. </para>
+ 
+ <para> By the way I'm on &postgres; 8.1.[0-3]. </para>
+ </question>
+ 
+ <answer> <para> Unfortunately, early releases of &postgres; 8.1 had a
+ problem where if you redefined a function (such as, say,
+ <function>upgradeSchema(text)</function>), and then, in the same
+ transaction, ran that function, the
+ <application>postmaster</application> would fall over, and the
+ transaction would fail to commit.  </para>
+ 
+ <para> The &lslonik; command <xref linkend="stmtupdatefunctions">
+ functions like that; it, in one transaction, tries to:
+ 
+ <itemizedlist>
+ <listitem><para> Load the new functions (from <filename>slony1_funcs.sql</filename>), notably including <function>upgradeSchema(text)</function>.  </para> </listitem>
+ <listitem><para> Run <function>upgradeSchema(text)</function> to do any necessary upgrades to the database schema. </para> </listitem>
+ <listitem><para> Notify &lslon; processes of a change of configuration.</para> </listitem>
+ </itemizedlist>
+ </para>
+ 
+ <para> Unfortunately, on &postgres; 8.1.0, 8.1.1, 8.1.2, and 8.1.3,
+ this conflicts with a bug where using and modifying a plpgsql function
+ in the same transaction leads to a crash. </para>
+ 
+ <para> Several workarounds are available. </para>
+ 
+ </answer>
+ 
+ <answer> <para> The preferred answer would be to upgrade &postgres; to
+ 8.1.4 or some later version.  Changes between minor versions do not
+ require rebuilding databases; it should merely require copying a
+ suitable 8.1.x build into place, and restarting the
+ <application>postmaster</application> with the new version.  </para>
+ </answer>
+ 
+ <answer><para> If that is unsuitable, it would be possible to perform
+ the upgrade via a series of transactions, performing the equivalent of
+ what &lslonik; does <quote>by hand</quote>: </para>
+ 
+ <itemizedlist>
+ <listitem><para> Take <filename>slony1_funcs.sql</filename> and do three replacements within it: </para> 
+ 
+ <itemizedlist>
+ <listitem><para> Replace <quote>@CLUSTERNAME@</quote> with the name of the cluster </para> </listitem>
+ <listitem><para> Replace <quote>@MODULEVERSION@</quote> with the &slony1; version string, such as <quote>1.2.10</quote> </para> </listitem>
+ <listitem><para> Replace <quote>@NAMESPACE@</quote> with the <quote>double-quoted</quote> name of the cluster namespace, such as "_MyCluster" </para> </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem><para> Load that <quote>remapped</quote> set of functions into the database.</para> </listitem>
+ <listitem><para> Run the stored function via <command>select <function>upgradeSchema('1.2.7')</function>; </command>, assuming that the previous version of &slony1; in use was version 1.2.7. </para> </listitem>
+ <listitem><para> Restarting all &lslon; processes would probably be a wise move with this sort of <quote>surgery.</quote> </para> </listitem>
+ </itemizedlist>
+ </answer>
+ </qandaentry>
+ 
  </qandadiv>
  

Index: installation.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/installation.sgml,v
retrieving revision 1.31
retrieving revision 1.32
diff -C2 -d -r1.31 -r1.32
*** installation.sgml	4 Dec 2006 07:12:49 -0000	1.31
--- installation.sgml	11 Jun 2007 16:02:50 -0000	1.32
***************
*** 40,43 ****
--- 40,45 ----
  <title>Short Version</title>
  
+ <indexterm><primary> installation: short version </primary></indexterm>
+ 
  <para>
  <screen>
***************
*** 189,192 ****
--- 191,197 ----
  </itemizedlist>
  
+ <para> (Note that as things change, the list of version-specific files
+ may grow...) </para>
+ 
  <para>The <filename>.sql</filename> files are not fully substituted
  yet.  And yes, both the 7.3, 7.4 and the 8.0 files get installed on every
***************
*** 206,209 ****
--- 211,216 ----
  <sect2> <title> Building Documentation: Admin Guide </title>
  
+ <indexterm><primary> building &slony1; documentation </primary></indexterm>
+ 
  <para> The document you are reading now is a fairly extensive
  <quote>Administrator's Guide</quote> containing what wisdom has been

Index: loganalysis.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/loganalysis.sgml,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -d -r1.8 -r1.9
*** loganalysis.sgml	16 Feb 2007 23:35:13 -0000	1.8
--- loganalysis.sgml	11 Jun 2007 16:02:50 -0000	1.9
***************
*** 695,699 ****
  <listitem><para><command>ERROR: remoteWorkerThread_%d: SYNC aborted</command></para> 
  
! <para> If any errors have been encountered that haven't already aborted the <command>SYNC</command>, this catches and aborts it.</para></listitem>
  
  <listitem><para><command>DEBUG2: remoteWorkerThread_%d: new sl_rowid_seq value: %s</command></para> 
--- 695,707 ----
  <listitem><para><command>ERROR: remoteWorkerThread_%d: SYNC aborted</command></para> 
  
! <para>The <command>SYNC</command> has been aborted. The &lslon; will
! likely retry this <command>SYNC</command> some time soon.  If the
! <command>SYNC</command> continues to fail, there is some continuing
! problem, and replication will likely never catch up without
! intervention.  It may be necessary to unsubscribe/resubscribe the
! affected slave set, or, if there is only one set on the slave node, it
! may be simpler to drop and recreate the slave node.  If application
! connections may be shifted over to the master during this time,
! application downtime may not be necessary.  </para></listitem>
  
  <listitem><para><command>DEBUG2: remoteWorkerThread_%d: new sl_rowid_seq value: %s</command></para> 

Index: addthings.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/addthings.sgml,v
retrieving revision 1.28
retrieving revision 1.29
diff -C2 -d -r1.28 -r1.29
*** addthings.sgml	18 Apr 2007 15:03:51 -0000	1.28
--- addthings.sgml	11 Jun 2007 16:02:50 -0000	1.29
***************
*** 61,64 ****
--- 61,66 ----
  <sect2><title> Adding a table to replication </title>
  
+ <indexterm><primary> adding a table to replication </primary></indexterm>
+ 
  <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
***************
*** 120,123 ****
--- 122,127 ----
  <sect2><title> How to add columns to a replicated table </title>
  
+ <indexterm><primary> adding columns to a replicated table </primary></indexterm>
+ 
  <para> This also answers the question <quote>How do I rename columns
  on a replicated table?</quote>, and, more generally, other questions