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
will be bypassed in practice. But this might change in the future.)
</para>
<para>
When refreshing a publication we remove the relations that are no longer
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
allocated for the subscription on the remote host are released. If due to
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
slot from the subscription and drop the subscription as explained in
<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.
These commands also cannot be executed when the subscription has
<literal>two_phase</literal> commit enabled, unless <literal>copy_data = false</literal>.
See column <literal>subtwophasestate</literal> of
<xref linkend="catalog-pg-subscription"/> to know the actual two-phase state.
<literal>two_phase</literal> commit enabled,
unless <literal>copy_data</literal> is <literal>false</literal>.
See column <structfield>subtwophasestate</structfield> of
<link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
to know the actual two-phase state.
</para>
</refsect1>
@ -92,7 +94,7 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
<term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
<listitem>
<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
information.
</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>
<listitem>
<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,
<literal>ADD</literal> adds additional publications to the list of
publications, and <literal>DROP</literal> removes the publications from
@ -143,8 +146,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
<para>
Fetch missing table information from publisher. This will start
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>.
since <command>CREATE SUBSCRIPTION</command> or
the last invocation of <command>REFRESH PUBLICATION</command>.
</para>
<para>
@ -156,9 +159,9 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
<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.
The default is <literal>true</literal>. (Previously subscribed
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>. (Previously-subscribed
tables are not copied.)
</para>
</listitem>
@ -171,8 +174,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
<term><literal>ENABLE</literal></term>
<listitem>
<para>
Enables the previously disabled subscription, starting the logical
replication worker at the end of transaction.
Enables a previously disabled subscription, starting the logical
replication worker at the end of the transaction.
</para>
</listitem>
</varlistentry>
@ -181,8 +184,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
<term><literal>DISABLE</literal></term>
<listitem>
<para>
Disables the running subscription, stopping the logical replication
worker at the end of transaction.
Disables a running subscription, stopping the logical replication
worker at the end of the transaction.
</para>
</listitem>
</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>
<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>