Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Browse files

Numerous updates to documentation based on Brian A. Seklecki's recent

questions on the mailing list.
Brian A. Seklecki wrote:

>>One of the big things missing from the "Introduction" docs is a more
>>thorough explanation of "How Slony Works". As a DBA or SysAdmin,
>>that's the first question that I desire to have answered by a manual,
>>and serves to help me better understand all future operations and
>>procedures, especially troubleshooting.

Thanks, you're one of the first to do any "detailed criticism" of the

>>For example, in introduction.html, it is stated "namely that Slony-I
>>operates using triggers", but what we should probably be saying is:
>>   "For every table, sequence, or database object that is replicated,
>>Slony is able to replicate changes by installing a trigger that
>>catches updates, inserts, and deletes."
>>Also, "sl_log" isn't mentioned until Chapter/Page 3 and then again in
>>7. However, no mention of the "_${repset}_cluster" schema is made at
>>all prior to that point. It's mentioned in Ch/Pg 5, but the purpose
>>isn't explained. Somewhere prior mention of "sl_log_1*", there should
>>be a paragraph explaining design:
>>   "For every database participating in replication, Slony creates a
>>schema named "_${repset}_cluster" at initialization time to maintain
>>configuration and status data. Most specifically, nodes acting as
>>master/sources maintain a _${repset}_cluster.sl_log_{1,2} table to
>>log/cache of all changes to master which are to be propagated to
>>slaves." (or something to that effect, check me)

That is in the section on defining clusters, now.

>>Also, it's also not explicitly stated anywhere that only Sequences and
>>Tables are replicated.  Although that may seem rudimentary, a it's only
>>briefly touched on.

That is now explicitly mentioned in several places.

>>It should probably be explicitly stated: "A database consists of
>>Casts, Languages, Schemas, Tables, Indexes, Constraints, Sequences,
>>Triggers, Functions, Views, Types, etc.; however Slony only replicates
>>Tables, Indexes, and Sequences. All other objections constitute DDL
>>changes that must be manually replicated by the administrator." (or
>>something to that effect, check me).

I am a little reluctant to try to enumerate *all* types of database
objects. Alan Perlis points out that if you have a procedure with 10
parameters, you probably have missed some :-) . The same is likely true
here. But I have revised the wording about DDL changes a bit to make it
clearer what is and isn't replicated.

>>Another thing to add to the wishlist: Example real-world scenarios
>>DBAs may encountered and recommended procedures to follow.

There is a document called "addthings.sgml" to which I have been adding
such of these scenarios as seem to come along.

Beefing it up with "recipes" for how to do additional things is
certainly fair game.

>>Also, it wouldn't hurt to break out XFig or Dia and add some explanatory
>>diagrams explaining concepts.

I'm not much of a graphical person, which is why the paucity of diagrams...

