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

Modified Files:
	addthings.sgml bestpractices.sgml defineset.sgml faq.sgml 
	slonik_ref.sgml slonyupgrade.sgml 
Log Message:
Patch that removes TABLE ADD KEY from CVS HEAD.  This supercedes the
previous patch:

http://lists.slony.info/pipermail/slony1-patches/2007-April/000008.html

Per Bill Moran's comments, this also drops out usage of sl_rowid_seq.
http://lists.slony.info/pipermail/slony1-general/2007-April/005883.html

It passes test1, as revised in the patch (e.g. - to remove usage of
TABLE ADD KEY)...

----------------------------------------------------
creating origin DB: cbbrowne -h localhost -U cbbrowne -p 5882 slonyregress1
add plpgsql to Origin
loading origin DB with test1/init_schema.sql
setting up user cbbrowne to have weak access to data
done
creating subscriber 2 DB: cbbrowne -h localhost -U cbbrowne -p 5882
slonyregress2
add plpgsql to subscriber
loading subscriber 2 DB from slonyregress1
done
creating cluster
done
storing nodes
done
Granting weak access on Slony-I schema
done
storing paths
done
launching originnode : /opt/OXRS/dbs/pgsql82/bin/slon -s500 -g10 -d2
slony_regress1 "dbname=slonyregress1 host=localhost user=cbbrowne port=5882"
launching: /opt/OXRS/dbs/pgsql82/bin/slon -s500 -g10 -d2 slony_regress1
"dbname=slonyregress2 host=localhost user=cbbrowne port=5882"
subscribing
done
generating 468 transactions of random data
0 %
5 %
10 %
15 %
20 %
25 %
30 %
35 %
40 %
45 %
50 %
55 %
60 %
65 %
70 %
75 %
80 %
85 %
90 %
95 %
100 %
done
launching polling script
loading data
data load complete
completed generate_sync_event() test
completed make_function_strict() test
done
slony is caught up
getting data from origin DB for diffing
done
getting data from node 2 for diffing against origin
comparing
subscriber node 2 is the same as origin node 1
done
**** killing slon node 1
**** killing slon node 2
waiting for slons to die
done
dropping database
slonyregress1
slonyregress2
done
***************************
test test1 completed successfully
***************************


Index: defineset.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/defineset.sgml,v
retrieving revision 1.26
retrieving revision 1.27
diff -C2 -d -r1.26 -r1.27
*** defineset.sgml	30 Jan 2007 19:48:35 -0000	1.26
--- defineset.sgml	18 Apr 2007 15:03:51 -0000	1.27
***************
*** 71,80 ****
  
  <listitem><para> If the table hasn't even got a candidate primary key,
! you can ask &slony1; to provide one.  This is done by first using
! <xref linkend="stmttableaddkey"> to add a column populated using a
! &slony1; sequence, and then having the <xref
! linkend="stmtsetaddtable"> include the directive
! <option>key=serial</option>, to indicate that &slony1;'s own column
! should be used.</para></listitem>
  
  </itemizedlist>
--- 71,82 ----
  
  <listitem><para> If the table hasn't even got a candidate primary key,
! you might ask &slony1; to provide one using 
! <xref linkend="stmttableaddkey">.</para>
! 
! <warning><para> <xref linkend="stmttableaddkey"> was always considered
! a <quote>kludge</quote>, at best, and as of version 2.0, it is
! considered such a misfeature that it is being removed.  </para>
! </warning>
! </listitem>
  
  </itemizedlist>
***************
*** 83,92 ****
  <quote>true</quote> primary key or a mere <quote>candidate primary
  key;</quote> it is, however, strongly recommended that you have one of
! those instead of having &slony1; populate the PK column for you. If you
! don't have a suitable primary key, that means that the table hasn't got
! any mechanism, from your application's standpoint, for keeping values
! unique. &slony1; may, therefore, introduce a new failure mode for your
! application, and this also implies that you had a way to enter confusing
! data into the database.</para>
  </sect2>
  
--- 85,94 ----
  <quote>true</quote> primary key or a mere <quote>candidate primary
  key;</quote> it is, however, strongly recommended that you have one of
! those instead of having &slony1; populate the PK column for you. If
! you don't have a suitable primary key, that means that the table
! hasn't got any mechanism, from your application's standpoint, for
! keeping values unique.  &slony1; may, therefore, introduce a new
! failure mode for your application, and this also implies that you had
! a way to enter confusing data into the database.</para>
  </sect2>
  

Index: slonyupgrade.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/slonyupgrade.sgml,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** slonyupgrade.sgml	23 Nov 2006 17:16:40 -0000	1.5
--- slonyupgrade.sgml	18 Apr 2007 15:03:51 -0000	1.6
***************
*** 78,81 ****
--- 78,194 ----
  
  </variablelist>
