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

Modified Files:
      Tag: REL_2_0_STABLE
	adminscripts.sgml intro.sgml slonik_ref.sgml slonyupgrade.sgml 
Log Message:
Add in OMIT COPY option to SUBSCRIBE SET in support of upgrading from
elder Slony-I versions.


Index: slonyupgrade.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/slonyupgrade.sgml,v
retrieving revision 1.10
retrieving revision 1.10.2.1
diff -C2 -d -r1.10 -r1.10.2.1
*** slonyupgrade.sgml	15 Oct 2008 21:51:54 -0000	1.10
--- slonyupgrade.sgml	17 Jun 2009 21:37:38 -0000	1.10.2.1
***************
*** 254,257 ****
--- 254,364 ----
  
  </sect2>
+ 
+ <sect2 id="upgrade20"> <title> Upgrading to &slony1; version 2 </title>
+ 
+ <para> The version 2 branch is <emphasis>substantially</emphasis>
+ different from earlier releases, dropping support for versions of
+ &postgres; prior to 8.3, as in version 8.3, support for a
+ <quote>session replication role</quote> was added, thereby eliminating
+ the need for system catalog hacks as well as the
+ not-entirely-well-supported <envar>xxid</envar> data type. </para>
+ 
+ <para> As a result of the replacement of the <envar>xxid</envar> type
+ with a (native-to-8.3) &postgres; transaction XID type, the &lslonik;
+ command <xref linkend="stmtupdatefunctions"> is quite inadequate to
+ the process of upgrading earlier versions of &slony1; to version
+ 2.</para>
+ 
+ <para> In version 2.0.2, we have added a new option to <xref
+ linkend="stmtsubscribeset">, <command>OMIT COPY</command>, which
+ allows taking an alternative approach to upgrade which amounts to:</para>
+ 
+ <itemizedlist>
+ <listitem><para> Uninstall old version of &slony1; </para>
+ <para> When &slony1; uninstalls itself, catalog corruptions are fixed back up.</para> </listitem>
+ <listitem><para> Install &slony1; version 2 </para></listitem>
+ <listitem><para> Resubscribe, with <command>OMIT COPY</command></para></listitem>
+ </itemizedlist>
+ 
+ <warning><para> There is a large <quote>foot gun</quote> here: during
+ part of the process, &slony1; is not installed in any form, and if an
+ application updates one or another of the databases, the
+ resubscription, omitting copying data, will be left with data
+ <emphasis>out of sync.</emphasis> </para>
+ 
+ <para> The administrator <emphasis>must take care</emphasis>; &slony1;
+ has no way to help ensure the integrity of the data during this
+ process.</para>
+ </warning>
+ 
+ <para> The following process is suggested to help make the upgrade
+ process as safe as possible, given the above risks. </para>
+ 
+ <itemizedlist>
+ 
+ <listitem><para> Use <xref linkend="slonikconfdump"> to generate a
+ &lslonik; script to recreate the replication cluster.  </para>
+ 
+ <para> Be sure to verify the <xref linkend="admconninfo"> statements,
+ as the values are pulled are drawn from the PATH configuration, which
+ may not necessarily be suitable for running &lslonik;. </para>
+ 
+ <para> This step may be done before the application outage. </para>
+ </listitem>
+ 
+ <listitem><para> Determine what triggers have <xref
+ linkend="stmtstoretrigger"> configuration on subscriber nodes.
+ </para>
+ 
+ <para> As discussed in <xref linkend="triggers">, the handling has
+ fundamentally changed between &slony1; 1.2 and 2.0. </para>
+ 
+ <para> Generally speaking, what needs to happen is to query
+ <envar>sl_table</envar> on each node, and, for any triggers found in
+ <envar>sl_table</envar>, it is likely to be appropriate to set up a
+ script indicating either <command>ENABLE REPLICA TRIGGER</command> or
+ <command>ENABLE ALWAYS TRIGGER</command> for these triggers.</para>
+ 
+ <para> This step may be done before the application outage. </para>
+ </listitem>
+ 
+ <listitem><para> Begin an application outage during which updates should no longer be applied to the database. </para> </listitem>
+ 
+ <listitem><para> To ensure that applications cease to make changes, it would be appropriate to lock them out via modifications to <filename>pg_hba.conf</filename> </para> </listitem>
+ 
+ <listitem><para> Ensure replication is entirely caught up, via examination of the <envar>sl_status</envar> view, and any application data that may seem appropriate. </para> </listitem>
+ 
+ <listitem><para> Shut down &lslon; processes. </para> </listitem>
+ 
+ <listitem><para> Uninstall the old version of &slony1; from the database. </para> 
+ 
+ <para> This involves running a &lslonik; script that runs <xref
+ linkend="stmtuninstallnode"> against each node in the cluster. </para>
+ 
+ </listitem>
+ 
+ <listitem><para> Ensure new &slony1; binaries are in place. </para> 
+ 
+ <para> A convenient way to handle this is to have old and new in different directories alongside two &postgres; builds, stop the <application>postmaster</application>, repoint to the new directory, and restart the <application>postmaster</application>. </para>
+ </listitem>
+ 
+ <listitem><para> Run the script that reconfigures replication as generated earlier.  </para> 
+ 
+ <para> This script should probably be split into two portions to be run separately:</para> 
+ <itemizedlist>
+ <listitem><para> Firstly, set up nodes, paths, sets, and such </para> </listitem>
+ <listitem><para> At this point, start up &lslon; processes </para> </listitem>
+ <listitem><para> Then, run the portion which runs <xref linkend="stmtsubscribeset"> </para> </listitem>
+ </itemizedlist>
+ 
+ <para> Splitting the <xref linkend="slonikconfdump"> script as described above is left as an exercise for the reader.</para>
+ </listitem>
+ 
+ <listitem><para> If there were triggers that needed to be activated on subscriber nodes, this is the time to activate them. </para> </listitem>
+ <listitem><para> At this point, the cluster should be back up and running, ready to be reconfigured so that applications may access it again.  </para> </listitem>
+ 
+ </itemizedlist>
+ 
+ </sect2>
  </sect1>
  <!-- Keep this comment at the end of the file

