diff options
Diffstat (limited to 'doc/src/sgml/ref/create_subscription.sgml')
| -rw-r--r-- | doc/src/sgml/ref/create_subscription.sgml | 107 |
1 files changed, 57 insertions, 50 deletions
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml index 04a0fd7fba3..990a41f1a1b 100644 --- a/doc/src/sgml/ref/create_subscription.sgml +++ b/doc/src/sgml/ref/create_subscription.sgml @@ -32,20 +32,21 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl <title>Description</title> <para> - <command>CREATE SUBSCRIPTION</command> adds a new subscription for the - current database. The subscription name must be distinct from the name of - any existing subscription in the database. + <command>CREATE SUBSCRIPTION</command> adds a new logical-replication + subscription. The subscription name must be distinct from the name of + any existing subscription in the current database. </para> <para> - The subscription represents a replication connection to the publisher. As - such this command does not only add definitions in the local catalogs but - also creates a replication slot on the publisher. + A subscription represents a replication connection to the publisher. + Hence, in addition to adding definitions in the local catalogs, this + command normally creates a replication slot on the publisher. </para> <para> A logical replication worker will be started to replicate data for the new - subscription at the commit of the transaction where this command is run. + subscription at the commit of the transaction where this command is run, + unless the subscription is initially disabled. </para> <para> @@ -73,14 +74,15 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl <term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term> <listitem> <para> - The connection string to the publisher. For details - see <xref linkend="libpq-connstring"/>. + The <application>libpq</application> connection string defining how + to connect to the publisher database. For details see + <xref linkend="libpq-connstring"/>. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable></literal></term> + <term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable> [, ...]</literal></term> <listitem> <para> Names of the publications on the publisher to subscribe to. @@ -105,25 +107,23 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl <listitem> <para> Specifies whether the <command>CREATE SUBSCRIPTION</command> - should connect to the publisher at all. Setting this to - <literal>false</literal> will change default values of - <literal>enabled</literal>, <literal>create_slot</literal> and + command should connect to the publisher at all. The default + is <literal>true</literal>. Setting this to + <literal>false</literal> will force the values of + <literal>create_slot</literal>, <literal>enabled</literal> and <literal>copy_data</literal> to <literal>false</literal>. + (You cannot combine setting <literal>connect</literal> + to <literal>false</literal> with + setting <literal>create_slot</literal>, <literal>enabled</literal>, + or <literal>copy_data</literal> to <literal>true</literal>.) </para> <para> - It is not allowed to combine <literal>connect</literal> set to - <literal>false</literal> and <literal>enabled</literal>, - <literal>create_slot</literal>, or <literal>copy_data</literal> - set to <literal>true</literal>. - </para> - - <para> - Since no connection is made when this option is set - to <literal>false</literal>, the tables are not subscribed, and so + Since no connection is made when this option is + <literal>false</literal>, no tables are subscribed, and so after you enable the subscription nothing will be replicated. - It is required to run - <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> in order + You will need to then run + <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> for tables to be subscribed. </para> </listitem> @@ -135,6 +135,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl <para> Specifies whether the command should create the replication slot on the publisher. The default is <literal>true</literal>. + If set to <literal>false</literal>, you are responsible for + creating the publisher's slot in some other way. </para> </listitem> </varlistentry> @@ -143,8 +145,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl <term><literal>enabled</literal> (<type>boolean</type>)</term> <listitem> <para> - Specifies whether the subscription should be actively replicating, - or whether it should be just setup but not started yet. The default + Specifies whether the subscription should be actively replicating + or whether it should just be set up but not started yet. The default is <literal>true</literal>. </para> </listitem> @@ -154,15 +156,15 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl <term><literal>slot_name</literal> (<type>string</type>)</term> <listitem> <para> - Name of the replication slot to use. The default behavior is to - use the name of the subscription for the slot name. + Name of the publisher's replication slot to use. The default is + to use the name of the subscription for the slot name. </para> <para> - When <literal>slot_name</literal> is set to - <literal>NONE</literal>, there will be no replication slot - associated with the subscription. This can be used if the - replication slot will be created later manually. Such + Setting <literal>slot_name</literal> to <literal>NONE</literal> + means there will be no replication slot + associated with the subscription. Use this when you will be + creating the replication slot later manually. Such subscriptions must also have both <literal>enabled</literal> and <literal>create_slot</literal> set to <literal>false</literal>. </para> @@ -172,7 +174,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl </para> <para> - The following parameters control the replication behavior: + The following parameters control the subscription's replication + behavior after it has been created: <variablelist> @@ -183,14 +186,14 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl Specifies whether the subscription will request the publisher to send the data in binary format (as opposed to text). The default is <literal>false</literal>. - Even when this option is enabled, only data types that have + Even when this option is enabled, only data types having binary send and receive functions will be transferred in binary. </para> <para> - When doing cross-version replication, it could happen that the + When doing cross-version replication, it could be that the publisher has a binary send function for some data type, but the - subscriber lacks a binary receive function for the type. In + subscriber lacks a binary receive function for that type. In such a case, data transfer will fail, and the <literal>binary</literal> option cannot be used. </para> @@ -201,8 +204,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl <term><literal>copy_data</literal> (<type>boolean</type>)</term> <listitem> <para> - Specifies whether the existing data in the publications that are - being subscribed to should be copied once the replication starts. + Specifies whether to copy pre-existing data in the publications + that are being subscribed to when the replication starts. The default is <literal>true</literal>. </para> </listitem> @@ -212,9 +215,9 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl <term><literal>streaming</literal> (<type>boolean</type>)</term> <listitem> <para> - Specifies whether streaming of in-progress transactions should - be enabled for this subscription. By default, all transactions - are fully decoded on the publisher, and only then sent to the + Specifies whether to enable streaming of in-progress transactions + for this subscription. By default, all transactions + are fully decoded on the publisher and only then sent to the subscriber as a whole. </para> </listitem> @@ -261,18 +264,22 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl </para> <para> - When two-phase commit is enabled then the decoded transactions are sent - to the subscriber on the PREPARE TRANSACTION. By default, the transaction - prepared on the publisher is decoded as a normal transaction at commit. + When two-phase commit is enabled, prepared transactions are sent + to the subscriber at the time of <command>PREPARE + TRANSACTION</command>, and are processed as two-phase + transactions on the subscriber too. Otherwise, prepared + transactions are sent to the subscriber only when committed, and + are then processed immediately by the subscriber. </para> <para> - The two-phase commit implementation requires that the replication has - successfully passed the initial table synchronization phase. This means - even when two_phase is enabled for the subscription, the internal - two-phase state remains temporarily "pending" until the initialization - phase is completed. See column - <literal>subtwophasestate</literal> of <xref linkend="catalog-pg-subscription"/> + The implementation of two-phase commit requires that replication + has successfully finished the initial table synchronization + phase. So even when <literal>two_phase</literal> is enabled for a + subscription, the internal two-phase state remains + temporarily <quote>pending</quote> until the initialization phase + completes. See column <structfield>subtwophasestate</structfield> + of <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link> to know the actual two-phase state. </para> |