Update of /home/cvsd/slony1/slony1-engine/doc/adminguide
In directory main:/tmp/cvs-serv23126

Modified Files:
	defineset.sgml 
Log Message:
Mark Stosberg suggested some additional wording about defining tables.
It more explicitly recommends using a primary key, and provides an
example syntax to convert a unique/not null index to a primary key.
cbbrowne did some further wording changes.


Index: defineset.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/defineset.sgml,v
retrieving revision 1.25
retrieving revision 1.26
diff -C2 -d -r1.25 -r1.26
*** defineset.sgml	2 Aug 2006 18:34:57 -0000	1.25
--- defineset.sgml	30 Jan 2007 19:48:35 -0000	1.26
***************
*** 43,47 ****
  <emphasis>candidate</emphasis> primary key, that is, some index on a
  combination of fields that is both UNIQUE and NOT NULL, then you can
! specify the key, as in</para>
  
  <programlisting>
--- 43,47 ----
  <emphasis>candidate</emphasis> primary key, that is, some index on a
  combination of fields that is both UNIQUE and NOT NULL, then you can
! specify that key, as shown in the following example. </para>
  
  <programlisting>
***************
*** 52,55 ****
--- 52,69 ----
  </programlisting>
  
+ <para> However, once you have come this far, there is little reason not
+ to just declare some suitable index to be a primary key, which requires
+ that the columns involved are NOT NULL, and which will establish a unique
+ index. Here is an example of this: </para>
+ 
+ <programlisting>
+ DROP INDEX my_table_name_col1_col2_uniq_idx;
+ ALTER TABLE my_table_name ADD PRIMARY KEY (col1, col2);
+ </programlisting>
+ 
+ <para>If your application is not somehow referencing the index by name,
+ the this should not lose you anything, and it gives you the clear design
+ benefit that a primary key has been declared for the table. </para>
+ 
  <para> Notice that while you need to specify the namespace for the
  table, you must <emphasis>not</emphasis> specify the namespace for the
***************
*** 68,78 ****
  <para> It is not terribly important whether you pick a
  <quote>true</quote> primary key or a mere <quote>candidate primary
! key;</quote> it is, however, 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>
  
--- 82,92 ----
  <para> It is not terribly important whether you pick a
  <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>