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

Modified Files:
	adminscripts.sgml failover.sgml faq.sgml firstdb.sgml 
	installation.sgml monitoring.sgml prerequisites.sgml 
	slonconf.sgml slonik_ref.sgml 
Log Message:
Pull in changes from 2.0


Index: prerequisites.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/prerequisites.sgml,v
retrieving revision 1.28
retrieving revision 1.29
diff -C2 -d -r1.28 -r1.29
*** prerequisites.sgml	11 Jun 2007 16:02:50 -0000	1.28
--- prerequisites.sgml	30 Apr 2009 16:07:47 -0000	1.29
***************
*** 8,17 ****
  <indexterm><primary> platforms where &slony1; runs </primary> </indexterm>
  
! <para>The platforms that have received specific testing at the time of
! this release are FreeBSD-4X-i368, FreeBSD-5X-i386, FreeBSD-5X-alpha,
! OS-X-10.3, Linux-2.4X-i386 Linux-2.6X-i386 Linux-2.6X-amd64,
  <trademark>Solaris</trademark>-2.8-SPARC,
! <trademark>Solaris</trademark>-2.9-SPARC, AIX 5.1, OpenBSD-3.5-sparc64
! and &windows; 2000, XP and 2003 (32 bit).</para>
  
  <sect2>
--- 8,19 ----
  <indexterm><primary> platforms where &slony1; runs </primary> </indexterm>
  
! <para>The platforms that have received specific testing are
! FreeBSD-4X-i368, FreeBSD-5X-i386, FreeBSD-5X-alpha, OS-X-10.3,
! Linux-2.4X-i386 Linux-2.6X-i386 Linux-2.6X-amd64,
  <trademark>Solaris</trademark>-2.8-SPARC,
! <trademark>Solaris</trademark>-2.9-SPARC, AIX 5.1 and 5.3,
! OpenBSD-3.5-sparc64 and &windows; 2000, XP and 2003 (32 bit).  There
! is enough diversity amongst these platforms that nothing ought to
! prevent running &slony1; on other similar platforms. </para>
  
  <sect2>
***************
*** 67,70 ****
--- 69,76 ----
  linkend="pg81funs"> on &postgres; 8.1.[0-3] </link>. </para>
  
+ <para> There is variation between what versions of &postgres& are
+ compatible with what versions of &slony1;.  See <xref
+ linkend="installation"> for more details.</para>
+ 
  </listitem>
  
***************
*** 103,107 ****
  installation.</para>
  
! <note><para>In &slony1; version 1.1, it is possible to compile
  &slony1; separately from &postgres;, making it practical for the
  makers of distributions of <productname>Linux</productname> and
--- 109,113 ----
  installation.</para>
  
! <note><para>From &slony1; version 1.1, it is possible to compile
  &slony1; separately from &postgres;, making it practical for the
  makers of distributions of <productname>Linux</productname> and


Index: faq.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/faq.sgml,v
retrieving revision 1.81
retrieving revision 1.82
diff -C2 -d -r1.81 -r1.82
*** faq.sgml	19 Feb 2009 16:47:18 -0000	1.81
--- faq.sgml	30 Apr 2009 16:07:47 -0000	1.82
***************
*** 1846,1849 ****
--- 1846,1887 ----
  linkend="stmtsetdropsequence">.</para></answer></qandaentry>
  
+ <qandaentry>
+ <question><para> I set up my cluster using pgAdminIII, with cluster
+ name <quote>MY-CLUSTER</quote>.  Time has passed, and I tried using
+ Slonik to make a configuration change, and this is failing with the
+ following error message:</para>
+ 
+ <programlisting>
+ ERROR: syntax error at or near -
+ </programlisting>
+ </question>
+ 
+ <answer><para> The problem here is that &slony1; expects cluster names
+ to be valid <ulink url=
+ "http://www.postgresql.org/docs/8.3/static/sql-syntax-lexical.html">
+ SQL Identifiers</ulink>, and &lslonik; enforces this.  Unfortunately,
+ <application>pgAdminIII</application> did not do so, and allowed using
+ a cluster name that now causes <emphasis>a problem.</emphasis> </para> </answer>
+ 
+ <answer> <para> If you have gotten into this spot, it's a problem that
+ we mayn't be help resolve, terribly much.  </para>
+ 
+ <para> It's <emphasis>conceivably possible</emphasis> that running the
+ SQL command <command>alter namespace "_My-Bad-Clustername" rename to
+ "_BetterClusterName";</command> against each database may work.  That
+ shouldn't particularly <emphasis>damage</emphasis> things!</para>
+ 
+ <para> On the other hand, when the problem has been experienced, users
+ have found they needed to drop replication and rebuild the
+ cluster.</para> </answer>
+ 
+ <answer><para> A change in version 2.0.2 is that a function runs as
+ part of loading functions into the database which checks the validity
+ of the cluster name.  If you try to use an invalid cluster name,
+ loading the functions will fail, with a suitable error message, which
+ should prevent things from going wrong even if you're using tools
+ other than &lslonik; to manage setting up the cluster. </para></answer>
+ </qandaentry>
+ 
  </qandadiv>
  