Index: adminscripts.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/adminscripts.sgml,v
retrieving revision 1.52.2.4
retrieving revision 1.52.2.5
diff -C2 -d -r1.52.2.4 -r1.52.2.5
*** adminscripts.sgml	12 Jun 2009 22:42:13 -0000	1.52.2.4
--- adminscripts.sgml	17 Jun 2009 21:37:38 -0000	1.52.2.5
***************
*** 765,769 ****
  <para> The tool <filename>tools/slonikconfdump.sh</filename> was
  created to help dump out a &lslonik; script to duplicate the
! configuration of a functioning &slony1; cluster.</para>
  
  <para> It dumps out: </para>
--- 765,771 ----
  <para> The tool <filename>tools/slonikconfdump.sh</filename> was
  created to help dump out a &lslonik; script to duplicate the
! configuration of a functioning &slony1; cluster.  It should be
! particularly useful when upgrading &slony1; to version 2.0; see <xref
! linkend="upgrade20"> for more details.</para>
  
  <para> It dumps out: </para>
***************
*** 789,793 ****
  # Generated on:  Tue Jun 9 17:34:12 EDT 2009
  cluster name=slony_regress1;
! include <admin-conninfos.slonik>;  # Draw in ADMIN CONNINFO lines
  node 1 admin conninfo='dbname=slonyregress1 host=localhost user=chris port=7083';
  node 2 admin conninfo='dbname=slonyregress2 host=localhost user=chris port=7083';
--- 791,795 ----
  # Generated on:  Tue Jun 9 17:34:12 EDT 2009
  cluster name=slony_regress1;
