Wed Dec 22 21:14:25 PST 2004
- Previous message: [Slony1-commit] By cbbrowne: Added commentary on what happens to triggers and rules
- Next message: [Slony1-commit] By cbbrowne: Point to internal Slonik command reference, not the GBorg
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Log Message: ----------- Put in proper <refpurpose> entries for each Slonik command Modified Files: -------------- slony1-engine/doc/adminguide: slonik_ref.sgml (r1.5 -> r1.6) -------------- next part -------------- Index: slonik_ref.sgml =================================================================== RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/slonik_ref.sgml,v retrieving revision 1.5 retrieving revision 1.6 diff -Ldoc/adminguide/slonik_ref.sgml -Ldoc/adminguide/slonik_ref.sgml -u -w -r1.5 -r1.6 --- doc/adminguide/slonik_ref.sgml +++ doc/adminguide/slonik_ref.sgml @@ -1,5 +1,5 @@ -<!-- $Id --> -<article> +<article id="slonikcommands"> + <title>Slonik Command Summary</title> <sect1 id="slonikintro"> <title>Slonik Command Summary</title> <sect2><title>Introduction</title> @@ -8,50 +8,54 @@ <application>Slonik</application> is a command line utility designed specifically to setup and modify configurations of the <productname>Slony-I</productname> replication system. -</para> -</sect2> + </para></sect2> + <sect2 id="outline"> <title>General outline</title> <para> - The <application>slonik</application> commandline utility is supposed to be - used embedded into shell scripts and reads commands from files - or stdin (via here documents for example). Nearly all of the - <emphasis>real</emphasis> configuration work is done by - calling stored procedures after loading the - <productname>Slony-I</productname> support base into a database. You may - find documentation for those procedures in the <ulink - url="schemadoc"><productname>Slony-I</productname> Schema - Documentation</ulink>, as well as in comments associated with - them in the database. + The <application>slonik</application> commandline utility is + supposed to be used embedded into shell scripts and reads + commands from files or stdin (via here documents for + example). Nearly all of the <emphasis>real</emphasis> + configuration work is done by calling stored procedures after + loading the <productname>Slony-I</productname> support base into + a database. You may find documentation for those procedures in + the <ulink url="schemadoc"><productname>Slony-I</productname> + Schema Documentation</ulink>, as well as in comments associated + with them in the database. </para> <para> - <Application>Slonik</Application> was created because: + <application>Slonik</application> was created because: <itemizedlist> - <listitem><para>The stored procedures have special - requirements as to on which particular node in the replication - system they are called,</para></listitem> + <listitem><para>The stored procedures have special requirements + as to on which particular node in the replication system they + are called,</para></listitem> <listitem><para>The lack of named parameters for stored procedures makes it rather difficult to do this from the <application>psql</application> prompt, and</para></listitem> - <listitem><para><application>psql</application>lacks the ability to - maintain multiple connections with open transactions.</para></listitem> + <listitem><para><application>psql</application>lacks the ability + to maintain multiple connections with open + transactions.</para></listitem> </itemizedlist> </para> + <para> + + </para> <sect3><title>Commands</title> <para> The slonik command language is format free. Commands begin with keywords and are terminated with a semicolon. Most commands have a list of parameters, some of which have default values and are therefore optional. The parameters of commands are enclosed in - parentheses. Each option consists of one or more keywords, followed - by an equal sign, followed by a value. Multiple options inside the - parentheses are separated by commas. All keywords are case - insensitive. The language should remind the reader of SQL. + parentheses. Each option consists of one or more keywords, + followed by an equal sign, followed by a value. Multiple options + inside the parentheses are separated by commas. All keywords are + case insensitive. The language should remind the reader of SQL. </para> <para> Option values may be: @@ -65,7 +69,7 @@ <sect3><title>Comments</title> <para> Comments begin at a hash sign (#) and extend to the end of the line. -</para> + </para></sect3> <sect3><title>Command groups</title> <para> Commands can be combined into groups of commands with optional @@ -77,32 +81,31 @@ } [on error { commands; } [on success { commands; } -</programlisting> -</para> -<para> Those commands are grouped together into one transaction per - participating node. -</para> + </programlisting></para> + + <para> Those commands are grouped together into one transaction + per participating node. </para> +<!-- ************************************************************ --></sect3></sect2></sect1></article> -</sect3> -</sect2> -</sect1> <reference id="hdrcmds"> <title>Slonik Preamble Commands</title> <partintro> <para> - The following commands must appear as a <quote>preamble</quote> at the very - top of every <application>slonik</application> command script. They do not cause any - direct action on any of the nodes in the replication system, - but affect the execution of the entire script. + The following commands must appear as a + <quote>preamble</quote> at the very top of every + <application>slonik</application> command script. They do not + cause any direct action on any of the nodes in the replication + system, but affect the execution of the entire script. </para> </partintro> - + <!-- **************************************** --> <refentry id ="clustername"><refmeta><refentrytitle>CLUSTER NAME</refentrytitle></refmeta> <refnamediv><refname>CLUSTER NAME</refname> <refpurpose> preamble - identifying <productname>Slony-I</productname> cluster</refpurpose> + </refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>CLUSTER NAME = </command> @@ -112,23 +115,23 @@ <refsect1> <title>Description</title> <para> - Must be the very first command in every <application>slonik</application> script. Defines - the namespace in which all <productname>Slony-I</productname> specific functions, - procedures, tables and sequences are defined. The namespace - name is built by prefixing the given string literal with an - underscore. This namespace will be identical in all databases - that participate in the same replication group. + Must be the very first command in every + <application>slonik</application> script. Defines the namespace + in which all <productname>Slony-I</productname> specific + functions, procedures, tables and sequences are defined. The + namespace name is built by prefixing the given string literal + with an underscore. This namespace will be identical in all + databases that participate in the same replication group. </para> <para> - No user objects are supposed to live in this - namespace and the namespace is not allowed to exist - prior to adding a database to the replication - system. Thus, if you add a new node using <command> - pg_dump -s </command> on a database that is already in - the cluster of replicated databases, you will need - to drop the namespace via the SQL command <command> DROP - SCHEMA _testcluster CASCADE; </command>. + No user objects are supposed to live in this namespace and the + namespace is not allowed to exist prior to adding a database to + the replication system. Thus, if you add a new node using + <command> pg_dump -s </command> on a database that is already in + the cluster of replicated databases, you will need to drop the + namespace via the SQL command <command> DROP SCHEMA _testcluster + CASCADE; </command>. </para> </refsect1> <refsect1><title>Example</title> @@ -145,8 +148,8 @@ <refnamediv><refname>ADMIN CONNINFO</refname> -<refpurpose> preamble - identifying <productname/PostgreSQL/ database </refpurpose> - + <refpurpose> preamble - identifying <productname>PostgreSQL</productname> database </refpurpose> + </refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>NODE ival ADMIN CONNINFO = 'DSN';</command> @@ -157,38 +160,39 @@ <refsect1> <title>Description</title> <para> - Describes how the <application>slonik</application> utility can reach a nodes database in - the cluster from where it is run (likely the DBA's - workstation). The conninfo string is the string agrument given - to the <function>PQconnectdb()</function> libpq function. The user used to connect - must be the special replication superuser, as some of the - actions performed later may include operations that are - strictly reserved for database superusers by PostgreSQL. + Describes how the <application>slonik</application> utility can + reach a nodes database in the cluster from where it is run + (likely the DBA's workstation). The conninfo string is the string + agrument given to the <function>PQconnectdb()</function> libpq + function. The user used to connect must be the special + replication superuser, as some of the actions performed later may + include operations that are strictly reserved for database + superusers by PostgreSQL. + </para> + + <para> + The <application>slonik</application> utility will not try to + connect to the databases unless some subsequent command requires + the connection. </para> <para> - The <application>slonik</application> utility will not try to connect to the databases - unless some subsequent command requires the connection. - </Para> - -<para> - Note: As mentioned in the original documents, <productname>Slony-I</productname> is designed as an - enterprise replication system for data centers. It has been - assumed throughout the entire development that the database - servers and administrative workstations involved in - replication and/or setup and configuration activities can use - simple authentication schemes like <quote>trust</quote>. - Alternatively, libpq can read passwords from <filename> - .pgpass </filename>. + Note: As mentioned in the original documents, + <productname>Slony-I</productname> is designed as an enterprise + replication system for data centers. It has been assumed + throughout the entire development that the database servers and + administrative workstations involved in replication and/or setup + and configuration activities can use simple authentication + schemes like <quote>trust</quote>. Alternatively, libpq can read + passwords from <filename> .pgpass </filename>. </para> <para> Note: If you need to change the DSN information for a node, as - would happen if the IP address for a host were to change, you - may submit the new information using this command, and that - configuration will be propagated. Existing <application/> - slon </application> - processes will need to be restarted in order to become aware - of the configuration change. + would happen if the IP address for a host were to change, you may + submit the new information using this command, and that + configuration will be propagated. Existing <application>> slon + </application> processes will need to be restarted in order to + become aware of the configuration change. </para> </Refsect1> <Refsect1><Title>Example</Title> @@ -197,12 +201,9 @@ </Programlisting> </Refsect1> </Refentry> - - </reference> <!-- ************************************************************ --> - <!-- **************************************** --> <reference id="cmds"> <title>Configuration and Action commmands</title> @@ -212,8 +213,8 @@ <refnamediv><refname>ECHO</refname> -<refpurpose> Generic debugging tool </refpurpose> - + <refpurpose> Generic output tool </refpurpose> + </refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>echo </command> @@ -239,8 +240,8 @@ <refnamediv><refname>EXIT</refname> -<refpurpose> Generic debugging tool </refpurpose> - + <refpurpose> Terminate Slonik script with signal </refpurpose> + </refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>exit</command> @@ -262,15 +263,14 @@ </Programlisting> </Refsect1> </Refentry> + <refentry id ="stmtinitcluster"> <refmeta> <refentrytitle>INIT CLUSTER</refentrytitle> </refmeta> - <refnamediv> <refname>INIT CLUSTER</refname> - - <refpurpose>Initialize <productname>Slony-I</productname> cluster</refpurpose> + <refpurpose>Initialize <productname>Slony-I</productname> cluster</refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>INIT CLUSTER</command> @@ -279,11 +279,11 @@ </cmdsynopsis> </refsynopsisdiv> <refsect1> - <title>Description</title> - <para> Initialize the first node in a new <productname>Slony-I</productname> - replication cluster. The initialization process consists of creating - the cluster namespace, loading all the base tables, functions, - procedures and initializing the node. + <title>Description</title> <para> Initialize the first node in a + new <productname>Slony-I</productname> replication cluster. The + initialization process consists of creating the cluster namespace, + loading all the base tables, functions, procedures and + initializing the node. <variablelist> <varlistentry><term><literal>ID</literal></term> @@ -298,32 +298,33 @@ </para> <para> For this process to work, the SQL scripts of the - <productname>Slony-I</productname> system must be installed on the DBA workstation - (the computer currently executing the <application>slonik</application> utility), - while on the system where the node database is running the shared - objects of the <productname>Slony-I</productname> system must be installed in the - PostgreSQL library directory. Also the procedural language PL/pgSQL is - assumed to already be installed in the target database.</para> - </Refsect1> - <Refsect1> - <Title>Example</Title> - <Programlisting> + <productname>Slony-I</productname> system must be installed on the + DBA workstation (the computer currently executing the + <application>slonik</application> utility), while on the system + where the node database is running the shared objects of the + <productname>Slony-I</productname> system must be installed in the + PostgreSQL library directory. Also the procedural language + PL/pgSQL is assumed to already be installed in the target + database.</para> + </refsect1> + <refsect1> + <title>Example</title> + <programlisting> INIT CLUSTER ( ID = 1, COMMENT = 'Node 1' ); - </Programlisting> - </Refsect1> - </Refentry> + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> <refentry id ="stmtstorenode"><refmeta><refentrytitle>STORE NODE</refentrytitle> </refmeta> <refnamediv><refname>STORE NODE</refname> - - <refpurpose> Initialize <productname>Slony-I</productname> node </refpurpose> + </refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>STORE NODE (options);</command> @@ -336,14 +337,15 @@ existing cluster.</para> <para> The initialization process consists of creating the cluster -namespace in the new node (the database itself must already exist), -loading all the base tables, functions, procedures and initializing -the node. The existing configuration of the rest of the cluster is -copied from the <quote>event node</quote>. + namespace in the new node (the database itself must already + exist), loading all the base tables, functions, procedures and + initializing the node. The existing configuration of the rest of + the cluster is copied from the <quote>event node</quote>. <variablelist> <varlistentry><term><literal>ID = ival</literal></term> - <listitem><para> The unique, numeric ID number of the new node.</para></listitem> + <listitem><para> The unique, numeric ID number of the new + node.</para></listitem> </varlistentry> <varlistentry><term><literal> COMMENT = 'description' </literal></term> @@ -352,10 +354,10 @@ <varlistentry><term><literal> SPOOLNODE = boolean </literal></term> - <listitem><para>Specifies that the new node is a virtual spool node - for file archiving of replication log. If true <application>slonik</application> - will not attempt to initialize a database with the replication - schema.</para></listitem> + <listitem><para>Specifies that the new node is a virtual spool + node for file archiving of replication log. If true + <application>slonik</application> will not attempt to initialize a database + with the replication schema.</para></listitem> </varlistentry> <varlistentry><term><literal> EVENT NODE = ival </literal></term> @@ -380,7 +382,7 @@ <refnamediv><refname>DROP NODE</refname> -<refpurpose> Decommission <productname>Slony-I</productname> node </refpurpose> + <refpurpose> Decommission <productname>Slony-I</productname> node </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>DROP NODE (options);</command> @@ -390,10 +392,11 @@ <title>Description</title> <para> - Drop a node. This command removes the specified node entirely from - the replication systems configuration. If the replication daemon - is still running on that node (and processing events), it will - attempt to uninstall the replication system and terminate itself. + Drop a node. This command removes the specified node entirely + from the replication systems configuration. If the replication + daemon is still running on that node (and processing events), it + will attempt to uninstall the replication system and terminate + itself. <variablelist> <varlistentry><term><literal> ID = ival </literal></term> @@ -404,20 +407,20 @@ </varlistentry> </variablelist> </para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> DROP NODE ( ID = 2 ); -</Programlisting> -</Refsect1> -</Refentry> + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> <refentry id ="stmtuninstallnode"><refmeta><refentrytitle>UNINSTALL NODE</refentrytitle> </refmeta> <refnamediv><refname>UNINSTALL NODE</refname> -<refpurpose> Decommission <productname>Slony-I</productname> node </refpurpose> + <refpurpose> Decommission <productname>Slony-I</productname> node </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>UNINSTALL NODE (options);</command> @@ -426,12 +429,12 @@ <refsect1> <title>Description</title> -<para> - Restores all tables to the unlocked state, with all original - user triggers, constraints and rules, eventually added <productname>Slony-I</productname> - specific serial key columns dropped and the <productname>Slony-I</productname> schema - dropped. The node becomes a standalone database. The data is - left untouched. + <para> Restores all tables to the unlocked state, with all + original user triggers, constraints and rules, eventually added + <productname>Slony-I</productname> specific serial key columns + dropped and the <productname>Slony-I</productname> schema + dropped. The node becomes a standalone database. The data is left + untouched. <variablelist> <varlistentry><term><literal> ID = ival </literal></term> @@ -439,13 +442,13 @@ </varlistentry> </variablelist> </para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> UNINSTALL NODE ( ID = 2 ); -</Programlisting> -</Refsect1> -</Refentry> + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> @@ -453,7 +456,7 @@ <refnamediv><refname>RESTART NODE</refname> -<refpurpose> Restart <productname>Slony-I</productname> node </refpurpose> + <refpurpose> Restart <productname>Slony-I</productname> node </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -464,10 +467,11 @@ <title>Description</title> <para> Causes an eventually running replication daemon on the -specified node to shutdown and restart itself. Theoretically this -command should be obsolete. In practice, TCP timeouts can delay -critical configuration changes to actually happen in the case where a -former forwarding node failed and needs to be bypassed by subscribers. + specified node to shutdown and restart itself. Theoretically, + this command should be obsolete. In practice, TCP timeouts can + delay critical configuration changes to actually happen in the + case where a former forwarding node failed and needs to be + bypassed by subscribers. <variablelist> <varlistentry><term><literal> ID = ival </literal></term> @@ -475,22 +479,23 @@ </varlistentry> </variablelist> </para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> RESTART NODE ( ID = 2 ); -</Programlisting> -</Refsect1> -</Refentry> + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> -<refentry id ="stmtstorepath"><refmeta><refentrytitle>STORE PATH</refentrytitle> </refmeta> + <refentry id="stmtstorepath"><refmeta><refentrytitle>STORE + PATH</refentrytitle> </refmeta> <refnamediv><refname>STORE PATH</refname> -<refpurpose> Configure <productname>Slony-I</productname> node </refpurpose> + <refpurpose> Configure <productname>Slony-I</productname> node connection </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -500,26 +505,27 @@ <refsect1> <title>Description</title> -<para> Configures how the replication daemon of one node connects to -the database of another node. If the replication system is supposed to -use a special backbone network segment, this is the place to user the -special IP addresses or hostnames. An existing configuration can be -overwritten.</para> - -<para> The conninfo string must contain all information to connect to the - database as the replication superuser. The names <quote>server</quote> or - <quote>client</quote> have nothing to do with the particular role of a node - within the cluster configuration. It should be simply viewed as - the <quote>server</quote> has the message or data that the <quote>client - is supposed to get</quote>. For a simple 2 node setup, paths into both - directions must be configured. -</para> -<para> - It does not do any harm to configure path information from every - node to every other node (full cross product). The connections - are not established unless they are required to actually transfer - events or confirmations because of <emphasis>listen</emphasis> entries or data - because of <emphasis>subscriptions</emphasis>. + <para> Configures how the replication daemon of one node connects + to the database of another node. If the replication system is + supposed to use a special backbone network segment, this is the + place to user the special IP addresses or hostnames. An existing + configuration can be overwritten.</para> + + <para> The conninfo string must contain all information to connect + to the database as the replication superuser. The names + <quote>server</quote> or <quote>client</quote> have nothing to do + with the particular role of a node within the cluster + configuration. It should be simply viewed as <quote>the + server</quote> has the message or data that <quote>the client is + supposed to get.</quote> For a simple 2 node setup, paths into + both directions must be configured. + </para> + <para> It does not do any harm to configure path information from + every node to every other node (full cross product). The + connections are not established unless they are required to + actually transfer events or confirmations because of + <emphasis>listen</emphasis> entries or data because of + <emphasis>subscriptions</emphasis>. <variablelist> <varlistentry><term><literal> SERVER = ival </literal></term> @@ -538,15 +544,15 @@ </varlistentry> </variablelist> </para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> STORE PATH ( SERVER = 1, CLIENT = 2, CONNINFO = 'dbname=testdb host=server1 user=slony' ); -</Programlisting> -</Refsect1> -</Refentry> + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> @@ -555,7 +561,7 @@ <refnamediv><refname>DROP PATH</refname> -<refpurpose> Configure <productname>Slony-I</productname> node </refpurpose> + <refpurpose> Delete <productname>Slony-I</productname> connection information </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -582,17 +588,17 @@ <listitem><para> The ID of the node used to create the configuration event that tells all existing nodes about dropping the path. Defaults to the <quote>client</quote>, if omitted. - </para> + </para></listitem> </varlistentry> </variablelist> </para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> DROP PATH ( SERVER = 1, CLIENT = 2 ); -</Programlisting> -</Refsect1> -</Refentry> + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> @@ -601,7 +607,8 @@ <refnamediv><refname>STORE LISTEN</refname> -<refpurpose> Configure <productname>Slony-I</productname> node </refpurpose> + <refpurpose> Configure <productname>Slony-I</productname> node to + indicate where to listen for events </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -612,24 +619,22 @@ <title>Description</title> <para> A <quote>listen</quote> entry causes a node (receiver) to query an -event provider for events that originate from a specific node, as well -as confirmations from every existing node. It requires a <quote>path</quote> -to exist so that the receiver (as client) can connect to the provider -(as server). - -<para> - Every node in the system must listen for events from every - other node in the system. As a general rule of thumb, a - subscriber (see <link linkend="stmtsubscribeset">SUBSCRIBE - SET</link>) should listen for events of the set's origin on - the same provider, where it receives the data from. In turn, - the origin of the data set should listen for events from the - origin in the opposite direction. A node can listen for events - from one and the same origin on different providers at the - same time. However, to process <command>SYNC</command> events from that - origin, all data providers must have the same or higher sync - status, so this will not result in any faster replication - behaviour. + event provider for events that originate from a specific node, as + well as confirmations from every existing node. It requires a + <quote>path</quote> to exist so that the receiver (as client) can connect + to the provider (as server).</para> + + <para> Every node in the system must listen for events from every + other node in the system. As a general rule of thumb, a subscriber + (see <link linkend="stmtsubscribeset">SUBSCRIBE SET</link>) should + listen for events of the set's origin on the same provider, where + it receives the data from. In turn, the origin of the data set + should listen for events from the origin in the opposite + direction. A node can listen for events from one and the same + origin on different providers at the same time. However, to + process <command>SYNC</command> events from that origin, all data + providers must have the same or higher sync status, so this will + not result in any faster replication behaviour. </para> <variablelist> @@ -637,7 +642,9 @@ <listitem><para> Node ID of the event origin the receiver is listening for.</para></listitem> </varlistentry> <varlistentry><term><literal> PROVIDER = ival </literal></term> - <listitem><para> Node ID of the node from which the receiver gets events that come from the origin. If not specified, default is the origin.</para></listitem> + <listitem><para> Node ID of the node from which the receiver gets + events that come from the origin. If not specified, default is + the origin.</para></listitem> </varlistentry> <varlistentry><term><literal> RECEIVER = ival </literal></term> @@ -645,24 +652,21 @@ </varlistentry> </variablelist> -<para> For more details, see the section on <link -linkend="listenpaths"> Slony-I Listen Paths. </link> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + <para> For more details, see the section on <link linkend="listenpaths"> Slony-I Listen Paths. </link></para> + </refsect1> + <refsect1><title>Example</title> + <programlisting> STORE LISTEN ( ORIGIN = 1, RECEIVER = 2, PROVIDER = 3 ); -</Programlisting> -</Refsect1> -</Refentry> - - -<!-- **************************************** --> - + </programlisting> + </refsect1> + </refentry> <refentry id ="stmtdroplisten"><refmeta><refentrytitle>DROP LISTEN</refentrytitle> </refmeta> <refnamediv><refname>DROP LISTEN</refname> -<refpurpose> Configure <productname>Slony-I</productname> node </refpurpose> + <refpurpose> Eliminate configuration indicating how + <productname>Slony-I</productname> node listens for events + </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -679,7 +683,9 @@ <listitem><para> Node ID of the event origin the receiver is listening for.</para></listitem> </varlistentry> <varlistentry><term><literal> PROVIDER = ival </literal></term> - <listitem><para> Node ID of the node from which the receiver gets events that come from the origin. If not specified, default is the origin.</para></listitem> + <listitem><para> Node ID of the node from which the receiver gets + events that come from the origin. If not specified, default is + the origin.</para></listitem> </varlistentry> <varlistentry><term><literal> RECEIVER = ival </literal></term> @@ -687,13 +693,13 @@ </varlistentry> </variablelist> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> DROP LISTEN ( ORIGIN = 1, RECEIVER = 2, PROVIDER = 3 ); -</Programlisting> -</Refsect1> -</Refentry> + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> @@ -702,7 +708,9 @@ <refnamediv><refname>TABLE ADD KEY</refname> -<refpurpose> Configure <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Add primary key for use by + <productname>Slony-I</productname> for a table with no suitable + key </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -713,11 +721,11 @@ <title>Description</title> <para> - In the <productname>Slony-I</productname> replication system, every replicated table is - required to have at least one <command>UNIQUE</command> constraint - whose columns are declared <command>NOT NULL.</command> Any - primary key satisfies this - requirement. + In the <productname>Slony-I</productname> replication system, + every replicated table is required to have at least one + <command>UNIQUE</command> constraint whose columns are + declared <command>NOT NULL.</command> Any primary key + satisfies this requirement. </para> <para> As a last resort, this command can be used to add such an @@ -727,7 +735,6 @@ attribute by other means.</emphasis> </para> - <variablelist> <varlistentry><term><literal> NODE ID = ival </literal></term> <listitem><para> Node ID of the set origin where the table will be @@ -742,14 +749,14 @@ </varlistentry> </variablelist> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> TABLE ADD KEY ( NODE ID = 1, FULLY QUALIFIED NAME = 'public.history' ); -</Programlisting> -</Refsect1> -</Refentry> + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> @@ -758,7 +765,8 @@ <refnamediv><refname>CREATE SET</refname> -<refpurpose> Configure <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Create <productname>Slony-I</productname> replication + set </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -769,16 +777,16 @@ <title>Description</title> <para> - In the <productname>Slony-I</productname> replication system, replicated tables are - organized in sets. As a general rule of thumb, a set should - contain all the tables of one application, that have - relationships. In a well designed application, this is equal - to all the tables in one schema. + In the <productname>Slony-I</productname> replication system, + replicated tables are organized in sets. As a general rule of + thumb, a set should contain all the tables of one application, + that have relationships. In a well designed application, this is + equal to all the tables in one schema. </para> <para> The smallest unit one node can subscribe for replication from another node is a set. A set always has an origin. In - classical replication terms, that would be the <quote>master</quote>. + classical replication terms, that would be the <quote>master.</quote> Since in <productname>Slony-I</productname> a node can be the <quote>master</quote> over one set, while receiving replication data in the <quote>slave</quote> role for another at the same time, this terminology may easily become @@ -799,15 +807,15 @@ </varlistentry> </variablelist> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> CREATE SET ( ID = 1, ORIGIN = 1, COMMENT = 'Tables for ticketing system' ); -</Programlisting> -</Refsect1> -</Refentry> + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> @@ -816,7 +824,8 @@ <refnamediv><refname>DROP SET</refname> -<refpurpose> Configure <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Discard <productname>Slony-I</productname> + replication set </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -827,9 +836,10 @@ <title>Description</title> <para> - Drop a set of tables from the <productname>Slony-I</productname> configuration. This - automatically unsubscribes all nodes from the set and restores - the original triggers and rules on all subscribers. + Drop a set of tables from the <productname>Slony-I</productname> + configuration. This automatically unsubscribes all nodes from the + set and restores the original triggers and rules on all + subscribers. </para> <variablelist> @@ -841,23 +851,24 @@ </varlistentry> </variablelist> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> +</refsect1> + <refsect1><title>Example</title> + <programlisting> DROP SET ( ID = 5, ORIGIN = 2 ); -</Programlisting> -</Refsect1> -</Refentry> - + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> -<refentry id ="stmtmergeset"><refmeta><refentrytitle>MERGE SET</refentrytitle> </refmeta> + <refentry id="stmtmergeset"><refmeta><refentrytitle>MERGE + SET</refentrytitle> </refmeta> <refnamediv><refname>MERGE SET</refname> -<refpurpose> Reconfigure <productname>Slony-I</productname> sets </refpurpose> + <refpurpose> Merge <productname>Slony-I</productname> replication + sets together </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -867,13 +878,12 @@ <refsect1> <title>Description</title> -<para> - Merge a set of tables and sequences into another one. This - function is a workaround for the problem that it is not - possible to add tables/sequences to already-subscribed - sets. One may create a temporary set, add the new objects to - that, subscribe all nodes currently subscribed to the other - set to this new one, and then merge the two together. + <para> Merge a set of tables and sequences into another one. This + function is a workaround for the problem that it is not possible + to add tables/sequences to already-subscribed sets. One may create + a temporary set, add the new objects to that, subscribe all nodes + currently subscribed to the other set to this new one, and then + merge the two together. </para> <para> This request will fail if the two sets do not have @@ -884,23 +894,22 @@ <listitem><para> Unique ID of the set to contain the union of the two separate sets.</para></listitem> </varlistentry> <varlistentry><term><literal> ADD ID = ival </literal></term> - <listitem><para> Unique ID of the set whose objects should be transferred. </para> + <listitem><para> Unique ID of the set whose objects should be transferred. </para></listitem> </varlistentry> <varlistentry><term><literal> ORIGIN = ival </literal></term> - <listitem><para> Current origin node for both sets. </para> + <listitem><para> Current origin node for both sets. </para></listitem> </varlistentry> </variablelist> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> MERGE SET ( ID = 2, ADD ID = 9999, ORIGIN = 1 ); -</Programlisting> -</Refsect1> -</Refentry> - + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> @@ -908,7 +917,8 @@ <refnamediv><refname>SET ADD TABLE</refname> -<refpurpose> Configure <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Add a table to a <productname>Slony-I</productname> + replication set </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -918,54 +928,55 @@ <refsect1> <title>Description</title> -<para> - Add an existing user table to a replication set. The set + <para> Add an existing user table to a replication set. The set cannot currently be subscribed by any other node - that functionality is supported by the <command><link linkend="stmtmergeset"> MERGE SET</link> </command> command. <variablelist> <varlistentry><term><literal> SET ID = ival </literal></term> - <listitem><para> ID of the set to which the table is to be added. </para> + <listitem><para> ID of the set to which the table is to be added. </para></listitem> </varlistentry> <varlistentry><term><literal> ORIGIN = ival </literal></term> <listitem><para> Origin node for the set. A future version of <application>slonik</application> - might figure out this information by itself.</para> + might figure out this information by itself.</para></listitem> </varlistentry> <varlistentry><term><literal> ID = ival </literal></term> - <listitem><para> Unique ID of the table. These ID's are not only - used to uniquely identify the individual table within the - replication system. The numeric value of this ID also determines the - order in which the tables are locked in a <link + <listitem><para> Unique ID of the table. These ID's are not + only used to uniquely identify the individual table within the + replication system. The numeric value of this ID also + determines the order in which the tables are locked in a <link linkend="stmtlockset">LOCK SET</link> command for example. So - these numbers should represent any applicable table hierarchy to - make sure the <application>slonik</application> command scripts do not deadlock - at any critical moment. + these numbers should represent any applicable table hierarchy + to make sure the <application>slonik</application> command + scripts do not deadlock at any critical + moment.</para></listitem> </varlistentry> <varlistentry><term><literal> FULLY QUALIFIED NAME = 'string' </literal></term> <listitem><para> The full table name as described in - <link linkend="stmttableaddkey">TABLE ADD KEY</link>.</para> + <link linkend="stmttableaddkey">TABLE ADD KEY</link>.</para></listitem> </varlistentry> - <varlistentry><term><literal> KEY = { 'string' | SERIAL } </literal></term> - <listitem><para> - <emphasis>(Optional)</emphasis> - The index name that covers the unique and not null column set - to be used as the row identifier for replication purposes. Or the - keyword SERIAL to use the special column added with a previous - <link linkend="stmttableaddkey">TABLE ADD KEY</link> command. Default - is to use the table's primary key. The index name is <emphasis> not </emphasis> - fully qualified; you must omit the namespace. + <varlistentry><term><literal> KEY = { 'string' | SERIAL } + </literal></term> <listitem><para> + <emphasis>(Optional)</emphasis> The index name that covers the + unique and not null column set to be used as the row identifier + for replication purposes. Or the keyword SERIAL to use the + special column added with a previous <link + linkend="stmttableaddkey">TABLE ADD KEY</link> command. Default + is to use the table's primary key. The index name is <emphasis> + not </emphasis> fully qualified; you must omit the + namespace.</para></listitem> </varlistentry> <varlistentry><term><literal> COMMENT = 'string' </literal></term> - <listitem><para> A descriptive text added to the table entry. </para> + <listitem><para> A descriptive text added to the table entry. </para></listitem> </varlistentry> </variablelist> </para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> SET ADD TABLE ( SET ID = 1, ORIGIN = 1, @@ -973,10 +984,9 @@ FULLY QUALIFIED NAME = 'public.tracker_ticket', COMMENT = 'Support ticket' ); -</Programlisting> -</Refsect1> -</Refentry> - + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> @@ -984,7 +994,9 @@ <refnamediv><refname>SET ADD SEQUENCE</refname> -<refpurpose> Configure <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Add a sequence to a + <productname>Slony-I</productname> replication set + </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -1002,29 +1014,35 @@ <variablelist> <varlistentry><term><literal> SET ID = ival </literal></term> - <listitem><para> ID of the set to which the sequence is to be added. </para> + <listitem><para> ID of the set to which the sequence is to be added. + </para></listitem> </varlistentry> <varlistentry><term><literal> ORIGIN = ival </literal></term> <listitem><para> Origin node for the set. A future version of <application>slonik</application> - might figure out this information by itself.</para> + might figure out this information by itself.</para></listitem> </varlistentry> <varlistentry><term><literal> ID = ival </literal></term> - <listitem><para> Unique ID of the sequence. <note><para> Note that this ID needs to be unique <emphasis>across sequences</emphasis> throughout the cluster; the numbering of tables is separate, so you might have a table with ID 20 and a sequence with ID 20, and they would be recognized as separate. </note> + <listitem><para> Unique ID of the sequence. <note><para> Note + that this ID needs to be unique <emphasis>across + sequences</emphasis> throughout the cluster; the numbering of + tables is separate, so you might have a table with ID 20 and a + sequence with ID 20, and they would be recognized as + separate.</para> </note></para></listitem> </varlistentry> <varlistentry><term><literal> FULLY QUALIFIED NAME = 'string' </literal></term> <listitem><para> The full sequence name as described in - <link linkend="stmttableaddkey">TABLE ADD KEY</link>.</para> + <link linkend="stmttableaddkey">TABLE ADD KEY</link>.</para></listitem> </varlistentry> <varlistentry><term><literal> COMMENT = 'string' </literal></term> - <listitem><para> A descriptive text added to the sequence entry. </para> + <listitem><para> A descriptive text added to the sequence entry. </para></listitem> </varlistentry> </variablelist> </para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> SET ADD SEQUENCE ( SET ID = 1, ORIGIN = 1, @@ -1032,10 +1050,9 @@ FULLY QUALIFIED NAME = 'public.tracker_ticket_id_seq', COMMENT = 'Support ticket ID sequence' ); -</Programlisting> -</Refsect1> -</Refentry> - + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> @@ -1043,7 +1060,9 @@ <refnamediv><refname>SET DROP TABLE</refname> -<refpurpose> Configure <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Remove a table from a + <productname>Slony-I</productname> replication set + </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -1058,33 +1077,29 @@ </para> <para> Note that this action will <emphasis> not </emphasis> drop a candidate - primary key created using <link - linkend="stmttableaddkey"> <command> TABLE ADD KEY + primary key created using <link linkend="stmttableaddkey"> <command> TABLE ADD KEY </command></link>. <variablelist> <varlistentry><term><literal> ORIGIN = ival </literal></term> <listitem><para> Origin node for the set. A future version of <application>slonik</application> - might figure out this information by itself.</para> + might figure out this information by itself.</para></listitem> </varlistentry> <varlistentry><term><literal> ID = ival </literal></term> - <listitem><para> Unique ID of the table. + <listitem><para> Unique ID of the table.</para></listitem></varlistentry> </variablelist> </para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> SET DROP TABLE ( ORIGIN = 1, ID = 20, ); -</Programlisting> -</Refsect1> -</Refentry> - -<!-- **************************************** --> - + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> @@ -1092,7 +1107,9 @@ <refnamediv><refname>SET DROP SEQUENCE</refname> -<refpurpose> Configure <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Remove a sequence from a + <productname>Slony-I</productname> replication set + </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -1107,33 +1124,36 @@ <variablelist> <varlistentry><term><literal> ORIGIN = ival </literal></term> <listitem><para> Origin node for the set. A future version of <application>slonik</application> - might figure out this information by itself.</para> + might figure out this information by itself.</para></listitem> </varlistentry> <varlistentry><term><literal> ID = ival </literal></term> - <listitem><para> Unique ID of the sequence. + <listitem><para> Unique ID of the sequence.</para></listitem> </varlistentry> </variablelist> </para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> +<refsect1><title>Example</title> + <programlisting> SET DROP SEQUENCE ( ORIGIN = 1, ID = 20, ); -</Programlisting> -</Refsect1> -</Refentry> +</programlisting> + </refsect1> + </refentry> <!-- **************************************** --> -<refentry id ="stmtsetmovetable"><refmeta><refentrytitle>SET MOVE TABLE</refentrytitle> </refmeta> + <refentry id="stmtsetmovetable"><refmeta><refentrytitle>SET MOVE + TABLE</refentrytitle> </refmeta> <refnamediv><refname>SET MOVE TABLE</refname> -<refpurpose> Reconfigure <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Move a table from one + <productname>Slony-I</productname> replication set to another + </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -1147,37 +1167,37 @@ Change the set a table belongs to. The current set and the new set must origin on the same node and subscribed by the same nodes. <caution><para> Due to the way subscribing to new sets - works make absolutely sure that the subscription of all nodes - to the sets is completely processed before moving - tables. Moving a table too early to a new set causes the - subscriber to try and add the table already during the - subscription process, which fails with a duplicate key error - and breaks replication.</para></caution> + works make absolutely sure that the subscription of all nodes to + the sets is completely processed before moving tables. Moving a + table too early to a new set causes the subscriber to try and add + the table already during the subscription process, which fails + with a duplicate key error and breaks + replication.</para></caution> <variablelist> <varlistentry><term><literal> ORIGIN = ival </literal></term> <listitem><para> Current origin of the set. A future version of <application>slonik</application> - might figure out this information by itself.</para> + might figure out this information by itself.</para></listitem> </varlistentry> <varlistentry><term><literal> ID = ival </literal></term> - <listitem><para> Unique ID of the table. + <listitem><para> Unique ID of the table.</para></listitem></varlistentry> <varlistentry><term><literal> NEW SET = ival </literal></term> - <listitem><para> Unique ID of the set to which the table should be added. + <listitem><para> Unique ID of the set to which the table should be added.</para></listitem></varlistentry> </variablelist> </para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> SET MOVE TABLE ( ORIGIN = 1, ID = 20, NEW SET = 3 ); -</Programlisting> -</Refsect1> -</Refentry> + </programlisting> + </refsect1> +</refentry> <!-- **************************************** --> @@ -1186,7 +1206,9 @@ <refnamediv><refname>SET MOVE SEQUENCE</refname> -<refpurpose> Reconfigure <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Move a sequence from one + <productname>Slony-I</productname> replication set to another + </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -1197,11 +1219,11 @@ <title>Description</title> <para> - Change the set a sequence belongs to. The current set and the new set - must originate on the same node and subscribed by the same + Change the set a sequence belongs to. The current set and the new + set must originate on the same node and subscribed by the same nodes. - <caution><Para> Due to the way subscribing to new sets works make + <caution><para> Due to the way subscribing to new sets works make absolutely sure that the subscription of all nodes to the sets is completely processed before moving sequences. Moving a sequence too early to a new set causes the subscriber to try and add the sequence @@ -1211,31 +1233,31 @@ <variablelist> <varlistentry><term><literal> ORIGIN = ival </literal></term> <listitem><para> Origin node for the set. A future version of <application>slonik</application> - might figure out this information by itself.</para> + might figure out this information by itself.</para></listitem> </varlistentry> <varlistentry><term><literal> ID = ival </literal></term> - <listitem><para> Unique ID of the sequence. + <listitem><para> Unique ID of the sequence.</para></listitem> </varlistentry> <varlistentry><term><literal> NEW SET = ival </literal></term> - <listitem><para> Unique ID of the set to which the sequence should be moved. + <listitem><para> Unique ID of the set to which the sequence should be moved.</para></listitem> </varlistentry> </variablelist> </para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> SET MOVE SEQUENCE ( ORIGIN = 1, ID = 20, NEW SET = 3 ); -</Programlisting> -</Refsect1> -</Refentry> + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> @@ -1244,7 +1266,9 @@ <refnamediv><refname>STORE TRIGGER</refname> -<refpurpose> Configure <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Indicate that a trigger should not be disabled by + <productname>Slony-I</productname> on a subscriber node + </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -1261,35 +1285,34 @@ <variablelist> <varlistentry><term><literal> TABLE ID = ival </literal></term> - <listitem><para> The unique, numeric ID number of the table the trigger is defined for. + <listitem><para> The unique, numeric ID number of the table the trigger is defined for.</para></listitem> </varlistentry> <varlistentry><term><literal> TRIGGER NAME = 'string' </literal></term> <listitem><para> The name of the trigger as it appears in the - <envar>pg_trigger</envar> system catalog. + <envar>pg_trigger</envar> system catalog.</para></listitem> </varlistentry> <varlistentry><term><literal> EVENT NODE = ival </literal></term> - <listitem><para> (Optional) The ID of the node used to create the - configuration event - that tells all existing nodes about the special trigger. Default - value is 1. + <listitem><para> (Optional) The ID of the node used to create + the configuration event that tells all existing nodes about the + special trigger. Default value is 1.</para></listitem> </varlistentry> </variablelist> </para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> STORE TRIGGER ( TABLE ID = 2, TRIGGER NAME = 'cache_invalidation' ); -</Programlisting> -</Refsect1> -</Refentry> + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> @@ -1297,7 +1320,8 @@ <refnamediv><refname>DROP TRIGGER</refname> -<refpurpose> Reconfigure <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Return a trigger to default behavior, where it will + not fire on subscriber nodes </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -1311,42 +1335,42 @@ <variablelist> <varlistentry><term><literal> TABLE ID = ival </literal></term> - <listitem><para> The unique, numeric ID number of the table the trigger is defined for. + <listitem><para> The unique, numeric ID number of the table the + trigger is defined for.</para></listitem> </varlistentry> <varlistentry><term><literal> TRIGGER NAME = 'string' </literal></term> <listitem><para> The name of the trigger as it appears in the - <envar>pg_trigger</envar> system catalog. + <envar>pg_trigger</envar> system catalog.</para></listitem> </varlistentry> <varlistentry><term><literal> EVENT NODE = ival </literal></term> - <listitem><para> (Optional) The ID of the node used to create the - configuration event - that tells all existing nodes about the special trigger. Default - value is 1. + <listitem><para> (Optional) The ID of the node used to create + the configuration event that tells all existing nodes about the + special trigger. Default value is 1.</para></listitem> </varlistentry> </variablelist> </para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> DROP TRIGGER ( TABLE ID = 2, TRIGGER NAME = 'cache_invalidation' ); -</Programlisting> -</Refsect1> -</Refentry> + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> <refentry id ="stmtsubscribeset"><refmeta><refentrytitle>SUBSCRIBE SET</refentrytitle> </refmeta> <refnamediv><refname>SUBSCRIBE SET</refname> -<refpurpose> Start replication of <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Start replication of <productname>Slony-I</productname> set </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -1358,79 +1382,85 @@ <para> Causes a node (subscriber) to start replicating a set of tables either from the origin or from another provider node, which must be an -active, forwarding subscriber itself. + active, forwarding subscriber itself.</para> -<para> The application tables contained in the set must already exist -and should ideally be empty. The current version of -<productname>Slony-I</productname> will <emphasis>not</emphasis> attempt to copy the schema -of the set. The replication daemon will start copying the current -content of the set from the given provider and then try to catch up -with any update activity that happened during that copy process. After -successful subscription, the tables are guarded on the subscriber, -using triggers, against accidental updates by the application. + <para> The application tables contained in the set must already + exist and should ideally be empty. The current version of + <productname>Slony-I</productname> will <emphasis>not</emphasis> + attempt to copy the schema of the set. The replication daemon will + start copying the current content of the set from the given + provider and then try to catch up with any update activity that + happened during that copy process. After successful subscription, + the tables are guarded on the subscriber, using triggers, against + accidental updates by the application. </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: <itemizedlist> -<listitem><para> It deletes all <quote>old</quote> entries in the table -<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 -<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. + + <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> -<note><para> - If you need to revise subscription information for a - node, you may submit the new information using this command, - and the new configuration will be propagated throughout the + <note><para> If you need to revise subscription information for a + node, you may submit the new information using this command, and + the new configuration will be propagated throughout the replication network. The normal reason to revise this information is that you want a node to subscribe to a <emphasis> different </emphasis> provider node, or for a node to become a <quote>forwarding</quote> subscriber so it may later become the - provider - for a later subscriber. </note> - - + provider for a later subscriber.</para> </note> <variablelist> <varlistentry><term><literal> ID = ival </literal></term> - <listitem><para> ID of the set to subscribe + <listitem><para> ID of the set to subscribe</para></listitem> </varlistentry> <varlistentry><term><literal> PROVIDER = ival </literal></term> - <listitem><para> Node ID of the data provider from which this node draws data. + <listitem><para> Node ID of the data provider from which this + node draws data.</para></listitem> </varlistentry> <varlistentry><term><literal> RECEIVER = ival </literal></term> - <listitem><para> Node ID of the new subscriber + <listitem><para> Node ID of the new subscriber</para></listitem> </varlistentry> <varlistentry><term><literal> FORWARD = boolean </literal></term> - <listitem><para> Flag whether or not the new subscriber should store - the log information during replication to make it + <listitem><para> Flag whether or not the new subscriber should + store the log information during replication to make it possible candidate for the provider role for future - nodes. - + nodes.</para></listitem> </varlistentry> </variablelist> </para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> SUBSCRIBE SET ( ID = 1, PROVIDER = 1, RECEIVER = 3, FORWARD = YES ); -</Programlisting> -</Refsect1> -</Refentry> + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> @@ -1438,7 +1468,7 @@ <refnamediv><refname>UNSUBSCRIBE SET</refname> -<refpurpose> End replication of <productname>Slony-I</productname> set </refpurpose> + <refpurpose> End replication of <productname>Slony-I</productname> set </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -1448,40 +1478,39 @@ <refsect1> <title>Description</title> -<para> - Stops the subscriber from replicating the set. The tables are - opened up for full access by the client application on the + <para> Stops the subscriber from replicating the set. The tables + are opened up for full access by the client application on the former subscriber. The tables are not truncated or otherwise modified. All original triggers, rules and constraints are restored. <warning><para> Resubscribing an unsubscribed set requires a -<emphasis>complete fresh copy</emphasis> of data from the provider to -be transferred since the tables have been subject to possible -independent modifications. </para></warning> + <emphasis>complete fresh copy</emphasis> of data from the + provider to be transferred since the tables have been subject to + possible independent modifications. </para></warning> <variablelist> <varlistentry><term><literal> ID = ival </literal></term> - <listitem><para> ID of the set to unsubscribe + <listitem><para> ID of the set to unsubscribe</para></listitem> </varlistentry> <varlistentry><term><literal> RECEIVER = ival </literal></term> - <listitem><para> Node ID of the (former) subscriber + <listitem><para> Node ID of the (former) subscriber</para></listitem> </varlistentry> </variablelist> </para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> UNSUBSCRIBE SET ( ID = 1, RECEIVER = 3 ); -</Programlisting> -</Refsect1> -</Refentry> + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> @@ -1490,7 +1519,9 @@ <refnamediv><refname>LOCK SET</refname> -<refpurpose> Configuration of <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Guard <productname>Slony-I</productname> replication + set to prepare for <command>MOVE SET</command> + </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>LOCK SET (options);</command> @@ -1499,29 +1530,27 @@ <refsect1> <title>Description</title> -<para> - Guards a replication set against client application updates in - preparation for a <link linkend="stmtmoveset">MOVE SET</link> + <para> Guards a replication set against client application updates + in preparation for a <link linkend="stmtmoveset">MOVE SET</link> command. </para> -<para> - This command must be the first in a possible statement group - (<command>try</command>). The reason for this is that it needs to - commit the changes made to the tables (adding a special + + <para> This command must be the first in a possible statement + group (<command>try</command>). The reason for this is that it + needs to commit the changes made to the tables (adding a special trigger function) before it can wait for every concurrent transaction to finish. At the same time it cannot hold an open - transaction to the same database itself since this would - result in blocking itself forever. - + transaction to the same database itself since this would result in + blocking itself forever. <variablelist> <varlistentry><term><literal> ID = ival </literal></term> - <listitem><para> ID of the set to lock + <listitem><para> ID of the set to lock</para></listitem> </varlistentry> <varlistentry><term><literal> ORIGIN = ival </literal></term> - <listitem><para> Node ID of the current set origin + <listitem><para> Node ID of the current set origin</para></listitem> </varlistentry> </variablelist> @@ -1543,7 +1572,7 @@ <refnamediv><refname>UNLOCK SET</refname> -<refpurpose> Configuration of <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Unlock a <productname>Slony-I</productname> set that was locked </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>UNLOCK SET (options);</command> @@ -1555,29 +1584,28 @@ <para> Unlocks a previously locked set. - <variablelist> <varlistentry><term><literal> ID = ival </literal></term> - <listitem><para> ID of the set to unlock + <listitem><para> ID of the set to unlock</para></listitem> </varlistentry> <varlistentry><term><literal> ORIGIN = ival </literal></term> - <listitem><para> Node ID of the current set origin + <listitem><para> Node ID of the current set origin</para></listitem> </varlistentry> </variablelist> </para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> UNLOCK SET ( ID = 1, RECEIVER = 3 ); -</Programlisting> -</Refsect1> -</Refentry> + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> @@ -1586,7 +1614,8 @@ <refnamediv><refname>MOVE SET</refname> -<refpurpose> Reconfiguration of <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Change origin of a <productname>Slony-I</productname> + replication set </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>MOVE SET (options);</command> @@ -1595,60 +1624,57 @@ <refsect1> <title>Description</title> -<para> - Changes the origin of a set from one node to another. The new - origin must be a current subscriber of the set. The set must + <para> Changes the origin of a set from one node to another. The + new origin must be a current subscriber of the set. The set must currently be locked on the old origin. </para> -<para> - After this command, the set cannot be unlocked on the old + <para> After this command, the set cannot be unlocked on the old origin any more. The old origin will continue as a forwarding subscriber of the set and the subscription chain from the old - origin to the new origin will be reversed, hop by hop. As soon - as the new origin has finished processing the event (that - includes any outstanding sync events that happened before, - <emphasis>i.e.</emphasis> fully catching up), the new origin - will take over and open all tables in the set for client - application update - activity. + origin to the new origin will be reversed, hop by hop. As soon as + the new origin has finished processing the event (that includes + any outstanding sync events that happened before, + <emphasis>i.e.</emphasis> fully catching up), the new origin will + take over and open all tables in the set for client application + update activity. </para> -<para> - This is <emphasis>not</emphasis> failover, as it requires a functioning - old origin node (you needed to lock the set on the old + + <para> This is <emphasis>not</emphasis> failover, as it requires a + functioning old origin node (you needed to lock the set on the old origin). You would probably prefer to <command>MOVE SET</command> instead of <command>FAILOVER</command>, if at all possible, as - <command>FAILOVER</command> winds up discarding the old origin node as - being corrupted. + <command>FAILOVER</command> winds up discarding the old origin + node as being corrupted. <variablelist> <varlistentry><term><literal> ID = ival </literal></term> - <listitem><para> ID of the set to transfer + <listitem><para> ID of the set to transfer</para></listitem> </varlistentry> <varlistentry><term><literal> OLD ORIGIN = ival </literal></term> - <listitem><para> Node ID of the current set origin + <listitem><para> Node ID of the current set origin</para></listitem> </varlistentry> <varlistentry><term><literal> NEW ORIGIN = ival </literal></term> - <listitem><para> Node ID of the new set origin + <listitem><para> Node ID of the new set origin</para></listitem> </varlistentry> </variablelist> </para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> MOVE SET ( ID = 1, OLD ORIGIN = 1, NEW ORIGIN = 3 ); -</Programlisting> -</Refsect1> -</Refentry> + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> @@ -1656,7 +1682,8 @@ <refnamediv><refname>FAILOVER</refname> -<refpurpose> Reconfiguration of <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Fail a broken replication set over to a backup node + </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>FAILOVER (options);</command> @@ -1666,51 +1693,54 @@ <title>Description</title> <para> - The failover command causes the backup node to take over all - sets that currently originate on the failed node. <Application>Slonik</Application> will - contact all other direct subscribers of the failed node to - determine which node has the highest sync status for each - set. If another node has a higher sync status than the backup - node, the replication will first be redirected so that the - backup node replicates against that other node, before - assuming the origin role and allowing update activity. -</para> -<para> - After successful failover, all former direct subscribers of - the failed node become direct subscribers of the backup - node. The failed node can and should be removed from the - configuration with <command><link linkend="stmtdropnode"> DROP NODE</link> </command>. + The failover command causes the backup node to take over all sets + that currently originate on the failed + node. <application>Slonik</application> will contact all other + direct subscribers of the failed node to determine which node has + the highest sync status for each set. If another node has a + higher sync status than the backup node, the replication will + first be redirected so that the backup node replicates against + that other node, before assuming the origin role and allowing + update activity. + </para> + <para> + After successful failover, all former direct subscribers of the + failed node become direct subscribers of the backup node. The + failed node can and should be removed from the configuration with + <command><link linkend="stmtdropnode"> DROP NODE</link> + </command>. </para> <warning><para> This command will abandon the status of the failed node. There is no possibility to let the failed node join the - cluster again without rebuilding it from scratch as a slave - slave. It would often be highly preferable to use <command> <link linkend="stmtmoveset"> MOVE SET </link> </command> instead. + cluster again without rebuilding it from scratch as a slave slave. + It would often be highly preferable to use <command> <link + linkend="stmtmoveset"> MOVE SET </link> </command> instead. </para></warning> <variablelist> <varlistentry><term><literal> ID = ival </literal></term> - <listitem><para> ID of the failed node + <listitem><para> ID of the failed node</para></listitem> </varlistentry> <varlistentry><term><literal> BACKUP NODE = ival </literal></term> - <listitem><para> Node ID of the node that will take over all sets originating on the failed node + <listitem><para> Node ID of the node that will take over all + sets originating on the failed node</para></listitem> </varlistentry> </variablelist> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> FAILOVER ( ID = 1, BACKUP NODE = 2 ); -</Programlisting> -</Refsect1> -</Refentry> - + </programlisting> + </refsect1> + </refentry> <!-- **************************************** --> @@ -1718,7 +1748,7 @@ <refnamediv><refname>EXECUTE SCRIPT</refname> -<refpurpose> Reconfiguration of <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Execute SQL/DDL script </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>EXECUTE SCRIPT (options);</command> @@ -1727,21 +1757,22 @@ <refsect1> <title>Description</title> -<para> Executes a script containing arbitrary SQL statements on all -nodes that are subscribed to a set at a common controlled point within -the replication transaction stream.</para> - -<para> The specified event origin must be the origin of the set. The -script file must not contain any <command>START</command> or <command>COMMIT</command> -TRANSACTION/ calls. (This may change in PostgreSQL 8.0 once nested -transactions, aka savepoints, are supported) In addition, -non-deterministic DML statements (like updating a field with -<function>CURRENT_TIMESTAMP</function>) must be avoided, since the data changes -done by the script are explicitly not replicated. </para> + <para> Executes a script containing arbitrary SQL statements on + all nodes that are subscribed to a set at a common controlled + point within the replication transaction stream.</para> + + <para> The specified event origin must be the origin of the set. + The script file must not contain any <command>START</command> or + <command>COMMIT TRANSACTION</command> calls. (This may change in + PostgreSQL 8.0 once nested transactions, aka savepoints, are + supported) In addition, non-deterministic DML statements (like + updating a field with <function>CURRENT_TIMESTAMP</function>) must + be avoided, since the data changes done by the script are + explicitly not replicated. </para> <variablelist> <varlistentry><term><literal> SET ID = ival </literal></term> - <listitem><para> The unique numeric ID number of the set affected by the script + <listitem><para> The unique numeric ID number of the set affected by the script</para></listitem> </varlistentry> <varlistentry><term><literal> FILENAME = '/path/to/file' </literal></term> @@ -1749,74 +1780,75 @@ <listitem><para> The name of the file containing the SQL script to execute. This might be a relative path, relative to the location of the <application>slonik</application> instance you are running, or, preferably, - an absolute path on the system where <application>slonik</application> is to run. + an absolute path on the system where <application>slonik</application> is to run.</para> <para> The <emphasis>contents</emphasis> of the file are propagated as part of the event, so the file does not need to be accessible on any of the - nodes. + nodes.</para></listitem> </varlistentry> <varlistentry><term><literal> EVENT NODE = ival </literal></term> - <listitem><para> (Optional) The ID of the current origin of the set. Default value is 1. + <listitem><para> (Optional) The ID of the current origin of the set. Default value is 1.</para></listitem> </varlistentry> - <varlistentry><term><literal> EXECUTE ONLY ON = ival </literal></term> - <listitem><para> (Optional) The ID of the only node to actually execute the script. - This option causes the script to be propagated by all nodes - but executed only by one. + <varlistentry><term><literal> EXECUTE ONLY ON = ival + </literal></term> <listitem><para> (Optional) The ID of the only + node to actually execute the script. This option causes the + script to be propagated by all nodes but executed only by one. The default is to execute the script on all nodes that are - subscribed to the set. - + subscribed to the set.</para></listitem> </varlistentry> </variablelist> -<para> See also the warnings in <link linkend="ddlchanges"> Database -Schema Changes (DDL)</link>. + <para> See also the warnings in <link linkend="ddlchanges"> + Database Schema Changes (DDL)</link>.</para> -</Refsect1> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> EXECUTE SCRIPT ( SET ID = 1, FILENAME = '/tmp/changes_2004-05-01.sql', EVENT NODE = 1 ); -</Programlisting> -</Refsect1> -</Refentry> + </programlisting> + </refsect1> + </refentry> +<!-- **************************************** --> <refentry id ="stmtwaitevent"><refmeta><refentrytitle>WAIT FOR EVENT</refentrytitle> </refmeta> <refnamediv><refname>WAIT FOR EVENT</refname> -<refpurpose> Reconfiguration of <productname>Slony-I</productname> set </refpurpose> + <refpurpose> Have Slonik script wait for previous event to + complete </refpurpose></refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>WAIT FOR EVENT (options);</command> </cmdsynopsis> </refsynopsisdiv> - <refsect1> <title>Description</title> <para> Waits for event Confirmation.</para> -<para> <Application>slonik</Application> remembers the last event generated on -every node during script execution (events generated by earlier calls -are currently not checked). In certain situations it is necessary that -events generated on one node (such as <command>CREATE SET</command>) -are processed on another node before issuing more commands (for -instance, <link linkend="stmtsubscribeset"><command>SUBSCRIBE -SET</command></link>). <COMMAND>WAIT FOR EVENT</COMMAND> may be used to cause -the <application>slonik</application> script to wait until the subscriber node is -ready for the next action. + <para> <application>Slonik</application> remembers the last event + generated on every node during script execution (events generated + by earlier calls are currently not checked). In certain situations + it is necessary that events generated on one node (such as + <command>CREATE SET</command>) are processed on another node + before issuing more commands (for instance, <link + linkend="stmtsubscribeset"><command>SUBSCRIBE + SET</command></link>). <command>WAIT FOR EVENT</command> may be + used to cause the <application>slonik</application> script to wait + until the subscriber node is ready for the next action. </para> -<para> <command>WAIT FOR EVENT</command> must be called outside of any -<command>try</command> block in order to work, since new confirm messages don't -become visible within a transaction.</para> + <para> <command>WAIT FOR EVENT</command> must be called outside of + any <command>try</command> block in order to work, since new + confirm messages don't become visible within a transaction. <variablelist> <varlistentry><term><literal> ORIGIN = ival | ALL </literal></term> @@ -1829,31 +1861,32 @@ </varlistentry> <varlistentry><term><literal> WAIT ON = ival </literal></term> - <listitem><para> The ID of the node where the sl_confirm table is to be checked. The default value is 1.</para></listitem> + <listitem><para> The ID of the node where the sl_confirm table + is to be checked. The default value is 1.</para></listitem> </varlistentry> <varlistentry><term><literal> TIMEOUT = ival </literal></term> - <listitem><para> The number of seconds to wait. Default is 600 (10 - minutes). <command>TIMEOUT = 0</command> causes the script to wait - indefinitely.</para></listitem> + <listitem><para> The number of seconds to wait. Default is 600 + (10 minutes). <command>TIMEOUT = 0</command> causes the script + to wait indefinitely.</para></listitem> </varlistentry> -</variablelist> -</Refsect1> + </variablelist></para> -<Refsect1><Title>Example</Title> -<Programlisting> + </refsect1> + <refsect1><title>Example</title> + <programlisting> WAIT FOR EVENT ( ORIGIN = ALL, CONFIRMED = ALL, WAIT ON = 1 ); -</Programlisting> -</Refsect1> -</Refentry> - + </programlisting> + </refsect1> + </refentry> </reference> +</article> <!-- Keep this comment at the end of the file Local variables: mode:sgml
- Previous message: [Slony1-commit] By cbbrowne: Added commentary on what happens to triggers and rules
- Next message: [Slony1-commit] By cbbrowne: Point to internal Slonik command reference, not the GBorg
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
More information about the Slony1-commit mailing list