***************
*** 2444,2452 ****
  </question> 
  
  <para> &slony1; uses sequences to provide primary key values for log
  entries, and therefore this kind of behaviour may (perhaps
  regrettably!) be expected.  </para>
  
! <answer> <para> Calling <function>lastval()</function>, to
  <quote>anonymously</quote> get <quote>the most recently updated
  sequence value</quote>, rather than using
--- 2482,2491 ----
  </question> 
  
+ <answer>
  <para> &slony1; uses sequences to provide primary key values for log
  entries, and therefore this kind of behaviour may (perhaps
  regrettably!) be expected.  </para>
  
! <para> Calling <function>lastval()</function>, to
  <quote>anonymously</quote> get <quote>the most recently updated
  sequence value</quote>, rather than using

Index: installation.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/installation.sgml,v
retrieving revision 1.36
retrieving revision 1.37
diff -C2 -d -r1.36 -r1.37
*** installation.sgml	28 Jan 2009 22:08:22 -0000	1.36
--- installation.sgml	30 Apr 2009 16:07:47 -0000	1.37
***************
*** 44,48 ****
  <para>
  <screen>
! PGMAIN=/usr/local/pgsql746-freebsd-2005-04-01 \
  ./configure \
      --with-pgconfigdir=$PGMAIN/bin
--- 44,48 ----
  <para>
  <screen>
! PGMAIN=/usr/local/pgsql839-freebsd-2008-09-03 \
  ./configure \
      --with-pgconfigdir=$PGMAIN/bin
***************
*** 69,74 ****
  <application>configure</application> needed to know where your
  &postgres; source tree is, which was done with the
! <option>--with-pgsourcetree=</option> option.  As of version 1.1, this
! is no longer necessary, as &slony1; has included within its own code
  base certain parts needed for platform portability.  It now only needs
  to make reference to parts of &postgres; that are actually part of the
--- 69,74 ----
  <application>configure</application> needed to know where your
  &postgres; source tree is, which was done with the
! <option>--with-pgsourcetree=</option> option.  Since version 1.1, this
! has not been necessary, as &slony1; has included within its own code
  base certain parts needed for platform portability.  It now only needs
  to make reference to parts of &postgres; that are actually part of the
***************
*** 93,99 ****
  to provide correct client libraries. </para>
  
! <para> &postgres; version 8 installs the server header
  <command>#include</command> files by default; with version 7.4 and
! earlier, you need to make sure that the build installation included
  doing <command>make install-all-headers</command>, otherwise the
  server headers will not be installed, and &slony1; will be unable to
--- 93,99 ----
  to provide correct client libraries. </para>
  
! <para> &postgres; versions from 8.0 onwards install the server header
  <command>#include</command> files by default; with version 7.4 and
! earlier, you needed to make sure that the build installation included
  doing <command>make install-all-headers</command>, otherwise the
  server headers will not be installed, and &slony1; will be unable to
***************
*** 124,128 ****
  try to detect some quirks of your system.  &slony1; is known to need a
  modified version of <application>libpq</application> on specific
! platforms such as Solaris2.X on SPARC.  The patch for libpq version
  7.4.2 can be found at <ulink id="threadpatch" url=
  "http://developer.postgresql.org/~wieck/slony1/download/threadsafe-libpq-742.diff.gz">
--- 124,128 ----
  try to detect some quirks of your system.  &slony1; is known to need a
  modified version of <application>libpq</application> on specific
! platforms such as Solaris2.X on SPARC.  A patch for libpq version
  7.4.2 can be found at <ulink id="threadpatch" url=
  "http://developer.postgresql.org/~wieck/slony1/download/threadsafe-libpq-742.diff.gz">
***************
*** 196,205 ****
  
  <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
