Log Message:
-----------
Add in document on how to perform Slony-I version upgrade

Added Files:
-----------
    slony1-engine/doc/adminguide:
        slonyupgrade.sgml (r1.1)

-------------- next part --------------
--- /dev/null
+++ doc/adminguide/slonyupgrade.sgml
@@ -0,0 +1,55 @@
+<!-- $Id: slonyupgrade.sgml,v 1.1 2006/07/31 14:48:45 cbbrowne Exp $ -->
+<sect1 id="slonyupgrade">
+<title> &slony1; Upgrade </title>
+<indexterm><primary>upgrading &slony1; to a newer version</primary></indexterm>
+
+<para> When upgrading &slony1;, the installation on all nodes in a
+cluster must be upgraded at once, using the &lslonik;
+command <xref linkend="stmtupgradefunctions">.</para>
+
+<para> While this requires temporarily stopping replication, it does
+not forcibly require an outage for applications that submit
+updates. </para>
+
+<para>The proper upgrade procedure is thus:</para>
+<itemizedlist>
+<listitem><para> Stop the &lslon; processes on all nodes.
+(<emphasis>e.g.</emphasis> - old version of &lslon;)</para></listitem>
+<listitem><para> Install the new version of &lslon; software on all
+nodes.</para></listitem>
+<listitem><para> Execute a &lslonik; script containing the
+command <command>update functions (id = [whatever]);</command> for
+each node in the cluster.</para></listitem>
+<listitem><para> Start all slons.  </para> </listitem>
+</itemizedlist>
+
+<para> The trickiest part of this is ensuring that the C library
+containing SPI functions is copied into place in the &postgres; build;
+the easiest and safest way to handle this is to have two separate
+&postgres; builds, one for each &slony1; version, where the postmaster
+is shut down and then restarted against the <quote>new</quote> build;
+that approach requires a brief database outage on each node.</para>
+
+<para> While that approach has been found to be easier and safer,
+nothing prevents one from carefully copying &slony1; components for
+the new version into place to overwrite the old version as
+the <quote>install</quote> step.  That might <emphasis>not</emphasis>
+work on <trademark>Windows</trademark> if it locks library files that
+are in use.</para>
+
+</sect1>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode:sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:"book.sgml"
+sgml-exposed-tags:nil
+sgml-local-catalogs:("/usr/lib/sgml/catalog")
+sgml-local-ecat-files:nil
+End:
+-->