mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doc: improve documentation of CREATE/ALTER SUBSCRIPTION.

Browse Source 
Improve the descriptions of some options.  Fix sloppy grammar and markup.

Peter Smith and Tom Lane

Discussion: https://postgr.es/m/CAHut+PtPJDSOxtuMGpO2yDrRPKxcYGL4n7HqJP9HernZE=Cj+g@mail.gmail.com
This commit is contained in:
Tom Lane 2021-09-13 14:27:02 -04:00
parent 1bf2518dd6
commit 1882d6cca1
2 changed files with 76 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
doc/src/sgml/ref/alter_subscription.sgml
View File

@ -50,14 +50,14 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
(Currently, all subscription owners must be superusers, so the owner checks (Currently, all subscription owners must be superusers, so the owner checks
will be bypassed in practice. But this might change in the future.) will be bypassed in practice. But this might change in the future.)
</para> </para>
<para> <para>
When refreshing a publication we remove the relations that are no longer When refreshing a publication we remove the relations that are no longer
part of the publication and we also remove the table synchronization slots part of the publication and we also remove the table synchronization slots
if there are any. It is necessary to remove these slots so that the resources if there are any. It is necessary to remove these slots so that the resources
allocated for the subscription on the remote host are released. If due to allocated for the subscription on the remote host are released. If due to
network breakdown or some other error, <productname>PostgreSQL</productname> network breakdown or some other error, <productname>PostgreSQL</productname>
is unable to remove the slots, an ERROR will be reported. To proceed in this is unable to remove the slots, an error will be reported. To proceed in this
situation, the user either needs to retry the operation or disassociate the situation, the user either needs to retry the operation or disassociate the
slot from the subscription and drop the subscription as explained in slot from the subscription and drop the subscription as explained in
<xref linkend="sql-dropsubscription"/>. <xref linkend="sql-dropsubscription"/>.
@ -69,9 +69,11 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
option as true cannot be executed inside a transaction block. option as true cannot be executed inside a transaction block.
These commands also cannot be executed when the subscription has These commands also cannot be executed when the subscription has
<literal>two_phase</literal> commit enabled, unless <literal>copy_data = false</literal>. <literal>two_phase</literal> commit enabled,
See column <literal>subtwophasestate</literal> of unless <literal>copy_data</literal> is <literal>false</literal>.
<xref linkend="catalog-pg-subscription"/> to know the actual two-phase state. See column <structfield>subtwophasestate</structfield> of
<link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
to know the actual two-phase state.
</para> </para>
</refsect1> </refsect1>
@ -92,7 +94,7 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
<term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term> <term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
<listitem> <listitem>
<para> <para>
This clause alters the connection property originally set by This clause replaces the connection string originally set by
<xref linkend="sql-createsubscription"/>. See there for more <xref linkend="sql-createsubscription"/>. See there for more
information. information.
</para> </para>
@ -105,7 +107,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
<term><literal>DROP PUBLICATION <replaceable class="parameter">publication_name</replaceable></literal></term> <term><literal>DROP PUBLICATION <replaceable class="parameter">publication_name</replaceable></literal></term>
<listitem> <listitem>
<para> <para>
Changes the list of subscribed publications. <literal>SET</literal> These forms change the list of subscribed publications.
<literal>SET</literal>
replaces the entire list of publications with a new list, replaces the entire list of publications with a new list,
<literal>ADD</literal> adds additional publications to the list of <literal>ADD</literal> adds additional publications to the list of
publications, and <literal>DROP</literal> removes the publications from publications, and <literal>DROP</literal> removes the publications from
@ -143,8 +146,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
<para> <para>
Fetch missing table information from publisher. This will start Fetch missing table information from publisher. This will start
replication of tables that were added to the subscribed-to publications replication of tables that were added to the subscribed-to publications
since the last invocation of <command>REFRESH PUBLICATION</command> or since <command>CREATE SUBSCRIPTION</command> or
since <command>CREATE SUBSCRIPTION</command>. the last invocation of <command>REFRESH PUBLICATION</command>.
</para> </para>
<para> <para>
@ -156,9 +159,9 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
<term><literal>copy_data</literal> (<type>boolean</type>)</term> <term><literal>copy_data</literal> (<type>boolean</type>)</term>
<listitem> <listitem>
<para> <para>
Specifies whether the existing data in the publications that are Specifies whether to copy pre-existing data in the publications
being subscribed to should be copied once the replication starts. that are being subscribed to when the replication starts.
The default is <literal>true</literal>. (Previously subscribed The default is <literal>true</literal>. (Previously-subscribed
tables are not copied.) tables are not copied.)
</para> </para>
</listitem> </listitem>
@ -171,8 +174,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
<term><literal>ENABLE</literal></term> <term><literal>ENABLE</literal></term>
<listitem> <listitem>
<para> <para>
Enables the previously disabled subscription, starting the logical Enables a previously disabled subscription, starting the logical
replication worker at the end of transaction. replication worker at the end of the transaction.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -181,8 +184,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
<term><literal>DISABLE</literal></term> <term><literal>DISABLE</literal></term>
<listitem> <listitem>
<para> <para>
Disables the running subscription, stopping the logical replication Disables a running subscription, stopping the logical replication
worker at the end of transaction. worker at the end of the transaction.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>

107
doc/src/sgml/ref/create_subscription.sgml
View File

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