! system, irrespective of its version.  The <xref linkend="slonik">
! admin utility does namespace/cluster substitutions within these files,
! and loads the files when creating replication nodes.  At that point in
! time, the database being initialized may be remote and may run a
! different version of &postgres; than that of the local host.</para>
  
  <para> At the very least, the two shared objects installed in the
--- 196,207 ----
  
  <para>The <filename>.sql</filename> files are not fully substituted
! yet.  And yes, versions for all supported versions of &postgres;
! (<emphasis>e.g.</emphasis> - such as 7.3, 7.4 8.0) get installed on
! every system, irrespective of its version.  The <xref
! linkend="slonik"> admin utility does namespace/cluster substitutions
! within these files, and loads the files when creating replication
! nodes.  At that point in time, the database being initialized may be
! remote and may run a different version of &postgres; than that of the
! local host.</para>
  
  <para> At the very least, the two shared objects installed in the

Index: slonik_ref.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/slonik_ref.sgml,v
retrieving revision 1.95
retrieving revision 1.96
diff -C2 -d -r1.95 -r1.96
*** slonik_ref.sgml	14 Apr 2009 09:31:28 -0000	1.95
--- slonik_ref.sgml	30 Apr 2009 16:07:47 -0000	1.96
***************
*** 84,87 ****
--- 84,104 ----
       <para> Those commands are grouped together into one transaction
        per participating node. </para>
+ 
+      <para> Note that this does not enforce grouping of the actions as
+      a single transaction on all nodes.  For instance, consider the
+      following slonik code:</para>
+      <programlisting>
+      try {
+          execute script (set id = 1, filename = '/tmp/script1.sql', event node=1);
+          execute script (set id = 1, filename = '/tmp/script2.sql', event node=1);
+      }
+      </programlisting>
+ 
+      <para> This <emphasis>would</emphasis> be processed within a
+      single BEGIN/COMMIT on node 1.  However, the requests are
+      separated into two <command>DDL_SCRIPT</command> events so that
+      each will be run individually, in separate transactions, on other
+      nodes in the cluster. </para>
+ 
  <!-- ************************************************************ --></sect3></sect2></sect1></article>
  
***************
*** 98,102 ****
    </partintro>
    <!-- **************************************** -->
!   <refentry id ="stmtinclude"><refmeta><refentrytitle>INCLUDE</refentrytitle>
     <manvolnum>7</manvolnum></refmeta>
    
--- 115,119 ----
    </partintro>
    <!-- **************************************** -->
!   <refentry id ="stmtinclude"><refmeta><refentrytitle>SLONIK INCLUDE</refentrytitle>
     <manvolnum>7</manvolnum></refmeta>
    
***************
*** 135,139 ****
    </refentry>
    <!-- **************************************** -->
!   <refentry id ="stmtdefine"><refmeta><refentrytitle>DEFINE</refentrytitle>
     <manvolnum>7</manvolnum></refmeta>
     
--- 152,156 ----
    </refentry>
    <!-- **************************************** -->
!   <refentry id ="stmtdefine"><refmeta><refentrytitle>SLONIK DEFINE</refentrytitle>
     <manvolnum>7</manvolnum></refmeta>
     
***************
*** 213,217 ****
    <!-- **************************************** -->
    
!   <refentry id ="clustername"><refmeta><refentrytitle>CLUSTER NAME</refentrytitle>
     <manvolnum>7</manvolnum></refmeta>
     
--- 230,234 ----
    <!-- **************************************** -->
    
!   <refentry id ="clustername"><refmeta><refentrytitle>SLONIK CLUSTER NAME</refentrytitle>
     <manvolnum>7</manvolnum></refmeta>
     
***************
*** 262,266 ****
  <!-- **************************************** -->
  
!   <refentry id ="admconninfo"><refmeta><refentrytitle>ADMIN CONNINFO</refentrytitle>
     <manvolnum>7</manvolnum></refmeta>
     
--- 279,283 ----
  <!-- **************************************** -->
  
!   <refentry id ="admconninfo"><refmeta><refentrytitle>SLONIK ADMIN CONNINFO</refentrytitle>
     <manvolnum>7</manvolnum></refmeta>
     
***************
*** 338,342 ****
  <!-- **************************************** -->
    
!   <refentry id ="stmtecho"><refmeta><refentrytitle>ECHO</refentrytitle>
     <manvolnum>7</manvolnum></refmeta>
     
--- 355,359 ----
  <!-- **************************************** -->
    