+ 
+ <sect2> <title> TABLE ADD KEY issue in &slony1; 2.0 </title> 
+ 
+ <para> Usually, upgrades between &slony1; versions have required no
+ special attention to the condition of the existing replica.  That is,
+ you fairly much merely need to stop &lslon;s, put new binaries in
+ place, run <xref linkend="stmtupdatefunctions"> against each node, and
+ restart &lslon;s.  Schema changes have been internal to the cluster
+ schema, and <xref linkend="stmtupdatefunctions"> has been capable to
+ make all of the needed alterations.  With version 2, this changes, if
+ there are tables that used <xref linkend="stmttableaddkey">.  Version
+ 2 does not support the <quote>extra</quote> column, and
+ <quote>fixing</quote> the schema to have a proper primary key is not
+ within the scope of what <xref linkend="stmtupdatefunctions"> can
+ perform.  </para>
+ 
+ <para> When upgrading from versions 1.0.x, 1.1.x, or 1.2.x to version
+ 2, it will be necessary to have already eliminated any such
+ &slony1;-managed primary keys. </para>
+ 
+ <para> One may identify the tables affected via the following SQL
+ query: <command> select n.nspname, c.relname from pg_class c,
+ pg_namespace n where c.oid in (select attrelid from pg_attribute where
+ attname like '_Slony-I_%rowID' and not attisdropped) and reltype <> 0
+ and n.oid = c.relnamespace order by n.nspname, c.relname; </command>
+ </para>
+ 
+ <para> The simplest approach that may be taken to rectify the
+ <quote>broken</quote> state of such tables is as follows: </para>
+ 
+ <itemizedlist>
+ 
+ <listitem><para> Drop the table from replication using the &lslonik;
+ command <xref linkend="stmtsetdroptable">. </para>
+ 
+ <para> This does <emphasis>not</emphasis> drop out the &slony1;-generated column. </para>
+ 
+ </listitem>
+ <listitem><para> On each node, run an SQL script to alter the table, dropping the extra column.</para> 
+ <para> <command> alter table whatever drop column "_Slony-I_cluster-rowID";</command> </para>
+ 
+ <para> This needs to be run individually against each node.  Depending
+ on your preferences, you might wish to use <xref
+ linkend="stmtddlscript"> to do this. </para>
+ 
+ <para> If the table is a heavily updated one, it is worth observing
+ that this alteration will require acquiring an exclusive lock on the
+ table.  It will not hold this lock for terribly long; dropping the
+ column should be quite a rapid operation as all it does internally is
+ to mark the column as being dropped; it <emphasis>does not</emphasis>
+ require rewriting the entire contents of the table.  Tuples that have
+ values in that column will continue to have that value; new tuples
+ will leave it NULL, and queries will ignore the column.  Space for
+ those columns will get reclaimed as tuples get updated.  </para>
+ 
+ <para> Note that at this point in the process, this table is not being
+ replicated.  If a failure takes place, replication is not, at this
+ point, providing protection on this table.  This is unfortunate but
+ unavoidable. </para>
+ </listitem>
+ 
+ <listitem><para> Make sure the table has a legitimate candidate for
+ primary key, some set of NOT NULL, UNIQUE columns.  </para>
+ 
+ <para> The possible variations to this are the reason that the
+ developers have made no effort to try to assist automation of
+ this.</para>
+ 
+ <itemizedlist>
+ 
+ <listitem><para> If the table is a small one, it may be perfectly
+ reasonable to do alterations (note that they must be applied to
+ <emphasis>every node</emphasis>!) to add a new column, assign it via a
+ new sequence, and then declare it to be a primary key.  </para>
+ 
+ <para> If there are only a few tuples, this should take a fraction of
+ a second, and, with luck, be unnoticeable to a running
+ application. </para>
+ 
+ <para> Even if the table is fairly large, if it is not frequently
+ accessed by the application, the locking of the table that takes place
+ when you run <command>ALTER TABLE</command> may not cause much
+ inconvenience. </para></listitem>
+ 
+ <listitem> <para> If the table is a large one, and is vital to and
+ heavily accessed by the application, then it may be necessary to take
+ an application outage in order to accomplish the alterations, leaving
+ you necessarily somewhat vulnerable until the process is
+ complete. </para>
+ 
+ <para> If it is troublesome to take outages, then the upgrade to
+ &slony1; version 2 may take some planning... </para>
+ </listitem>
+ 
+ </itemizedlist>
+ </listitem>
+ 
+ <listitem><para> Create a new replication set (<xref
+ linkend="stmtcreateset">) and re-add the table to that set (<xref
+ linkend="stmtsetaddtable">).  </para>
+ 
+ <para> If there are multiple tables, they may be handled via a single
+ replication set.</para>
+ </listitem>
+ 
+ <listitem><para> Subscribe the set (<xref linkend="stmtsubscribeset">)
+ on all the nodes desired. </para> </listitem>
+ 
+ <listitem><para> Once subscriptions are complete, merge the set(s) in,
+ if desired (<xref linkend="stmtmergeset">). </para> </listitem>
+ 
+ </itemizedlist>
+ </sect2>
  </sect1>
  <!-- Keep this comment at the end of the file

