Fri Mar 16 12:01:28 PDT 2007
- Previous message: [Slony1-commit] slony1-engine/doc/adminguide releasechecklist.sgml
- Next message: [Slony1-commit] slony1-engine RELEASE-1.2.8
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Update of /home/cvsd/slony1/slony1-engine/doc/adminguide
In directory main.slony.info:/tmp/cvs-serv29453
Modified Files:
Tag: REL_1_2_STABLE
addthings.sgml adminscripts.sgml bestpractices.sgml
defineset.sgml faq.sgml firstdb.sgml help.sgml
installation.sgml intro.sgml monitoring.sgml
releasechecklist.sgml slon.sgml slonconf.sgml slonik_ref.sgml
slonyupgrade.sgml startslons.sgml testbed.sgml
Log Message:
Check numerous revisions made to admin guide in HEAD into 1.2 branch
Index: testbed.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/testbed.sgml,v
retrieving revision 1.10
retrieving revision 1.10.2.1
diff -C2 -d -r1.10 -r1.10.2.1
*** testbed.sgml 2 Aug 2006 18:34:59 -0000 1.10
--- testbed.sgml 16 Mar 2007 19:01:26 -0000 1.10.2.1
***************
*** 95,98 ****
--- 95,112 ----
to be a &postgres; <quote>superuser.</quote> </para> </glossdef> </glossentry>
+ <glossentry><glossterm> <envar>WEAKUSER</envar> </glossterm>
+ <glossdef><para> By default, the user <filename>postgres</filename> is
+ used; this is taken as the default user ID to use for the <xref linkend="stmtstorepath"> connections to all of the
+ databases. </para>
+
+ <para> There are also variables <envar>WEAKUSER1</envar> thru
+ <envar>WEAKUSER13</envar> which allow specifying a separate user name
+ for each database instance. This user <emphasis> does not </emphasis>
+ need to be a &postgres; <quote>superuser.</quote> This user can start
+ out with no permissions; it winds up granted read permissions on the
+ tables that the test uses, plus read access throughout the &slony1;
+ schema, plus write access to one table and sequence used to manage
+ node locks. </para> </glossdef> </glossentry>
+
<glossentry><glossterm> <envar>HOST</envar> </glossterm>
<glossdef><para> By default, <filename>localhost</filename> is used.
Index: intro.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/intro.sgml,v
retrieving revision 1.25
retrieving revision 1.25.2.1
diff -C2 -d -r1.25 -r1.25.2.1
*** intro.sgml 2 Aug 2006 18:34:58 -0000 1.25
--- intro.sgml 16 Mar 2007 19:01:26 -0000 1.25.2.1
***************
*** 142,148 ****
collects updates using triggers, and neither schema changes, large
object operations, nor <command>TRUNCATE</command> requests are able
! to triggers suitable to inform &slony1; when those sorts of changes
! take place. As a result, the only database objects where &slony1; can
! replicate updates are tables and sequences. </para>
<para> Note that with the <emphasis>use</emphasis> of triggers comes
--- 142,148 ----
collects updates using triggers, and neither schema changes, large
object operations, nor <command>TRUNCATE</command> requests are able
! to have triggers suitable to inform &slony1; when those sorts of
! changes take place. As a result, the only database objects where
! &slony1; can replicate updates are tables and sequences. </para>
<para> Note that with the <emphasis>use</emphasis> of triggers comes
***************
*** 167,171 ****
scripts via the <application>slonik</application> <xref
linkend="stmtddlscript"> operation. That is not handled
! <quote>automaticly;</quote> you, as a database administrator, will
have to construct an SQL DDL script and submit it, via <xref
linkend="stmtddlscript"> and there are a number of further <link
--- 167,171 ----
scripts via the <application>slonik</application> <xref
linkend="stmtddlscript"> operation. That is not handled
! <quote>automatically;</quote> you, as a database administrator, will
have to construct an SQL DDL script and submit it, via <xref
linkend="stmtddlscript"> and there are a number of further <link
Index: slonyupgrade.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/slonyupgrade.sgml,v
retrieving revision 1.3.2.1
retrieving revision 1.3.2.2
diff -C2 -d -r1.3.2.1 -r1.3.2.2
*** slonyupgrade.sgml 15 Nov 2006 22:10:45 -0000 1.3.2.1
--- slonyupgrade.sgml 16 Mar 2007 19:01:26 -0000 1.3.2.2
***************
*** 20,24 ****
<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>
--- 20,27 ----
<listitem><para> Execute a &lslonik; script containing the
command <command>update functions (id = [whatever]);</command> for
! each node in the cluster.</para>
! <note><para>Remember that your slonik upgrade script like all other
! slonik scripts must contain the proper preamble commands to function.
! </para></note></listitem>
<listitem><para> Start all slons. </para> </listitem>
</itemizedlist>
Index: monitoring.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/monitoring.sgml,v
retrieving revision 1.29.2.5
retrieving revision 1.29.2.6
diff -C2 -d -r1.29.2.5 -r1.29.2.6
*** monitoring.sgml 5 Dec 2006 23:24:27 -0000 1.29.2.5
--- monitoring.sgml 16 Mar 2007 19:01:26 -0000 1.29.2.6
***************
*** 171,175 ****
a given path (<envar>LOGHOME</envar>), based both on the naming
conventions used by the <xref linkend="launchclusters"> and <xref
! linkend="slonwatchdog"> systems used for launching &lslon; processes.</para>
<para> Errors, if found, are listed, by log file, and emailed to the
--- 171,176 ----
a given path (<envar>LOGHOME</envar>), based both on the naming
conventions used by the <xref linkend="launchclusters"> and <xref
! linkend="slonwatchdog"> systems used for launching &lslon;
! processes.</para>
<para> Errors, if found, are listed, by log file, and emailed to the
***************
*** 183,186 ****
--- 184,212 ----
for replication problems. </para>
</sect2>
+
+ <sect2 id="wikigen"> <title> Building MediaWiki Cluster Summary </title>
+
+ <para> The script <filename>mkmediawiki.pl </filename>, in
+ <filename>tools</filename>, may be used to generate a cluster summary
+ compatible with the popular <ulink url="http://www.mediawiki.org/">
+ MediaWiki </ulink> software. </para>
+
+ <para> The gentle user might use the script as follows: </para>
+
+ <screen>
+ ~/logtail.en> mvs login -d mywiki.example.info -u "Chris Browne" -p `cat ~/.wikipass` -w wiki/index.php
+ Doing login with host: logtail and lang: en
+ ~/logtail.en> perl $SLONYHOME/tools/mkmediawiki.pl --host localhost --database slonyregress1 --cluster slony_regress1 > Slony_replication.wiki
+ ~/logtail.en> mvs commit -m "More sophisticated generated Slony-I cluster docs" Slony_replication.wiki
+ Doing commit Slony_replication.wiki with host: logtail and lang: en
+ </screen>
+
+ <para> Note that <command>mvs</command> is a client written in Perl;
+ on <ulink url="http://www.debian.org/"> Debian GNU/Linux</ulink>, the
+ relevant package is called
+ <application>libwww-mediawiki-client-perl</application>; other systems
+ may have a packaged version of this under some similar name. </para>
+
+ </sect2>
</sect1>
<!-- Keep this comment at the end of the file
Index: firstdb.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/firstdb.sgml,v
retrieving revision 1.20.2.1
retrieving revision 1.20.2.2
diff -C2 -d -r1.20.2.1 -r1.20.2.2
*** firstdb.sgml 13 Mar 2007 16:04:46 -0000 1.20.2.1
--- firstdb.sgml 16 Mar 2007 19:01:26 -0000 1.20.2.2
***************
*** 140,146 ****
and configuration is all done through the <xref linkend="slonik">
tool. It is a specialized scripting aid that mostly calls stored
! procedures in the master/slave (node) databases. The script to create
the initial configuration for the simple master-slave setup of our
! <application>pgbench</application> database looks like this:
<programlisting>
--- 140,184 ----
and configuration is all done through the <xref linkend="slonik">
tool. It is a specialized scripting aid that mostly calls stored
! procedures in the master/slave (node) databases. </para>
!
! <sect3><title>Using the altperl scripts</title>
!
! <para>
! Using the <xref linkend="altperl"> scripts is an easy way to get started. The
! <command>slonik_build_env</command> script will generate output providing
! details you need to omplete building a <filename>slon_tools.conf</filename>.
! An example <filename>slon_tools.conf</filename> is provided in the distribution
! to get you started. The altperl scripts will all reference
! this central configuration file in the future to ease administration. Once
! slon_tools.conf has been created, you can proceed as follows:
! </para>
!
! <programlisting>
! # Initialize cluster:
! $ slonik_init_cluster | slonik
!
! # Start slon (here 1 and 2 are node numbers)
! $ slon_start 1
! $ slon_start 2
!
! # Create Sets (here 1 is a set number)
! $ slonik_create_set 1
!
! # subscribe set to second node (1= set ID, 2= node ID)
! $ slonik_subscribe_set 2 | slonik
! </programlisting>
!
! <para> You have now replicated your first database. You can skip the following section
! of documentation if you'd like, which documents more of a <quote>bare-metal</quote> approach.</para>
! </sect3>
!
! <sect3><title>Using slonik command directly</title>
! <para>The traditional approach to administering slony is to craft slonik
! commands directly. An example of this given here. </para>
!
!
! <para> The script to create
the initial configuration for the simple master-slave setup of our
! <application>pgbench</application> database looks like this:</para>
<programlisting>
***************
*** 201,205 ****
store path (server = 2, client = 1, conninfo='dbname=$SLAVEDBNAME host=$SLAVEHOST user=$REPLICATIONUSER');
_EOF_
! </programlisting></para>
<para>Is the <application>pgbench</application> still running? If
--- 239,243 ----
store path (server = 2, client = 1, conninfo='dbname=$SLAVEDBNAME host=$SLAVEHOST user=$REPLICATIONUSER');
_EOF_
! </programlisting>
<para>Is the <application>pgbench</application> still running? If
***************
*** 281,285 ****
<application>pgbench</application> has completed, so that there are no
new updates hitting the origin node, and that your slon sessions have
! caught up.
<programlisting>
--- 319,323 ----
<application>pgbench</application> has completed, so that there are no
new updates hitting the origin node, and that your slon sessions have
! caught up.</para>
<programlisting>
***************
*** 317,321 ****
fi
</programlisting>
- </para>
<para>Note that there is somewhat more sophisticated documentation of
--- 355,358 ----
***************
*** 325,332 ****
<para>If this script returns <command>FAILED</command> please contact the
developers at <ulink url="http://slony.info/">
! http://slony.info/</ulink></para></sect2>
!
</sect1>
-
<!-- Keep this comment at the end of the file
Local variables:
--- 362,368 ----
<para>If this script returns <command>FAILED</command> please contact the
developers at <ulink url="http://slony.info/">
! http://slony.info/</ulink></para></sect3>
! </sect2>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
Index: bestpractices.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/bestpractices.sgml,v
retrieving revision 1.24
retrieving revision 1.24.2.1
diff -C2 -d -r1.24 -r1.24.2.1
*** bestpractices.sgml 17 Oct 2006 18:45:15 -0000 1.24
--- bestpractices.sgml 16 Mar 2007 19:01:26 -0000 1.24.2.1
***************
*** 376,379 ****
--- 376,418 ----
</listitem>
+ <listitem><para> Lowering Authority </para>
+
+ <para> Traditionally, it has been stated that <quote>&slony1; needs to
+ use superuser connections.</quote> It turns out that this is not
+ entirely true, and and if there are particular concerns about
+ excessive use of superuser accounts, it is possible to reduce this
+ considerably. </para>
+
+ <para> It is true to say that each &lslon; <emphasis>must</emphasis>
+ have a superuser connection in order to manage the node that it is
+ assigned to. It needs to be able to alter the system catalogue in
+ order to set up subscriptions and to process alterations
+ (<emphasis>e.g</emphasis> - to run <xref linkend="stmtddlscript"> and
+ other events that may alter the role of replicated tables on the local
+ node). </para>
+
+ <para> However, the connections that &lslon; processes open to other
+ nodes to access events and process subcriptions do not need to have
+ nearly so much permission. Indeed, one could set up a <quote>weak
+ user</quote> assigned to all <xref linkend="stmtstorepath"> requests.
+ The minimal permissions that this user, let's call it
+ <command>weakuser</command>, requires are as follows:</para>
+
+ <itemizedlist>
+ <listitem><para> It must have read access to the &slony1;-specific namespace </para> </listitem>
+ <listitem><para> It must have read access to all tables and sequences in that namespace</para> </listitem>
+ <listitem><para> It must have write access to the &slony1; table <envar>sl_nodelock</envar> and sequence <envar>sl_nodelock_nl_conncnt_seq</envar> </para> </listitem>
+ <listitem><para> At subscribe time, it must have read access to all of the replicated tables. </para>
+ <para> Outside of subscription time, there is no need for access to access to the replicated tables. </para> </listitem>
+ <listitem><para> There is some need for read access to tables in pg_catalog; it has not been verified how little access would be suitable. </para> </listitem>
+ </itemizedlist>
+
+ <para> In version 1.3, the tests in the <xref linkend="testbed">
+ support using a <envar>WEAKUSER</envar> so that testing can regularly
+ confirm the minimal set of permissions needed to support
+ replication.</para>
+
+ </listitem>
+
<listitem><para> The section on <link linkend="listenpaths"> listen
paths </link> discusses the issues surrounding the table <xref
Index: installation.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/installation.sgml,v
retrieving revision 1.28
retrieving revision 1.28.2.1
diff -C2 -d -r1.28 -r1.28.2.1
*** installation.sgml 17 Oct 2006 18:33:18 -0000 1.28
--- installation.sgml 16 Mar 2007 19:01:26 -0000 1.28.2.1
***************
*** 182,193 ****
<listitem><para><filename> $datadir/slony1_base.v73.sql</filename></para></listitem>
<listitem><para><filename> $datadir/slony1_base.v74.sql</filename></para></listitem>
<listitem><para><filename> $datadir/slony1_funcs.sql</filename></para></listitem>
<listitem><para><filename> $datadir/slony1_funcs.v73.sql</filename></para></listitem>
<listitem><para><filename> $datadir/slony1_funcs.v74.sql</filename></para></listitem>
! <listitem><para><filename> $datadir/xxid.v73.sql </filename></para></listitem>
</itemizedlist>
<para>The <filename>.sql</filename> files are not fully substituted
! yet. And yes, both the 7.3 and the 7.4 files get installed on every
system, irrespective of its version. The <xref linkend="slonik">
admin utility does namespace/cluster substitutions within these files,
--- 182,194 ----
<listitem><para><filename> $datadir/slony1_base.v73.sql</filename></para></listitem>
<listitem><para><filename> $datadir/slony1_base.v74.sql</filename></para></listitem>
+ <listitem><para><filename> $datadir/slony1_base.v80.sql</filename></para></listitem>
<listitem><para><filename> $datadir/slony1_funcs.sql</filename></para></listitem>
<listitem><para><filename> $datadir/slony1_funcs.v73.sql</filename></para></listitem>
<listitem><para><filename> $datadir/slony1_funcs.v74.sql</filename></para></listitem>
! <listitem><para><filename> $datadir/slony1_funcs.v80.sql</filename></para></listitem>
</itemizedlist>
<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,
***************
*** 308,311 ****
--- 309,327 ----
<service name> <config file></command>.</para>
+ <para> For further information about the &windows; port, you may want
+ to see the following URLs: </para>
+
+ <itemizedlist>
+
+ <listitem><para> <ulink
+ url="http://developer.pgadmin.org/~hiroshi/Slony-I/"> Slony-I Windows
+ installer sample </ulink> </para> </listitem>
+
+ <listitem><para> <ulink url=
+ "http://people.planetpostgresql.org/xzilla/index.php?/archives/200-Alpha-testing-Slony-on-win32-Crib-Notes.html">
+ xzilla's Alpha testing Slony on win32 Crib Notes </ulink> </para> </listitem>
+
+ </itemizedlist>
+
</sect2>
Index: help.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/help.sgml,v
retrieving revision 1.18.2.1
retrieving revision 1.18.2.2
diff -C2 -d -r1.18.2.1 -r1.18.2.2
*** help.sgml 27 Oct 2006 15:35:32 -0000 1.18.2.1
--- help.sgml 16 Mar 2007 19:01:26 -0000 1.18.2.2
***************
*** 76,82 ****
Freshmeat on &slony1; </ulink></para></listitem>
- <listitem> <para><ulink url="http://www.slony2.org/wiki/index.php">
- Slony-II Wiki</ulink> </para> </listitem>
-
</itemizedlist>
</sect2>
--- 76,79 ----
Index: startslons.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/startslons.sgml,v
retrieving revision 1.19
retrieving revision 1.19.2.1
diff -C2 -d -r1.19 -r1.19.2.1
*** startslons.sgml 2 Aug 2006 18:34:59 -0000 1.19
--- startslons.sgml 16 Mar 2007 19:01:26 -0000 1.19.2.1
***************
*** 88,93 ****
one point not preferable to run it whilst subscribing a very large
replication set where it is expected to take many hours to do the
! initial <command>COPY SET</command>. The problem that came up in that
! case was that it figured that since it hasn't done a
<command>SYNC</command> in 2 hours, something was broken requiring
restarting slon, thereby restarting the <command>COPY SET</command>
--- 88,94 ----
one point not preferable to run it whilst subscribing a very large
replication set where it is expected to take many hours to do the
! <command>COPY SET</command> (the main event that processes a
! <command>SUBSCRIBE SET</command> request). The problem that came up
! in that case was that it figured that since it hasn't done a
<command>SYNC</command> in 2 hours, something was broken requiring
restarting slon, thereby restarting the <command>COPY SET</command>
Index: slonik_ref.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/slonik_ref.sgml,v
retrieving revision 1.61.2.4
retrieving revision 1.61.2.5
diff -C2 -d -r1.61.2.4 -r1.61.2.5
*** slonik_ref.sgml 31 Oct 2006 22:03:40 -0000 1.61.2.4
--- slonik_ref.sgml 16 Mar 2007 19:01:26 -0000 1.61.2.5
***************
*** 1265,1269 ****
WAIT FOR EVENT (ORIGIN = 3, CONFIRMED = 1);
SYNC (ID=1);
! MERGE SET ( ID = 2, ADD ID = 9999, ORIGIN = 1 );
</programlisting>
</refsect1>
--- 1265,1269 ----
WAIT FOR EVENT (ORIGIN = 3, CONFIRMED = 1);
SYNC (ID=1);
! MERGE SET ( ID = 1, ADD ID = 9999, ORIGIN = 1 );
</programlisting>
</refsect1>
***************
*** 1934,1953 ****
</para>
! <para> If the tables on the subscriber are <emphasis>not</emphasis> empty, then
! the <command>COPY SET</command> process winds up doing more work than should be
! strictly necessary:</para>
<itemizedlist>
! <listitem><para> It deletes all <quote>old</quote> entries in
! the table</para></listitem>
! <listitem><para> Those old entries
! clutter up the table until it is next
! <command>VACUUM</command>ed <emphasis>after</emphasis> the
! subscription process is complete</para></listitem>
<listitem><para> The indices for the table will contain entries
! for the old, deleted entries, which will slow the process of
! inserting new entries into the index.</para></listitem>
</itemizedlist>
--- 1934,1959 ----
</para>
! <para> If the tables on the subscriber are
! <emphasis>not</emphasis> empty, then the <command>COPY
! SET</command> event (which is part of the subscription process)
! may wind up doing more work than should be strictly
! necessary:</para>
<itemizedlist>
+
+ <listitem><para> It attempts to <command>TRUNCATE</command> the
+ table, which will be efficient. </para> </listitem>
! <listitem><para> If that fails (a foreign key relationship might
! prevent TRUNCATE from working), it uses
! <command>DELETE</command> to delete all <quote>old</quote>
! entries in the table</para></listitem>
! <listitem><para> Those old entries clutter up the table until it
! is next <command>VACUUM</command>ed <emphasis>after</emphasis>
! the subscription process is complete</para></listitem>
<listitem><para> The indices for the table will contain entries
! for the old, deleted entries, which will slow the process of
! inserting new entries into the index.</para></listitem>
</itemizedlist>
***************
*** 1960,1971 ****
<para> The <command>SUBSCRIBE SET</command> request will,
! nonetheless, return fairly much immediately, even though the work
! is merely <quote>in progress.</quote> If you need to set up
! subscriptions for a set of cascading nodes, you will need to wait
! for each subscriber to complete subscribing before submitting
! requests for subscriptions that use that node as a provider. If
! you don't, it won't be a big deal: <command>slonik</command> will
! check the node, discover that it is not yet an active provider
! for the set, and report back:</para>
<programlisting>
--- 1966,1978 ----
<para> The <command>SUBSCRIBE SET</command> request will,
! nonetheless, return fairly much immediately, even though the
! work, being handled by the <command>COPY SET</command> event, is
! still in progress. If you need to set up subscriptions for a set
! of cascading nodes, you will need to wait for each subscriber to
! complete subscribing before submitting requests for subscriptions
! that use that node as a provider. If you don't, it won't be a
! big deal: <command>slonik</command> will check the node, discover
! that it is not yet an active provider for the set, and report
! back:</para>
<programlisting>
Index: faq.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/faq.sgml,v
retrieving revision 1.66.2.3
retrieving revision 1.66.2.4
diff -C2 -d -r1.66.2.3 -r1.66.2.4
*** faq.sgml 2 Feb 2007 20:23:46 -0000 1.66.2.3
--- faq.sgml 16 Mar 2007 19:01:26 -0000 1.66.2.4
***************
*** 240,244 ****
</screen></para></question>
-
<answer> <para> There is evidently some reasonably old outstanding
transaction blocking &slony1; from processing the sync. You might
--- 240,243 ----
***************
*** 1018,1022 ****
<answer><para> Another would be to treat the node as having failed,
! and use the &slonik; command <xref linkend="stmtdropnode"> to drop the
node, and recreate it. If the database is heavily updated, it may
well be cheaper to do this than it is to find a way to let it catch
--- 1017,1021 ----
<answer><para> Another would be to treat the node as having failed,
! and use the &lslonik; command <xref linkend="stmtdropnode"> to drop the
node, and recreate it. If the database is heavily updated, it may
well be cheaper to do this than it is to find a way to let it catch
***************
*** 1679,1685 ****
index on the primary key, and leaves all indexes alone whilst using
the &postgres; <command>COPY</command> command to load the data.
! Further hurting performane, the <command>COPY SET</command> event
! starts by deleting the contents of tables, which potentially leaves a
! lot of dead tuples
</para>
--- 1678,1684 ----
index on the primary key, and leaves all indexes alone whilst using
the &postgres; <command>COPY</command> command to load the data.
! Further hurting performance, the <command>COPY SET</command> event (an
! event that the subscription process generates) starts by deleting the
! contents of tables, which leaves the table full of dead tuples.
</para>
Index: releasechecklist.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/releasechecklist.sgml,v
retrieving revision 1.3.2.4
retrieving revision 1.3.2.5
diff -C2 -d -r1.3.2.4 -r1.3.2.5
*** releasechecklist.sgml 8 Nov 2006 19:49:25 -0000 1.3.2.4
--- releasechecklist.sgml 16 Mar 2007 19:01:26 -0000 1.3.2.5
***************
*** 7,42 ****
<itemizedlist>
! <listitem><para>Positive build reports for each supported platform -
! although it is arguably less necessary for a comprehensive list if
! we are releasing a minor upgrade </para></listitem>
<listitem><para>Some kind of Standard Test Plan</para></listitem>
<listitem><para>Binary RPM packages</para></listitem>
! <listitem>
! <para>If the release is a <quote>.0</quote> one, we need to
open a new STABLE branch</para>
! <para> <command> cvs tag -b REL_1_2_STABLE</command></para>
! </listitem>
! <listitem>
! <para>Tag the with the release ID. For version 1.1.2, this
! would be <envar>REL_1_1_2 </envar></para>
! <para> <command> cvs tag REL_1_1_2 </command></para>
! </listitem>
! <listitem><para>Check out a copy via <command>cvs export -rREL_1_1_2 </command>
! </para></listitem>
<listitem><para>Run <application>autoconf</application> so as to
regenerate <filename>configure</filename> from
! <filename>configure.ac</filename>
- </para></listitem>
<listitem><para>Purge directory <filename>autom4te.cache</filename> so it is not included in the build </para></listitem>
- <listitem><para>Purge out .cvsignore files; this can be done with the command <command> find . -name .cvsignore | xargs rm </command> </para></listitem>
<listitem><para> Run <filename>tools/release_checklist.sh</filename> </para>
--- 7,59 ----
<itemizedlist>
! <listitem><para>Positive build reports for each supported platform -
! although it is arguably less necessary for a comprehensive list if we
! are releasing a minor upgrade </para></listitem>
<listitem><para>Some kind of Standard Test Plan</para></listitem>
+
+ <listitem><para> If the release modified the set of version-specific
+ SQL files in <filename>src/backend</filename>
+ (<emphasis>e.g.</emphasis> - it added a new
+ <filename>slony1_base.v83.sql</filename> or
+ <filename>slony1_funcs.v83.sql</filename>), or if we have other
+ changes to the shape of &postgres; version support, the function
+ <function>load_slony_functions() </function> in
+ <filename>src/slonik/slonik.c</filename> needs to be revised to
+ reflect the new shape of things.</para> </listitem>
+
+ <listitem><para> The new release needs to be added to function
+ <function>upgradeSchema(text)</function> in
+ <filename>src/backend/slony1_funcs.sql</filename>. </para>
+
+ <para> This takes place in a <quote>cross-branch</quote> fashion; if
+ we add version 1.1.9, in the 1.1 branch, then version 1.1.9 needs to
+ be added to the 1.2 branch as well as to later branches
+ (<emphasis>e.g.</emphasis> - 1.3, 1.4, HEAD). Earlier branches will
+ normally not need to be made aware of versions added to later
+ branches... </para> </listitem>
+
<listitem><para>Binary RPM packages</para></listitem>
! <listitem> <para>If the release is a <quote>.0</quote> one, we need to
open a new STABLE branch</para>
! <para> <command> cvs tag -b REL_1_2_STABLE</command></para> </listitem>
! <listitem> <para>Tag the with the release ID. For version 1.1.2, this
! would be <envar>REL_1_1_2 </envar></para>
! <para> <command> cvs tag REL_1_1_2 </command></para> </listitem>
! <listitem><para>Check out a copy via <command>cvs export -rREL_1_1_2
! </command> </para></listitem>
<listitem><para>Run <application>autoconf</application> so as to
regenerate <filename>configure</filename> from
! <filename>configure.ac</filename></para></listitem>
<listitem><para>Purge directory <filename>autom4te.cache</filename> so it is not included in the build </para></listitem>
+ <listitem><para>Purge out .cvsignore files; this can be done with the command <command> find . -name .cvsignore | xargs rm </command> </para></listitem>
<listitem><para> Run <filename>tools/release_checklist.sh</filename> </para>
Index: defineset.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/defineset.sgml,v
retrieving revision 1.25
retrieving revision 1.25.2.1
diff -C2 -d -r1.25 -r1.25.2.1
*** defineset.sgml 2 Aug 2006 18:34:57 -0000 1.25
--- defineset.sgml 16 Mar 2007 19:01:26 -0000 1.25.2.1
***************
*** 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>
Index: slonconf.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/slonconf.sgml,v
retrieving revision 1.14.2.1
retrieving revision 1.14.2.2
diff -C2 -d -r1.14.2.1 -r1.14.2.2
*** slonconf.sgml 2 Feb 2007 20:23:46 -0000 1.14.2.1
--- slonconf.sgml 16 Mar 2007 19:01:26 -0000 1.14.2.2
***************
*** 87,91 ****
</indexterm>
<listitem>
! <para>Debug log level (higher value ==> more output). Range: [0,4], default 4</para>
</listitem>
</varlistentry>
--- 87,97 ----
</indexterm>
<listitem>
! <para>Debug log level (higher value ==> more output). Range: [0,4], default 2</para>
!
! <para> There are <link linkend="nineloglevels">nine log
! message types</link>; using this option, some or all of
! the <quote>debugging</quote> levels may be left out of the
! slon logs. </para>
!
</listitem>
</varlistentry>
Index: adminscripts.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/adminscripts.sgml,v
retrieving revision 1.40.2.7
retrieving revision 1.40.2.8
diff -C2 -d -r1.40.2.7 -r1.40.2.8
*** adminscripts.sgml 5 Jan 2007 19:28:48 -0000 1.40.2.7
--- adminscripts.sgml 16 Mar 2007 19:01:26 -0000 1.40.2.8
***************
*** 14,41 ****
<indexterm><primary>altperl scripts for &slony1;</primary></indexterm>
! <para>In the <filename>altperl</filename> directory in the
! <application>CVS</application> tree, there is a sizable set of
! <application>Perl</application> scripts that may be used to administer
! a set of &slony1; instances, which support having arbitrary numbers of
! nodes.</para>
! <para>Most of them generate Slonik scripts that are then to be passed
! on to the <xref linkend="slonik"> utility to be submitted to all of
! the &slony1; nodes in a particular cluster. At one time, this
! embedded running <xref linkend="slonik"> on the slonik scripts.
Unfortunately, this turned out to be a pretty large calibre
<quote>foot gun</quote>, as minor typos on the command line led, on a
! couple of occasions, to pretty calamitous actions, so the behavior has
! been changed so that the scripts simply submit output to standard
! output. The savvy administrator should review the script
! <emphasis>before</emphasis> submitting it to <xref
! linkend="slonik">.</para>
! <sect3><title>Node/Cluster Configuration - cluster.nodes</title>
! <indexterm><primary>cluster.nodes - node/cluster configuration for Perl tools</primary></indexterm>
<para>The UNIX environment variable <envar>SLONYNODES</envar> is used
to determine what Perl configuration file will be used to control the
! shape of the nodes in a &slony1; cluster.</para>
<para>What variables are set up.
--- 14,49 ----
<indexterm><primary>altperl scripts for &slony1;</primary></indexterm>
! <para>There is a set of scripts to simplify administeration
! of set of &slony1; instances. The scripts support having arbitrary numbers of
! nodes. They may be installed as part of the installation process:</para>
! <para><command>
! ./configure --with-perltools
! </command></para>
!
! <para>This will produce a number of scripts with the prefix
! <command>slonik_</command>. They eliminate tedium by always referring
! to a central configuration file for the details of your site
! configuration. A documented sample of this file is provided in
! <filename>altperl/slon_tools.conf-sample</filename>. Most also include
! some command line help with the "--help" option, making them easier to
! learn and use.
! </para>
!
! <para>Most generate Slonik scripts that are printed to STDOUT.
! At one time, the commands were passed directly to <xref linkend="slonik"> for execution.
Unfortunately, this turned out to be a pretty large calibre
<quote>foot gun</quote>, as minor typos on the command line led, on a
! couple of occasions, to pretty calamitous actions. The savvy administrator should review the script
! <emphasis>before</emphasis> piping it to <xref linkend="slonik">.</para>
! <sect3><title>Support for Multiple Clusters</title>
! <indexterm><primary>Multiple Cluster support for the altperl tools</primary></indexterm>
<para>The UNIX environment variable <envar>SLONYNODES</envar> is used
to determine what Perl configuration file will be used to control the
! shape of the nodes in a &slony1; cluster. If it is not provided, a
! default <filename>slon_tools.conf</filename> location will be
! referenced. </para>
<para>What variables are set up.
***************
*** 85,88 ****
--- 93,97 ----
</programlisting>
</sect3>
+
<sect3><title>Set configuration - cluster.set1, cluster.set2</title>
<indexterm><primary>cluster.set1 - replication set configuration for Perl tools</primary></indexterm>
***************
*** 98,130 ****
control what tables will be in a particular replication set.</para>
- <para>What variables are set up.</para>
- <itemizedlist>
- <listitem><para>$TABLE_ID = 44;</para>
- <para> Each table must be identified by a unique number; this variable controls where numbering starts</para>
- </listitem>
- <listitem><para>$SEQUENCE_ID = 17;</para>
- <para> Each sequence must be identified by a unique number; this variable controls where numbering starts</para>
- </listitem>
- <listitem><para>@PKEYEDTABLES</para>
-
- <para> An array of names of tables to be replicated that have a
- defined primary key so that &slony1; can automatically select its key</para>
- </listitem>
- <listitem><para>%KEYEDTABLES</para>
- <para> A hash table of tables to be replicated, where the hash index
- is the table name, and the hash value is the name of a unique not null
- index suitable as a "candidate primary key."</para>
- </listitem>
- <listitem><para>@SERIALTABLES</para>
-
- <para> An array of names of tables to be replicated that have no
- candidate for primary key. &slony1; will add a key field based on a
- sequence that &slony1; generates</para>
- </listitem>
- <listitem><para>@SEQUENCES</para>
-
- <para> An array of names of sequences that are to be replicated</para>
- </listitem>
- </itemizedlist>
</sect3>
<sect3><title>slonik_build_env</title>
--- 107,110 ----
***************
*** 536,539 ****
--- 516,520 ----
use...</para>
</sect3>
+
<sect3><title>Node-Specific Values</title>
***************
*** 649,652 ****
--- 630,643 ----
</sect3>
</sect2>
+
+ <sect2 id="bsd-ports-profile"> <title> <filename> slon.in-profiles </filename> </title>
+ <subtitle> Apache-Style profiles for FreeBSD <filename>ports/databases/slony/*</filename> </subtitle>
+
+ <para> In the tools area, <filename>slon.in-profiles</filename> is a
+ script that might be used to start up &lslon; instances at the time of
+ system startup. It is designed to interact with the FreeBSD Ports
+ system.</para>
+
+ </sect2>
</sect1>
<!-- Keep this comment at the end of the file
Index: slon.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/slon.sgml,v
retrieving revision 1.29
retrieving revision 1.29.2.1
diff -C2 -d -r1.29 -r1.29.2.1
*** slon.sgml 2 Aug 2006 18:34:59 -0000 1.29
--- slon.sgml 16 Mar 2007 19:01:26 -0000 1.29.2.1
***************
*** 41,54 ****
<variablelist>
<varlistentry>
! <term><option>-d</option><replaceable class="parameter"> debuglevel</replaceable></term>
<listitem>
<para>
! The <envar>log_level</envar> specifies which Debug levels
<application>slon</application> should display when logging its
activity.
</para>
! <para>
! The eight levels of logging are:
<itemizedlist>
<listitem><para>Error</para></listitem>
<listitem><para>Warn</para></listitem>
--- 41,55 ----
<variablelist>
<varlistentry>
! <term><option>-d</option><replaceable class="parameter"> log_level</replaceable></term>
<listitem>
<para>
! The <envar>log_level</envar> specifies which levels of debugging messages
<application>slon</application> should display when logging its
activity.
</para>
! <para id="nineloglevels">
! The nine levels of logging are:
<itemizedlist>
+ <listitem><para>Fatal</para></listitem>
<listitem><para>Error</para></listitem>
<listitem><para>Warn</para></listitem>
***************
*** 61,69 ****
</itemizedlist>
</para>
! <para> Thus, <emphasis>all</emphasis> the non-debugging log
! levels are always displayed in the logs. If
! <envar>log_level</envar> is set to 2 (a routine, and, seemingly
preferable choice), then output at debugging levels 1 and 2 will
also be displayed.</para>
</listitem>
</varlistentry>
--- 62,72 ----
</itemizedlist>
</para>
!
! <para> The first five non-debugging log levels (from Fatal to
! Info) are <emphasis>always</emphasis> displayed in the logs. If
! <envar>log_level</envar> is set to 2 (a routine, and, seemingly,
preferable choice), then output at debugging levels 1 and 2 will
also be displayed.</para>
+
</listitem>
</varlistentry>
Index: addthings.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/addthings.sgml,v
retrieving revision 1.23.2.3
retrieving revision 1.23.2.4
diff -C2 -d -r1.23.2.3 -r1.23.2.4
*** addthings.sgml 7 Nov 2006 20:34:17 -0000 1.23.2.3
--- addthings.sgml 16 Mar 2007 19:01:26 -0000 1.23.2.4
***************
*** 135,138 ****
--- 135,149 ----
linkend="stmtddlscript">.</para>
+ <para> Alternatively, if you have the <link linkend="altperl"> altperl
+ scripts </link> installed, you may use
+ <command>slonik_execute_script</command> for this purpose: </para>
+
+ <para> <command> slonik_execute_script [options] set#
+ full_path_to_sql_script_file </command></para>
+
+ <para> See <command>slonik_execute_script -h</command> for further
+ options; note that this uses <xref linkend="stmtddlscript">
+ underneath. </para>
+
<para> There are a number of <quote>sharp edges</quote> to note...</para>
- Previous message: [Slony1-commit] slony1-engine/doc/adminguide releasechecklist.sgml
- Next message: [Slony1-commit] slony1-engine RELEASE-1.2.8
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
More information about the Slony1-commit mailing list