!   <refentry id ="stmtecho"><refmeta><refentrytitle>SLONIK ECHO</refentrytitle>
     <manvolnum>7</manvolnum></refmeta>
     
***************
*** 552,556 ****
     <Refsect1><Title>Example</Title>
      <Programlisting>
!      STORE NODE ( ID = 2, COMMENT = 'Node 2');
      </Programlisting>
     </Refsect1>
--- 569,573 ----
     <Refsect1><Title>Example</Title>
      <Programlisting>
!      STORE NODE ( ID = 2, COMMENT = 'Node 2', EVENT NODE = 1 );
      </Programlisting>
     </Refsect1>
***************
*** 613,617 ****
     <refsect1><title>Example</title>
      <programlisting>
!      DROP NODE ( ID = 2 );
      </programlisting>
     </refsect1>
--- 630,634 ----
     <refsect1><title>Example</title>
      <programlisting>
!      DROP NODE ( ID = 2, EVENT NODE = 1 );
      </programlisting>
     </refsect1>
***************
*** 3058,3062 ****
  
  
!   <refentry id ="stmtcloneprepare"><refmeta><refentrytitle>CLONE PREPARE</refentrytitle>
     <manvolnum>7</manvolnum></refmeta>
     
--- 3075,3079 ----
  
  
!   <refentry id ="stmtcloneprepare"><refmeta><refentrytitle>SLONIK CLONE PREPARE</refentrytitle>
     <manvolnum>7</manvolnum></refmeta>
     
***************
*** 3106,3110 ****
  
  
!   <refentry id ="stmtclonefinish"><refmeta><refentrytitle>CLONE FINISH</refentrytitle>
     <manvolnum>7</manvolnum></refmeta>
     
--- 3123,3127 ----
  
  
!   <refentry id ="stmtclonefinish"><refmeta><refentrytitle>SLONIK CLONE FINISH</refentrytitle>
     <manvolnum>7</manvolnum></refmeta>
     


Index: slonconf.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/slonconf.sgml,v
retrieving revision 1.21
retrieving revision 1.22
diff -C2 -d -r1.21 -r1.22
*** slonconf.sgml	31 Mar 2008 16:28:24 -0000	1.21
--- slonconf.sgml	30 Apr 2009 16:07:47 -0000	1.22
***************
*** 123,132 ****
            appear in each log line entry.
          </para>
        </listitem>
      </varlistentry>
  
- 
- 
- 
      <varlistentry id="slon-config-logging-log-timestamp-format" xreflabel="slon_conf_log_timestamp_format">
        <term><varname>log_timestamp_format</varname> (<type>string</type>)</term>
--- 123,135 ----
            appear in each log line entry.
          </para>
+ 
+         <para> Note that if <envar>syslog</envar> usage is configured,
+         then this is ignored; it is assumed that
+         <application>syslog</application> will be supplying
+         timestamps, and timestamps are therefore suppressed.
+         </para>
        </listitem>
      </varlistentry>
  
      <varlistentry id="slon-config-logging-log-timestamp-format" xreflabel="slon_conf_log_timestamp_format">
        <term><varname>log_timestamp_format</varname> (<type>string</type>)</term>


Index: failover.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/failover.sgml,v
retrieving revision 1.30
retrieving revision 1.31
diff -C2 -d -r1.30 -r1.31
*** failover.sgml	3 Apr 2009 20:55:12 -0000	1.30
--- failover.sgml	30 Apr 2009 16:07:47 -0000	1.31
***************
*** 48,52 ****
  server requires the application to reconnect to the new database.  So
  in order to avoid any complications, we simply shut down the web
! server.  Users who use <application>pgpool</application> for the
  applications database connections merely have to shut down the
  pool.</para>
--- 48,52 ----
  server requires the application to reconnect to the new database.  So
  in order to avoid any complications, we simply shut down the web
! server.  Users who use <application>pg_pool</application> for the
  applications database connections merely have to shut down the
  pool.</para>
***************
*** 80,84 ****
  </para> </listitem>
  
! <listitem><para> If you are using <application>pgpool</application> or some
  similar <quote>connection pool manager,</quote> then the reconfiguration
  involves reconfiguring this management tool, but is otherwise similar
--- 80,84 ----
  </para> </listitem>
  
! <listitem><para> If you are using <application>pg_pool</application> or some
  similar <quote>connection pool manager,</quote> then the reconfiguration
  involves reconfiguring this management tool, but is otherwise similar