>>(And yes, I'm will to help write docs!) >:}
  • Loading branch information...
1 parent 685a7b4 commit f630d7e155ec851b7f22d29b507a553ab933e406 Christopher Browne committed
11 doc/adminguide/bestpractices.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: bestpractices.sgml,v 2006-01-10 17:06:09 cbbrowne Exp $ -->
+<!-- $Id: bestpractices.sgml,v 2006-01-17 16:14:43 cbbrowne Exp $ -->
<sect1 id="bestpractices">
<title> &slony1; <quote>Best Practices</quote> </title>
<indexterm><primary>best practices for &slony1; usage</primary></indexterm>
@@ -250,9 +250,9 @@ active are visible in the process environment. (And if there are a
lot of them, they may be a nuisance to read.)</para>
<para> Unfortunately, if you invoke <xref linkend="slon"> from the
-command line, you could <emphasis>forget</emphasis> to include <link
-linkend="logshipping"> log shipping </link> configuration and thereby
-destroy the sequence of logs for a log shipping node. </para>
+command line, you could <emphasis>forget</emphasis> to include
+&logshiplink; configuration and thereby destroy the sequence of logs
+for a log shipping node. </para>
<listitem> <para> Unlike when command line options are used, the
@@ -262,8 +262,7 @@ configuration file, and will not reflect subsequent changes to the
configuration file. </para>
<para> By putting the options in a file, you won't forget including
-any of them, so this is safer for <link linkend="logshipping"> log
-shipping. </link> </para>
+any of them, so this is safer for &logshiplink;. </para>
23 doc/adminguide/cluster.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: cluster.sgml,v 1.10 2005-04-13 21:22:57 cbbrowne Exp $ -->
+<!-- $Id: cluster.sgml,v 2006-01-17 16:14:43 cbbrowne Exp $ -->
<sect1 id="cluster">
<title>Defining &slony1; Clusters</title>
@@ -8,7 +8,16 @@
<para>A &slony1; cluster is the basic grouping of database instances
in which replication takes place. It consists of a set of &postgres;
database instances in which is defined a namespace specific to that
+cluster. For instance, if the cluster is called
+<envar>cbcluster</envar>, then &slony1; will define, at the
+initialization time for each node, a schema called
+<command>_cbcluster</command>, in which it then creates numerous
+tables that store &slony1; configuration and replication state
+information. See <xref linkend="schema"> for more documentation about
+what is stored in that schema. More specifically, the tables <xref
+linkend=""> and <xref linkend=""> log
+changes collected on the origin node as they are replicated to
+subscribers. </para>
<para>Each database instance in which replication is to take place is
identified by a node number.</para>
@@ -22,10 +31,12 @@ driven insane. The node numbers should be chosen to somehow
correspond to the shape of the environment, as opposed to (say) the
order in which nodes were initialized.</para>
-<para>It may be that in version 1.1, nodes will also have a
-<quote>name</quote> attribute, so that they may be given more mnemonic names.
-In that case, the node numbers might remain somewhat cryptic; it will
-be the node name that is used to organize the cluster.</para>
+<para> In &slony1; version 1.1, the <xref linkend="stmtinclude"> and
+<xref linkend="stmtdefine"> statements allow you to create a sort of
+<quote>symbol table</quote> behind the scenes so that <xref
+linkend="slonik"> scripts can use names for nodes rather than cryptic
+numbers. </para>
<!-- Keep this comment at the end of the file
4 doc/adminguide/filelist.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: filelist.sgml,v 2005-11-30 17:41:30 cbbrowne Exp $ -->
+<!-- $Id: filelist.sgml,v 2006-01-17 16:14:43 cbbrowne Exp $ -->
<!entity intro SYSTEM "intro.sgml">
<!entity prerequisites SYSTEM "prerequisites.sgml">
@@ -36,7 +36,7 @@
<!entity notation SYSTEM "notation.sgml">
<!entity problems SYSTEM "problems.sgml">
<!entity slonybook SYSTEM "slony.sgml">
-<!entity logshipping SYSTEM "logshipping.sgml">
+<!entity logshipfile SYSTEM "logshipping.sgml">
<!entity bestpractices SYSTEM "bestpractices.sgml">
<!entity locking SYSTEM "locking.sgml">
<!entity supportedplatforms SYSTEM "supportedplatforms.sgml">
47 doc/adminguide/intro.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: intro.sgml,v 2005-12-09 22:21:54 cbbrowne Exp $ -->
+<!-- $Id: intro.sgml,v 2006-01-17 16:14:43 cbbrowne Exp $ -->
<sect1 id="introduction">
<title>Introduction to &slony1;</title>
<sect2> <title>What &slony1; is</title>
@@ -136,16 +136,37 @@ replication services.</para></sect2>
<para>&slony1; does not automatically propagate schema changes, nor
does it have any ability to replicate large objects. There is a
single common reason for these limitations, namely that &slony1;
-operates using triggers, and neither schema changes nor large object
-operations can raise triggers suitable to tell &slony1; when those
-kinds of changes take place.</para>
-<para>There is a capability for &slony1; to propagate DDL changes if
-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 <link
-linkend="ddlchanges"> caveats.</link></para>
+collects updates using triggers, and neither schema changes nor large
+object operations 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
+some additional <emphasis>fiddling around with triggers</emphasis>.
+On the <quote>origin</quote> for each replicated table, an additional
+trigger is added which runs the stored procedure <xref
+linkend="function.logtrigger">. On each subscriber, tables are
+augmented with a trigger that runs the <xref
+linkend="function.denyaccess"> function; this function prevents
+anything other than the <xref linkend="slon"> process from updating
+data in replicated tables. In addition, any
+<emphasis>other</emphasis> triggers and rules on replicated tables are
+<emphasis>suppressed</emphasis> on the subscribers: This is done by
+pointing them, in the system table, to the primary key index instead
+of to the table itself. This represents something of a
+<quote>corruption</quote> of the data dictionary, and is why you
+should not directly use <application>pg_dump</application> to dump
+schemas on subscribers. </para>
+<para>There is a capability for &slony1; to propagate other kinds of
+database modifications, notably DDL changes, if you submit them as
+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
+linkend="ddlchanges"> caveats.</link> </para>
<para>If you have those sorts of requirements, it may be worth
exploring the use of &postgres; 8.X <acronym>PITR</acronym> (Point In
@@ -174,8 +195,8 @@ it is impossible for one replication system to be all things to all
<para> &slony1; implements a particular model, namely that of
-asynchronous replication, using triggers, where a single
-<quote>origin</quote> may be replicated to multiple
+asynchronous replication, using triggers to collect table updates,
+where a single <quote>origin</quote> may be replicated to multiple
<quote>subscribers</quote> including cascaded subscribers.</para>
<para> There are a number of other replication models which are
5 doc/adminguide/man.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: man.sgml,v 2005-12-09 22:27:47 cbbrowne Exp $ -->
+<!-- $Id: man.sgml,v 2006-01-17 16:14:43 cbbrowne Exp $ -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
<!entity % version SYSTEM "version.sgml">
@@ -9,7 +9,7 @@
<!ENTITY windows "<trademark>Windows</trademark>">
- <!ENTITY logship "log shipping">
+ <!ENTITY logshiplink "log shipping">
<!ENTITY rlocking " locking ">
<!ENTITY rddlchanges "distribution documentation on DDL changes">
<!ENTITY rplainpaths "distribution documentation on plain paths">
@@ -43,6 +43,7 @@
<!ENTITY funsubscribeset "<function>subscribeset(integer,integer,integer,boolean)</function>">
<!ENTITY slnode "<envar>sl_node</envar>">
<!ENTITY slconfirm "<envar>sl_confirm</envar>">
+ <!ENTITY bestpracticelink "Best Practice">
<book id="slony">
19 doc/adminguide/prerequisites.sgml
@@ -230,16 +230,15 @@ branch location that can't be kept secure compromises security for the
cluster as a whole.</para>
<para>New in &slony1; version 1.1 is a feature whereby updates for a
-particular replication set may be serialized via a scheme called <link
-linkend="logshipping">log shipping. </link> The data stored in
-<envar>sl_log_1</envar> and <envar>sl_log_2</envar> is also written
-out to log files on disk. These files may then be transmitted in any
-manner desired, whether via scp, FTP, burning them onto DVD-ROMs and
-mailing them, or, at the frivolous end of the spectrum, by recording
-them on a USB <quote>flash device</quote> and attaching them to birds,
-allowing some equivalent to <ulink
-url=""> transmission of IP
-datagrams on avian carriers - RFC 1149.</ulink> But whatever the
+particular replication set may be serialized via a scheme called
+&logshiplink;. The data stored in <envar>sl_log_1</envar> and
+<envar>sl_log_2</envar> is also written out to log files on disk.
+These files may then be transmitted in any manner desired, whether via
+scp, FTP, burning them onto DVD-ROMs and mailing them, or, at the
+frivolous end of the spectrum, by recording them on a USB <quote>flash
+device</quote> and attaching them to birds, allowing some equivalent
+to <ulink url=""> transmission of
+IP datagrams on avian carriers - RFC 1149.</ulink> But whatever the
transmission mechanism, this allows one way communications such that
subscribers that use log shipping have no need of access to other
&slony1; nodes.</para>
4 doc/adminguide/slon.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: slon.sgml,v 2005-12-09 22:22:00 cbbrowne Exp $ -->
+<!-- $Id: slon.sgml,v 2006-01-17 16:14:43 cbbrowne Exp $ -->
<refentry id="slon">
<refentrytitle id="app-slon-title"><application>slon</application></refentrytitle>
@@ -298,7 +298,7 @@
<envar>archive_dir</envar> indicates a directory in which to
place a sequence of <command>SYNC</command> archive files for
- use in &logship; mode.
+ use in &logshiplink; mode.
8 doc/adminguide/slonik_ref.sgml
@@ -985,8 +985,7 @@ STORE PATH ( SERVER = 1, CLIENT = 2,
<caution><para> <command>TABLE ADD KEY</command> <emphasis>should
not be used</emphasis> if you can possibly avoid it. It is
- emphatically <emphasis>not</emphasis> a <link
- linkend="bestpractices"> Best Practice.</link> </para>
+ emphatically <emphasis>not</emphasis> a &bestpracticelink;. </para>
<para> The absence of a proper primary key should be a big red
flag that the database schema is <emphasis>broken.</emphasis> The
@@ -994,9 +993,8 @@ STORE PATH ( SERVER = 1, CLIENT = 2,
proper primary key, not to have &slony1; <quote>fake</quote> one
- <para>It is <emphasis>not</emphasis> supported in <link
- linkend="logshipping"> log shipping </link>, and will not
- be.</para> </caution>
+ <para>It is <emphasis>not</emphasis> supported in &logshiplink;,
+ and will not be.</para> </caution>
<para> This uses &funtableaddkey;. </para>
7 doc/adminguide/slony.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: slony.sgml,v 2006-01-06 17:05:22 cbbrowne Exp $ -->
+<!-- $Id: slony.sgml,v 2006-01-17 16:14:43 cbbrowne Exp $ -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
<!entity % version SYSTEM "version.sgml">
@@ -10,7 +10,7 @@
<!ENTITY windows "<trademark>Windows</trademark>">
- <!ENTITY logship "<link linkend=logshipping>log shipping</link>">
+ <!ENTITY logshiplink "<link linkend=logshipping>log shipping</link>">
<!ENTITY rlocking "<link linkend=locking> locking </link>">
<!ENTITY rddlchanges "<xref linkend=ddlchanges>">
<!ENTITY fundroplisten "<xref linkend=function.droplisten-integer-integer-integer>">
@@ -39,6 +39,7 @@
<!ENTITY fununinstallnode "<xref linkend=function.uninstallnode>">
<!ENTITY fununlockset "<xref linkend=function.unlockset-integer>">
<!ENTITY fununsubscribeset "<xref linkend=function.unsubscribeset-integer-integer>">
+ <!ENTITY bestpracticelink "<link linkend=bestpractices>Best Practice</link>">
<!ENTITY rmissingoids "<link linkend=missingoids>error messages indicating missing OIDs</link>">
<!ENTITY slnode "<xref>">
<!ENTITY slconfirm "<xref>">
@@ -89,7 +90,7 @@
- &logshipping;
+ &logshipfile;

0 comments on commit f630d7e

Please sign in to comment.
Something went wrong with that request. Please try again.