Wed Jun 29 21:13:39 PDT 2005
- Previous message: [Slony1-commit] By darcyb: The attached patch implements a suitable build environment
- Next message: [Slony1-commit] By cbbrowne: Further formatting changes.
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Log Message:
-----------
Lots of textual changes in preparation for OSCON documentation release.
Modified Files:
--------------
slony1-engine/doc/adminguide:
adminscripts.sgml (r1.24 -> r1.25)
bestpractices.sgml (r1.9 -> r1.10)
concepts.sgml (r1.15 -> r1.16)
ddlchanges.sgml (r1.15 -> r1.16)
defineset.sgml (r1.18 -> r1.19)
faq.sgml (r1.40 -> r1.41)
firstdb.sgml (r1.13 -> r1.14)
installation.sgml (r1.13 -> r1.14)
intro.sgml (r1.17 -> r1.18)
legal.sgml (r1.6 -> r1.7)
locking.sgml (r1.2 -> r1.3)
logshipping.sgml (r1.9 -> r1.10)
plainpaths.sgml (r1.8 -> r1.9)
prerequisites.sgml (r1.18 -> r1.19)
slonik_ref.sgml (r1.27 -> r1.28)
slony.sgml (r1.20 -> r1.21)
usingslonik.sgml (r1.11 -> r1.12)
versionupgrade.sgml (r1.5 -> r1.6)
-------------- next part --------------
Index: versionupgrade.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/versionupgrade.sgml,v
retrieving revision 1.5
retrieving revision 1.6
diff -Ldoc/adminguide/versionupgrade.sgml -Ldoc/adminguide/versionupgrade.sgml -u -w -r1.5 -r1.6
--- doc/adminguide/versionupgrade.sgml
+++ doc/adminguide/versionupgrade.sgml
@@ -1,7 +1,8 @@
<!-- $Id$ -->
<sect1 id="versionupgrade"><title>Using &slony1; for &postgres; Upgrades</title>
-<indexterm><primary>&slony1; for &postgres; version upgrades</primary></indexterm>
+<indexterm><primary>version upgrades for &postgres; using
+&slony1;</primary></indexterm>
<para> A number of people have found
&slony1; useful for helping perform upgrades
Index: defineset.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/defineset.sgml,v
retrieving revision 1.18
retrieving revision 1.19
diff -Ldoc/adminguide/defineset.sgml -Ldoc/adminguide/defineset.sgml -u -w -r1.18 -r1.19
--- doc/adminguide/defineset.sgml
+++ doc/adminguide/defineset.sgml
@@ -5,7 +5,7 @@
<para>Defining the nodes indicated the shape of the cluster of
database servers; it is now time to determine what data is to be
copied between them. The groups of data that are copied are defined
-as <quote>sets.</quote></para>
+as <quote>replication sets.</quote></para>
<para>A replication set consists of the following:</para>
<itemizedlist>
@@ -30,12 +30,12 @@
<listitem><para> If the table has a formally identified primary key,
<xref linkend="stmtsetaddtable"> can be used without any need to
-reference the primary key. &slony1; will pick up that there is a
-primary key, and use it.</para></listitem>
+reference the primary key. &slony1; can automatically pick up that
+there is a primary key, and use it.</para></listitem>
<listitem><para> If the table hasn't got a primary key, but has some
<emphasis>candidate</emphasis> primary key, that is, some index on a
-combination of fields that is UNIQUE and NOT NULL, then you can
+combination of fields that is both UNIQUE and NOT NULL, then you can
specify the key, as in</para>
<programlisting>
@@ -63,10 +63,10 @@
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 of keeping values
-unique. &slony1; may therefore introduce a new failure mode for your
-application, and this implies that you had a way to enter confusing
-data into the database.</para>
+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>
<sect2 id="definesets"><title>Grouping tables into sets</title>
Index: adminscripts.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/adminscripts.sgml,v
retrieving revision 1.24
retrieving revision 1.25
diff -Ldoc/adminguide/adminscripts.sgml -Ldoc/adminguide/adminscripts.sgml -u -w -r1.24 -r1.25
--- doc/adminguide/adminscripts.sgml
+++ doc/adminguide/adminscripts.sgml
@@ -16,8 +16,9 @@
<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. An administrator should review the script
-<emphasis>before</emphasis> submitting it to <xref linkend="slonik">.</para>
+output. The savvy administrator should review the script
+<emphasis>before</emphasis> submitting it to <xref
+linkend="slonik">.</para>
<sect2><title>Node/Cluster Configuration - cluster.nodes</title>
Index: slonik_ref.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/slonik_ref.sgml,v
retrieving revision 1.27
retrieving revision 1.28
diff -Ldoc/adminguide/slonik_ref.sgml -Ldoc/adminguide/slonik_ref.sgml -u -w -r1.27 -r1.28
--- doc/adminguide/slonik_ref.sgml
+++ doc/adminguide/slonik_ref.sgml
@@ -249,7 +249,6 @@
<refentry id ="admconninfo"><refmeta><refentrytitle>ADMIN CONNINFO</refentrytitle> </refmeta>
<refnamediv><refname>ADMIN CONNINFO</refname>
-
<refpurpose> preamble - identifying <productname>PostgreSQL</productname> database </refpurpose>
</refnamediv>
<refsynopsisdiv>
Index: bestpractices.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/bestpractices.sgml,v
retrieving revision 1.9
retrieving revision 1.10
diff -Ldoc/adminguide/bestpractices.sgml -Ldoc/adminguide/bestpractices.sgml -u -w -r1.9 -r1.10
--- doc/adminguide/bestpractices.sgml
+++ doc/adminguide/bestpractices.sgml
@@ -1,6 +1,7 @@
<!-- $Id$ -->
<sect1 id="bestpractices">
<title> &slony1; <quote>Best Practices</quote> </title>
+<indexterm><primary>best practices for &slony1; usage</primary></indexterm>
<para> It is common for managers to have a desire to operate systems
using some available, documented set of <quote>best practices.</quote>
@@ -81,9 +82,9 @@
<para> At Afilias, some internal <citation>The 3AM Unhappy DBA's Guide
to...</citation> guides have been created to provide checklists of
-what to do when <quote>unhappy</quote> things happen; this sort of
-material is highly specific to the applications running, so you would
-need to generate your own such documents.
+what to do when certain <quote>unhappy</quote> events take place; this
+sort of material is highly specific to the applications running, so
+you would need to generate your own such documents.
</para>
</listitem>
@@ -305,16 +306,15 @@
<xref linkend="slonik"> scripts.</para>
</listitem>
-<listitem><para> Handling Very Large Replication Sets </para></listitem>
+<listitem><para> Handling Very Large Replication Sets </para>
-<listitem><para> Some users have set up replication on replication sets that are
+<para> Some users have set up replication on replication sets that are
tens to hundreds of gigabytes in size, which puts some added
<quote>strain</quote> on the system, in particular where it may take
several days for the <command>COPY_SET</command> event to complete.
Here are some principles that have been observed for dealing with
-these sorts of situtations.</para></listitem>
+these sorts of situtations.</para>
-</itemizedlist>
<itemizedlist>
<listitem><para> Drop all indices other than the primary key index
@@ -352,9 +352,8 @@
</para> </listitem>
<listitem><para> Several things can be done that will help, involving
-careful selection of <xref linkend="slon"> parameters:</para></listitem>
+careful selection of <xref linkend="slon"> parameters:</para>
-</itemizedlist>
<itemizedlist>
<listitem><para> On the subscriber's <xref linkend="slon">, increase
@@ -385,6 +384,7 @@
the data is copied and the subscriber starts to catch up. </para>
</listitem>
</itemizedlist>
+</itemizedlist>
</sect1>
<!-- Keep this comment at the end of the file
Index: concepts.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/concepts.sgml,v
retrieving revision 1.15
retrieving revision 1.16
diff -Ldoc/adminguide/concepts.sgml -Ldoc/adminguide/concepts.sgml -u -w -r1.15 -r1.16
--- doc/adminguide/concepts.sgml
+++ doc/adminguide/concepts.sgml
@@ -2,7 +2,6 @@
<sect1 id="concepts">
<title>&slony1; Concepts</title>
-
<para>In order to set up a set of &slony1; replicas, it is necessary
to understand the following major abstractions that it uses:</para>
Index: firstdb.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/firstdb.sgml,v
retrieving revision 1.13
retrieving revision 1.14
diff -Ldoc/adminguide/firstdb.sgml -Ldoc/adminguide/firstdb.sgml -u -w -r1.13 -r1.14
--- doc/adminguide/firstdb.sgml
+++ doc/adminguide/firstdb.sgml
@@ -194,8 +194,8 @@
_EOF_
</programlisting></para>
-<para>Is the <application>pgbench</application> still running? If not start it
-again.</para>
+<para>Is the <application>pgbench</application> still running? If
+not, then start it again.</para>
<para>At this point we have 2 databases that are fully prepared. One
is the master database in which <application>pgbench</application> is
@@ -267,8 +267,10 @@
are in fact the same.</para>
<para>The following script will create ordered dumps of the 2
-databases and compare them. Make sure that <application>pgbench</application> has
-completed its testing, and that your slon sessions have caught up.
+databases and compare them. Make sure that
+<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>
#!/bin/sh
Index: prerequisites.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/prerequisites.sgml,v
retrieving revision 1.18
retrieving revision 1.19
diff -Ldoc/adminguide/prerequisites.sgml -Ldoc/adminguide/prerequisites.sgml -u -w -r1.18 -r1.19
--- doc/adminguide/prerequisites.sgml
+++ doc/adminguide/prerequisites.sgml
@@ -104,14 +104,12 @@
will need approximately 5MB for the source tree during build and
installation.</para>
-<note><para>There are changes afoot for version 1.1 that ought to make
-it possible to compile &slony1; separately from &postgres;, which
-should make it practical for the makers of distributions of
-<productname>Linux</productname> and
+<note><para>In &slony1; version 1.1, it is possible to compile
+&slony1; separately from &postgres;, making it practical for the
+makers of distributions of <productname>Linux</productname> and
<productname>FreeBSD</productname> to include precompiled binary
-packages for &slony1;, but until that happens, you need to be prepared
-to use versions of all this software that you compile
-yourself.</para></note>
+packages for &slony1;. If no suitable packages are available, you
+will need to be prepared to compile &slony1; yourself. </para></note>
</sect2>
<sect2>
@@ -130,10 +128,12 @@
<para> All the servers used within the replication cluster need to
have their Real Time Clocks in sync. This is to ensure that <xref
linkend="slon"> doesn't generate errors with messages indicating that
-a subscriber is already ahead of its provider during replication. We
-recommend you have <application>ntpd</application> running on all
-nodes, where subscriber nodes using the <quote>master</quote> provider
-host as their time server.</para>
+a subscriber is already ahead of its provider during replication.
+Interpreting logs when servers have a different idea of what time it
+is leads to confusion and frustration. It is recommended that you
+have <application>ntpd</application> running on all nodes, where
+subscriber nodes using the <quote>master</quote> provider host as
+their time server.</para>
<para> It is possible for &slony1; itself to function even in the face
of there being some time discrepancies, but having systems <quote>in
Index: legal.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/legal.sgml,v
retrieving revision 1.6
retrieving revision 1.7
diff -Ldoc/adminguide/legal.sgml -Ldoc/adminguide/legal.sgml -u -w -r1.6 -r1.7
--- doc/adminguide/legal.sgml
+++ doc/adminguide/legal.sgml
@@ -23,11 +23,11 @@
</para>
<para>
- IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY
- PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
- DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS
- SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA
- HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
+FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES,
+INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND
+ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</para>
<para>
Index: faq.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/faq.sgml,v
retrieving revision 1.40
retrieving revision 1.41
diff -Ldoc/adminguide/faq.sgml -Ldoc/adminguide/faq.sgml -u -w -r1.40 -r1.41
Index: usingslonik.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/usingslonik.sgml,v
retrieving revision 1.11
retrieving revision 1.12
diff -Ldoc/adminguide/usingslonik.sgml -Ldoc/adminguide/usingslonik.sgml -u -w -r1.11 -r1.12
--- doc/adminguide/usingslonik.sgml
+++ doc/adminguide/usingslonik.sgml
@@ -44,7 +44,7 @@
<itemizedlist>
<listitem><para> Named nodes, named sets</para>
-<para> This is supported by the (new in 1.1) <xref
+<para> This is supported in &slony1; 1.1 by the <xref
linkend="stmtdefine"> and <xref linkend="stmtinclude"> statements.
</para></listitem>
@@ -69,12 +69,13 @@
<para> The test bed found in the <filename>src/ducttape</filename>
directory takes this approach.</para></listitem>
-<listitem><para> The <xref linkend="altperl"> use Perl code to
-generate Slonik scripts.</para>
+<listitem><para> The <link linkend="altperl"> altperl tools </link>
+use Perl code to generate Slonik scripts.</para>
-<para> You define the cluster as a set of Perl objects; each script
-walks through the Perl objects as needed to satisfy whatever it is
-supposed to do. </para></listitem>
+<para> You define the cluster's configuration as a set of Perl
+objects; each script walks through the Perl objects as needed to
+generate a slonik script for that script's purpose.
+</para></listitem>
</itemizedlist>
</sect1>
@@ -269,14 +270,17 @@
<para> The developers of &slony1; anticipate that interested parties
may wish to develop graphical tools as an alternative to Slonik; it
would be entirely appropriate in such cases to submit configuration
-requests directly via the stored functions.</para>
+requests directly via the stored functions. If you plan to do so, it
+is suggested that you examine how the stored procedures get used in
+<filename>slonik.c</filename>, as that should be the most
+representative way of seeing correct use of the functions.</para>
<para> When debugging problems in <quote>troubled</quote> &slony1;
clusters, it has also occasionally proven useful to use the stored
functions. This has been particularly useful for cases where <xref
- linkend="table.sl-listen"> configuration has been broken, and
-events have not been propagating properly. The <quote>easiest</quote>
-fix was to:</para>
+linkend="table.sl-listen"> configuration has been broken, and events
+have not been propagating properly. The <quote>easiest</quote> fix
+was to:</para>
<para> <command> select
_slonycluster.droplisten(li_origin,li_provider,li_receiver) from
Index: intro.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/intro.sgml,v
retrieving revision 1.17
retrieving revision 1.18
diff -Ldoc/adminguide/intro.sgml -Ldoc/adminguide/intro.sgml -u -w -r1.17 -r1.18
--- doc/adminguide/intro.sgml
+++ doc/adminguide/intro.sgml
@@ -3,15 +3,15 @@
<title>Introduction to &slony1;</title>
<sect2> <title>What &slony1; is</title>
-<para>&slony1; is a <quote>master to
-multiple slaves</quote> replication system supporting cascading and
-slave promotion. The big picture for the development of
-&slony1; is as a master-slave system that
-includes all features and capabilities needed to replicate large
+<para>&slony1; is a <quote>master to multiple slaves</quote>
+replication system supporting cascading and slave promotion. The big
+picture for the development of &slony1; is as a master-slave system
+that includes the sorts of capabilities needed to replicate large
databases to a reasonably limited number of slave systems.
-<quote>Reasonable,</quote> in this context, is probably no more than a
-few dozen servers. If the number of servers grows beyond that, the
-cost of communications becomes prohibitively high.</para>
+<quote>Reasonable,</quote> in this context, is on the order of a dozen
+servers. If the number of servers grows beyond that, the cost of
+communications increases prohibitively, and the incremental benefits
+of having multiple servers will be falling off at that point.</para>
<para> See also <xref linkend="slonylistenercosts"> for a further
analysis of costs associated with having many nodes.</para>
@@ -33,13 +33,23 @@
<para> Replicating a pricing database from a central server to sales
staff who connect periodically to grab updates. </para></listitem>
+
+<listitem><para> Sites where configuration changes are made in a
+haphazard way.</para>
+
+<para> A <quote>web hosting</quote> situation where customers can
+independently make arbitrary changes to database schemas is not a good
+candidate for &slony1; usage. </para></listitem>
+
</itemizedlist></para>
<para> There is also a <link linkend="logshipping">file-based log
shipping</link> extension where updates would be serialized into
files. Given that, log files could be distributed by any means
desired without any need of feedback between the provider node and
-those nodes subscribing via <quote>log shipping.</quote></para>
+those nodes subscribing via <quote>log shipping.</quote> <quote>Log
+shipped</quote> nodes do not add to the costs of communicating events
+between &slony1; nodes.</para>
<para> But &slony1;, by only having a single origin for each set, is
quite unsuitable for <emphasis>really</emphasis> asynchronous multiway
@@ -48,10 +58,11 @@
resolution</quote> akin to what is provided by <productname>Lotus
<trademark>Notes</trademark></productname> or the
<quote>syncing</quote> protocols found on PalmOS systems, you will
-really need to look elsewhere. These sorts of replication models are
-not without merit, but they represent <emphasis>different</emphasis>
-replication scenarios that &slony1; does not attempt to
-address.</para>
+really need to look elsewhere. </para>
+
+<para> These other sorts of replication models are not without merit,
+but they represent <emphasis>different</emphasis> replication
+scenarios that &slony1; does not attempt to address.</para>
</sect2>
@@ -73,16 +84,17 @@
node failure, nor to automatically promote a node to a master or other
data origin.</para>
-<para> It is quite possible that you may need to do that; that
-will require that you combine some network tools that evaluate
-<emphasis> to your satisfaction </emphasis> which nodes you consider
+<para> It is quite possible that you may need to do that; that will
+require that you combine some network tools that evaluate <emphasis>
+to your satisfaction </emphasis> which nodes you consider
<quote>live</quote> and which nodes you consider <quote>dead</quote>
along with some local policy to determine what to do under those
circumstances. &slony1; does not dictate any of that policy to
you.</para></listitem>
-<listitem><para>&slony1; is not multi-master; it is not a connection broker, and
-it doesn't make you coffee and toast in the morning.</para></listitem>
+<listitem><para>&slony1; is not a multi-master replication system; it
+is not a connection broker, and it won't make you coffee and toast in
+the morning.</para></listitem>
</itemizedlist>
@@ -97,24 +109,27 @@
<sect2><title> Why doesn't &slony1; do automatic fail-over/promotion?
</title>
-<para>That is properly the responsibility of network monitoring
-software, not &slony1;. The configuration, fail-over paths, and
-preferred policies will be different for each site. For example,
-keep-alive monitoring with redundant NIC's and intelligent HA switches
-that guarantee race-condition-free takeover of a network address and
-disconnecting the <quote>failed</quote> node will vary based on
-network configuration, vendor choices, and the combinations of
-hardware and software in use. This is clearly the realm of network
-management software and not &slony1;.</para>
+<para>Determining whether a node has <quote>failed</quote> is properly
+the responsibility of network management software, not &slony1;. The
+configuration, fail-over paths, and preferred policies will be
+different for each site. For example, keep-alive monitoring with
+redundant NIC's and intelligent HA switches that guarantee
+race-condition-free takeover of a network address and disconnecting
+the <quote>failed</quote> node will vary based on network
+configuration, vendor choices, and the combinations of hardware and
+software in use. This is clearly in the realm of network management
+and not &slony1;.</para>
<para> Furthermore, choosing what to do based on the
-<quote>shape</quote> of the cluster represents local business policy.
-If &slony1; imposed failover policy on you, that might conflict with
-business requirements, thereby making &slony1; an unacceptable
-choice.</para>
+<quote>shape</quote> of the cluster represents local business policy,
+particularly in view of the fact that <link
+linkend="stmtfailover"><command>FAIL OVER</command></link> requires
+discarding the failed node. If &slony1; imposed failover policy on
+you, that might conflict with business requirements, thereby making
+&slony1; an unacceptable choice.</para>
<para>As a result, let &slony1; do what it does best: provide database
-replication.</para></sect2>
+replication services.</para></sect2>
<sect2><title> Current Limitations</title>
@@ -129,7 +144,8 @@
you submit them as scripts via the <application>slonik</application>
<xref linkend="stmtddlscript"> operation. That is not
<quote>automatic;</quote> you have to construct an SQL DDL script and
-submit it, and there are a number of further caveats.</para>
+submit it, and there are a number of further <link
+linkend="ddlchanges"> caveats.</link></para>
<para>If you have those sorts of requirements, it may be worth
exploring the use of &postgres; 8.0 <acronym>PITR</acronym> (Point In
@@ -215,10 +231,16 @@
address update, one user, on one node, might update the phone number
for an address, and another user might update the street address, and
the conflict resolution system might try to apply these updates in a
-non-conflicting order.</para>
+non-conflicting order. This can also be considered a form of
+<quote>table partitioning</quote> where a database table is treated as
+consisting of several <quote>sub-tables.</quote> </para>
<para> Conflict resolution systems almost always require some domain
-knowledge of the application being used. </para>
+knowledge of the application being used, which means that they can
+only deal automatically with those conflicts where you have assigned a
+policy. If they run into conflicts for which no policy is available,
+replication stops until someone applies some manual
+intervention. </para>
</listitem>
</itemizedlist>
Index: ddlchanges.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/ddlchanges.sgml,v
retrieving revision 1.15
retrieving revision 1.16
diff -Ldoc/adminguide/ddlchanges.sgml -Ldoc/adminguide/ddlchanges.sgml -u -w -r1.15 -r1.16
--- doc/adminguide/ddlchanges.sgml
+++ doc/adminguide/ddlchanges.sgml
@@ -4,7 +4,7 @@
<indexterm>
<primary> DDL changes </primary>
- <secondary> changing the database schema </secondary>
+ <secondary>database schema changes</secondary>
</indexterm>
<para>When changes are made to the database schema,
@@ -38,9 +38,9 @@
<listitem><para>The script <emphasis>must not</emphasis> contain
transaction <command>BEGIN</command> or <command>END</command>
statements, as the script is already executed inside a transaction.
-In &postgres; version 8, the introduction of nested transactions may
-modify this requirement somewhat, but you must still remain aware that
-the actions in the script are wrapped inside a
+In &postgres; version 8, the introduction of nested transactions
+changes this somewhat, but you must still remain aware that the
+actions in the script are wrapped inside a single
transaction.</para></listitem>
<listitem><para>If there is <emphasis>anything</emphasis> broken about
@@ -51,7 +51,12 @@
certainly, fail the second time just as it did the first time. I have
found this scenario to lead to a need to go to the
<quote>master</quote> node to delete the event to stop it from
-continuing to fail.</para></listitem>
+continuing to fail.</para>
+
+<para> The implication of this is that it is
+<emphasis>vital</emphasis> that modifications not be made in a
+haphazard way on one node or another. The schemas must always stay in
+sync.</para> </listitem>
<listitem><para> For <application>slon</application> to, at that
point, <quote>panic</quote> is probably the
Index: installation.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/installation.sgml,v
retrieving revision 1.13
retrieving revision 1.14
diff -Ldoc/adminguide/installation.sgml -Ldoc/adminguide/installation.sgml -u -w -r1.13 -r1.14
--- doc/adminguide/installation.sgml
+++ doc/adminguide/installation.sgml
@@ -56,6 +56,10 @@
<sect2>
<title>Example</title>
+<para> After determining that the &postgres; instance to be used is
+installed in
+<filename>/opt/dbs/pgsql746-aix-2005-04-01</filename>:</para>
+
<screen>
PGMAIN=/opt/dbs/pgsql746-aix-2005-04-01 \
./configure \
@@ -81,6 +85,9 @@
</ulink> Similar patches may need to be constructed for other
versions; see the FAQ entry on <link linkend="threadsafety"> thread
safety </link>. </para>
+
+<para> For a full listing of configuration options, run the command
+<command>./configure --help</command>.</para>
</sect2>
<sect2>
@@ -116,10 +123,11 @@
</command></para>
<para>This will install files into postgresql install directory as
-specified by the <option>--prefix</option> option used in the
-&postgres; installation. Make sure you have appropriate permissions
-to write into that area. Normally you need to do this either as root
-or as the postgres user. </para>
+specified by the <command>configure</command>
+<option>--prefix</option> option used in the &postgres; installation.
+Make sure you have appropriate permissions to write into that area.
+Commonly you need to do this either as root or as the postgres user.
+</para>
</sect2>
</sect1>
Index: plainpaths.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/plainpaths.sgml,v
retrieving revision 1.8
retrieving revision 1.9
diff -Ldoc/adminguide/plainpaths.sgml -Ldoc/adminguide/plainpaths.sgml -u -w -r1.8 -r1.9
--- doc/adminguide/plainpaths.sgml
+++ doc/adminguide/plainpaths.sgml
@@ -1,7 +1,7 @@
<!-- $Id$ -->
<sect1 id="plainpaths"><title> &slony1; Path Communications</title>
-<para> &slony1; uses &postgres; DSNs in two contexts to establish
+<para> &slony1; uses &postgres; DSNs in three contexts to establish
access to databases:
<itemizedlist>
@@ -24,6 +24,12 @@
connections using <link linkend="tunnelling">SSH
tunnelling</link>.</para></listitem>
+<listitem><para> The <xref linkend="slon"> DSN parameter. </para>
+
+<para> The DSN parameter passed to each <xref linkend="slon">
+indicates what network path should be used to get from the slon
+process to the database that it manages.</para> </listitem>
+
<listitem><para> <xref linkend="stmtstorepath"> - controlling how
<xref linkend="slon"> daemons communicate with remote nodes. These
paths are stored in <xref linkend="table.sl-path">.</para>
@@ -79,8 +85,8 @@
would doubtless prefer for them to be useful, and that can certainly
be the case. If the primary site is being used for
<quote>transactional activities,</quote> the replicas at the secondary
-site may be used for running time-oriented reports that are allowed to
-be a little bit behind.</para></listitem>
+site may be used for running time-oriented reports that do not require
+up-to-the second data.</para></listitem>
<listitem><para> The symmetry of the configuration means that if you
had <emphasis>two</emphasis> transactional applications needing
Index: logshipping.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/logshipping.sgml,v
retrieving revision 1.9
retrieving revision 1.10
diff -Ldoc/adminguide/logshipping.sgml -Ldoc/adminguide/logshipping.sgml -u -w -r1.9 -r1.10
--- doc/adminguide/logshipping.sgml
+++ doc/adminguide/logshipping.sgml
@@ -1,6 +1,7 @@
<!-- $Id$ -->
<sect1 id="logshipping">
<title>Log Shipping - &slony1; with Files</title>
+<indexterm><primary>log shipping</primary></indexterm>
<para> One of the new features for 1.1 is the ability to serialize the
updates to go out into log files that can be kept in a spool
@@ -118,22 +119,10 @@
entirety of the traffic going to a subscriber. You cannot separate
things out if there are multiple replication sets. </para></answer>
-<answer><para> The <quote>log shipping node</quote> presently tracks
-only <command>SYNC</command> events. This should be sufficient to cope with
-<emphasis>some</emphasis> changes in cluster configuration, but not
-others. </para>
-
-<para> Log shipping does <emphasis>not</emphasis> process certain
-additional events, with the implication that the introduction of any
-of the following events can invalidate the relationship between the
-<command>SYNC</command>s and the dump created using
-<application>slony1_dump.sh</application> so that you'll likely need
-to rerun <application>slony1_dump.sh</application>:
-
-<itemizedlist>
-<listitem><para><command> SUBSCRIBE_SET </command></para></listitem>
-
-</itemizedlist></para>
+<answer><para> The <quote>log shipping node</quote> presently only
+fully tracks <command>SYNC</command> events. This should be
+sufficient to cope with <emphasis>some</emphasis> changes in cluster
+configuration, but not others. </para>
<para> A number of event types <emphasis> are </emphasis> handled in
such a way that log shipping copes with them:
@@ -159,6 +148,8 @@
<command>MERGE_SET</command>, will be handled
<quote>appropriately</quote>.</para></listitem>
+<listitem><para><command> SUBSCRIBE_SET </command></para></listitem>
+
<listitem><para> The various events involved in node configuration are
irrelevant to log shipping:
@@ -205,13 +196,15 @@
<itemizedlist>
<listitem><para> You <emphasis>don't</emphasis> want to blindly apply
-<command>SYNC</command> files because any given <command>SYNC</command> file may <emphasis>not</emphasis> be
-the right one. If it's wrong, then the result will be that the call
-to <function> setsyncTracking_offline() </function> will fail, and
-your <application> psql</application> session will <command> ABORT
-</command>, and then run through the remainder of that <command>SYNC</command> file
-looking for a <command>COMMIT</command> or <command>ROLLBACK</command>
-so that it can try to move on to the next transaction.</para>
+<command>SYNC</command> files because any given
+<command>SYNC</command> file may <emphasis>not</emphasis> be the right
+one. If it's wrong, then the result will be that the call to
+<function> setsyncTracking_offline() </function> will fail, and your
+<application> psql</application> session will <command> ABORT
+</command>, and then run through the remainder of that
+<command>SYNC</command> file looking for a <command>COMMIT</command>
+or <command>ROLLBACK</command> so that it can try to move on to the
+next transaction.</para>
<para> But we <emphasis> know </emphasis> that the entire remainder of
the file will fail! It is futile to go through the parsing effort of
@@ -222,7 +215,8 @@
<itemizedlist>
<listitem><para> Read the first few lines of the file, up to and
-including the <function> setsyncTracking_offline() </function> call.</para></listitem>
+including the <function> setsyncTracking_offline() </function>
+call.</para></listitem>
<listitem><para> Try to apply it that far.</para></listitem>
Index: locking.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/locking.sgml,v
retrieving revision 1.2
retrieving revision 1.3
diff -Ldoc/adminguide/locking.sgml -Ldoc/adminguide/locking.sgml -u -w -r1.2 -r1.3
--- doc/adminguide/locking.sgml
+++ doc/adminguide/locking.sgml
@@ -27,21 +27,22 @@
<para> A momentary table lock must be acquired on the
<quote>origin</quote> node in order to add the trigger that collects
-updates for that table.</para>
+updates for that table. It only needs to be acquired long enough to
+establish the new trigger.</para>
</listitem>
<listitem><para><link linkend="stmtmoveset"> <command> move
set</command> </link></para>
<para> When a set origin is shifted from one node to another, locks
-must be acquired on the tables on both the old origin and the new
-origin in order to change the triggers on the tables.
+must be acquired on each of the tables on both the old origin and the
+new origin in order to change the triggers on the tables.
</para></listitem>
<listitem><para><link linkend="stmtlockset"> <command> lock set
</command> </link> </para>
-<para> This operation expressly requests locks on the tables in a
+<para> This operation expressly requests locks on each of the tables in a
given replication set on the origin node.</para>
</listitem>
@@ -61,7 +62,7 @@
<para> In a sense, this is the least provocative scenario, since,
before the replication set has been populated, it is pretty reasonable
to say that the node is <quote>unusable</quote> and that &slony1;
-could reasonably expect exclusive access to the node. </para>
+could reasonably demand exclusive access to the node. </para>
</listitem>
</itemizedlist>
@@ -116,7 +117,8 @@
the <link linkend="slonyuser"> <command>slony</command> user </link>
will have access to the database. </para> </listitem>
-<listitem><para> Issue a <command>kill -SIGHUP</command> to the &postgres; postmaster.</para>
+<listitem><para> Issue a <command>kill -SIGHUP</command> to the
+&postgres; postmaster.</para>
<para> This will not kill off existing possibly-long-running queries,
but will prevent new ones from coming in. There is an application
@@ -135,7 +137,7 @@
attach to the node. </para>
<para> At that point, it will be safe to proceed with the &slony1;
-operation.</para></listitem>
+operation; there will be no competing processes.</para></listitem>
<listitem><para> Reset <filename>pg_hba.conf</filename> to allow other
users in, and <command>kill -SIGHUP</command> the postmaster to make
Index: slony.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/slony.sgml,v
retrieving revision 1.20
retrieving revision 1.21
diff -Ldoc/adminguide/slony.sgml -Ldoc/adminguide/slony.sgml -u -w -r1.20 -r1.21
--- doc/adminguide/slony.sgml
+++ doc/adminguide/slony.sgml
@@ -37,7 +37,7 @@
<article id="slonyadmin">
<title> Slony-I Administration </title>
<articleinfo>
- <corpauthor>The Slony Global Development Group</corpauthor>
+ <corpauthor>The PostgreSQL Global Development Group</corpauthor>
<author> <firstname>Christopher</firstname> <surname>Browne</surname> </author>
</articleinfo>
&firstdb;
- Previous message: [Slony1-commit] By darcyb: The attached patch implements a suitable build environment
- Next message: [Slony1-commit] By cbbrowne: Further formatting changes.
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
More information about the Slony1-commit mailing list