Index: bestpractices.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/bestpractices.sgml,v
retrieving revision 1.26
retrieving revision 1.27
diff -C2 -d -r1.26 -r1.27
*** bestpractices.sgml	14 Mar 2007 16:53:51 -0000	1.26
--- bestpractices.sgml	18 Apr 2007 15:03:51 -0000	1.27
***************
*** 224,228 ****
  possibility that updates to this table can fail due to the introduced
  unique index, which means that &slony1; has introduced a new failure
! mode for your application.</para>
  </listitem>
  
--- 224,234 ----
  possibility that updates to this table can fail due to the introduced
  unique index, which means that &slony1; has introduced a new failure
! mode for your application.  
! </para>
! 
! <warning><para> In version 2 of &slony1;, <xref
! linkend="stmttableaddkey"> is no longer supported.  You
! <emphasis>must</emphasis> have either a true primary key or a
! candidate primary key.  </para></warning>
  </listitem>
  

Index: slonik_ref.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/slonik_ref.sgml,v
retrieving revision 1.67
retrieving revision 1.68
diff -C2 -d -r1.67 -r1.68
*** slonik_ref.sgml	14 Mar 2007 16:53:51 -0000	1.67
--- slonik_ref.sgml	18 Apr 2007 15:03:51 -0000	1.68
***************
*** 1010,1020 ****
      </para>
      <para>
!      As a last resort, this command can be used to add such an
!      attribute to a table that does not have a primary key. Since
!      this modification can have unwanted side effects, <emphasis>it is
!       strongly recommended that users add a unique and not null
!       attribute by other means.</emphasis>
      </para>
  
      <variablelist>
       <varlistentry><term><literal> NODE ID = ival </literal></term>
--- 1010,1027 ----
      </para>
      <para>
!      As a last resort, <emphasis>in versions of &slony1; prior to
!      2.0</emphasis>, this command can be used to add such an attribute
!      to a table that does not have a primary key. Since this
!      modification can have unwanted side effects, <emphasis>it is
!      strongly recommended that users add a unique and not null
!      attribute by other means.</emphasis>
      </para>
  
+    <para> If you intend to use &slony1; version 2.0, you
+    <emphasis>must</emphasis> arrange for a more proper primary key.
+    &slony1; will not provide one for you, and if you have cases of
+    keys created via <command>TABLE ADD KEY</command>, you cannot
+    expect &slony1; to function properly. </para>
+ 
      <variablelist>
       <varlistentry><term><literal> NODE ID = ival </literal></term>
***************
*** 1082,1085 ****
--- 1089,1103 ----
     <refsect1> <title> Version Information </title>
      <para> This command was introduced in &slony1; 1.0 </para>
+ 
+     <para> This command is <emphasis> no longer supported </emphasis>
+     as of &slony1; version 2.0.  In version 2, the various
+     <quote>catalogue breakages</quote> done in &postgres; versions
+     prior to 8.3 are being eliminated so that schema dumps may be
+     taken from any node.  That leaves the <quote>kludgy</quote>
+     columns created via <command>TABLE ADD KEY</command> as the only
+     thing that prevents <xref linkend="stmtuninstallnode"> from being
+     comprised of the SQL statement <command>drop schema _ClusterName
+     cascade;</command>.</para>
+ 
     </refsect1>
    </refentry>

Index: faq.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/faq.sgml,v
retrieving revision 1.69
retrieving revision 1.70
diff -C2 -d -r1.69 -r1.70
*** faq.sgml	14 Mar 2007 16:53:51 -0000	1.69
--- faq.sgml	18 Apr 2007 15:03:51 -0000	1.70
***************
*** 15,19 ****
  </question>
  
- 
  <answer><para> <productname>Frotznik Freenix</productname> is new to
  me, so it's a bit dangerous to give really hard-and-fast definitive
--- 15,18 ----

Index: addthings.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/addthings.sgml,v
retrieving revision 1.27
retrieving revision 1.28
diff -C2 -d -r1.27 -r1.28
*** addthings.sgml	13 Mar 2007 21:00:11 -0000	1.27
--- addthings.sgml	18 Apr 2007 15:03:51 -0000	1.28
***************
*** 233,237 ****
  drops the schema and its contents, but also removes any columns
  previously added in using <xref linkend= "stmttableaddkey">.
! </para></listitem>
  </itemizedlist>
  </sect2>
--- 233,243 ----
  drops the schema and its contents, but also removes any columns
  previously added in using <xref linkend= "stmttableaddkey">.
! </para>
! 
! <note><para> In &slony1; version 2.0, <xref linkend=
! "stmttableaddkey"> is <emphasis>no longer supported</emphasis>, and
! thus <xref linkend="stmtuninstallnode"> consists very simply of
! <command>DROP SCHEMA "_ClusterName" CASCADE;</command>.  </para>
! </note></listitem>
  </itemizedlist>
  </sect2>