! include &lt;admin-conninfos.slonik&gt;;  # Draw in ADMIN CONNINFO lines
  node 1 admin conninfo='dbname=slonyregress1 host=localhost user=chris port=7083';
  node 2 admin conninfo='dbname=slonyregress2 host=localhost user=chris port=7083';

Index: slonik_ref.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/slonik_ref.sgml,v
retrieving revision 1.92.2.6
retrieving revision 1.92.2.7
diff -C2 -d -r1.92.2.6 -r1.92.2.7
*** slonik_ref.sgml	16 Apr 2009 16:47:41 -0000	1.92.2.6
--- slonik_ref.sgml	17 Jun 2009 21:37:38 -0000	1.92.2.7
***************
*** 2122,2125 ****
--- 2122,2144 ----
  
        </varlistentry>
+       <varlistentry><term><literal> OMIT COPY = boolean </literal></term>
+        
+        <listitem><para> Flag whether or not the subscription process
+        should omit doing the <command>COPY</command> of the existing
+        data in the set.  In effect, use this option indicates
+        <quote>Trust me, the data is already in sync!</quote>
+        </para>
+ 
+        <para> This is notably useful for the following sorts of cases:
+        </para>
+ 
+        <itemizedlist>
+ 	<listitem><para> Major inter-version upgrades (<emphasis>e.g. </emphasis> - as from &slony1; 1.2 to 2.0) may be done quickly. </para> </listitem>
+ 	<listitem><para> Cloning a <quote>master node</quote>.  <xref linkend="stmtcloneprepare">/<xref linkend="stmtclonefinish">   </para> </listitem>
+ 	<listitem><para> </para> </listitem>
+        </itemizedlist>
+        </listitem>
+ 
+       </varlistentry>
       </variablelist>
      <para> This uses &funsubscribeset;. </para>
***************
*** 2211,2214 ****
--- 2230,2237 ----
       populated <emphasis>from scratch</emphasis>.</para> </listitem>
  
+      <listitem><para> The <command>OMIT COPY</command> option has the
+      potential to be a large <quote>foot gun</quote> in that it allows
+      the administrator to push replication sets out of sync. </para>
+      </listitem>
     </itemizedlist>
  
***************
*** 2229,2232 ****
--- 2252,2256 ----
     <refsect1> <title> Version Information </title>
      <para> This command was introduced in &slony1; 1.0 </para>
+     <para> The <command>OMIT COPY</command> option was introduced in &slony1; 2.0.3.</para>
     </refsect1>
    </refentry>
***************
*** 3093,3097 ****
      <title>Description</title>
      <para>
!      Prepares for cloning a specified node.
      </para>
  
--- 3117,3121 ----
      <title>Description</title>
      <para>
!      Prepares for cloning a specified subscriber node.
      </para>
  

Index: intro.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/intro.sgml,v
retrieving revision 1.29
retrieving revision 1.29.2.1
diff -C2 -d -r1.29 -r1.29.2.1
*** intro.sgml	25 Feb 2008 15:37:58 -0000	1.29
--- intro.sgml	17 Jun 2009 21:37:38 -0000	1.29.2.1
***************
*** 158,167 ****
  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
--- 158,170 ----
  data in replicated tables.  In addition, any
  <emphasis>other</emphasis> triggers and rules on replicated tables are
! <emphasis>suppressed</emphasis> on the subscribers.  On versions of
! &slony1; prior to 2.0, this is done by pointing them, in the system
! table, to the primary key index instead of to the table itself, which
! represents 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.  In version 2.0, this functionality is
! handled via native &postgres; functionality, so that with &slony1;
! 2.0+, <application>pg_dump</application> may be expected to work fine.
! </para>
  
  <para>There is a capability for &slony1; to propagate other kinds of
***************
*** 192,195 ****
--- 195,202 ----
  
  </itemizedlist></para>
+ 
+ <para> &slony1; does not automatically determine what sequences ought
+ to be replicated; you need to add them explicitly using <xref
+ linkend="stmtsetaddsequence">. </para>
  </sect2>