Skip to content

Commit 1882d6c

Browse files
tglsfdctglsfdc
committed
Doc: improve documentation of CREATE/ALTER SUBSCRIPTION.
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
1 parent 1bf2518 commit 1882d6c

File tree

2 files changed

+76
-66
lines changed

2 files changed

+76
-66
lines changed

‎doc/src/sgml/ref/alter_subscription.sgml

Lines changed: 19 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -50,14 +50,14 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
5050
(Currently, all subscription owners must be superusers, so the owner checks
5151
will be bypassed in practice. But this might change in the future.)
5252
</para>
53-
53+
5454
<para>
5555
When refreshing a publication we remove the relations that are no longer
5656
part of the publication and we also remove the table synchronization slots
5757
if there are any. It is necessary to remove these slots so that the resources
5858
allocated for the subscription on the remote host are released. If due to
5959
network breakdown or some other error, <productname>PostgreSQL</productname>
60-
is unable to remove the slots, an ERROR will be reported. To proceed in this
60+
is unable to remove the slots, an error will be reported. To proceed in this
6161
situation, the user either needs to retry the operation or disassociate the
6262
slot from the subscription and drop the subscription as explained in
6363
<xref linkend="sql-dropsubscription"/>.
@@ -69,9 +69,11 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
6969
option as true cannot be executed inside a transaction block.
7070

7171
These commands also cannot be executed when the subscription has
72-
<literal>two_phase</literal> commit enabled, unless <literal>copy_data = false</literal>.
73-
See column <literal>subtwophasestate</literal> of
74-
<xref linkend="catalog-pg-subscription"/> to know the actual two-phase state.
72+
<literal>two_phase</literal> commit enabled,
73+
unless <literal>copy_data</literal> is <literal>false</literal>.
74+
See column <structfield>subtwophasestate</structfield> of
75+
<link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
76+
to know the actual two-phase state.
7577
</para>
7678
</refsect1>
7779

@@ -92,7 +94,7 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
9294
<term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
9395
<listitem>
9496
<para>
95-
This clause alters the connection property originally set by
97+
This clause replaces the connection string originally set by
9698
<xref linkend="sql-createsubscription"/>. See there for more
9799
information.
98100
</para>
@@ -105,7 +107,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
105107
<term><literal>DROP PUBLICATION <replaceable class="parameter">publication_name</replaceable></literal></term>
106108
<listitem>
107109
<para>
108-
Changes the list of subscribed publications. <literal>SET</literal>
110+
These forms change the list of subscribed publications.
111+
<literal>SET</literal>
109112
replaces the entire list of publications with a new list,
110113
<literal>ADD</literal> adds additional publications to the list of
111114
publications, and <literal>DROP</literal> removes the publications from
@@ -143,8 +146,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
143146
<para>
144147
Fetch missing table information from publisher. This will start
145148
replication of tables that were added to the subscribed-to publications
146-
since the last invocation of <command>REFRESH PUBLICATION</command> or
147-
since <command>CREATE SUBSCRIPTION</command>.
149+
since <command>CREATE SUBSCRIPTION</command> or
150+
the last invocation of <command>REFRESH PUBLICATION</command>.
148151
</para>
149152

150153
<para>
@@ -156,9 +159,9 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
156159
<term><literal>copy_data</literal> (<type>boolean</type>)</term>
157160
<listitem>
158161
<para>
159-
Specifies whether the existing data in the publications that are
160-
being subscribed to should be copied once the replication starts.
161-
The default is <literal>true</literal>. (Previously subscribed
162+
Specifies whether to copy pre-existing data in the publications
163+
that are being subscribed to when the replication starts.
164+
The default is <literal>true</literal>. (Previously-subscribed
162165
tables are not copied.)
163166
</para>
164167
</listitem>
@@ -171,8 +174,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
171174
<term><literal>ENABLE</literal></term>
172175
<listitem>
173176
<para>
174-
Enables the previously disabled subscription, starting the logical
175-
replication worker at the end of transaction.
177+
Enables a previously disabled subscription, starting the logical
178+
replication worker at the end of the transaction.
176179
</para>
177180
</listitem>
178181
</varlistentry>
@@ -181,8 +184,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
181184
<term><literal>DISABLE</literal></term>
182185
<listitem>
183186
<para>
184-
Disables the running subscription, stopping the logical replication
185-
worker at the end of transaction.
187+
Disables a running subscription, stopping the logical replication
188+
worker at the end of the transaction.
186189
</para>
187190
</listitem>
188191
</varlistentry>

‎doc/src/sgml/ref/create_subscription.sgml

Lines changed: 57 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -32,20 +32,21 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
3232
<title>Description</title>
3333

3434
<para>
35-
<command>CREATE SUBSCRIPTION</command> adds a new subscription for the
36-
current database. The subscription name must be distinct from the name of
37-
any existing subscription in the database.
35+
<command>CREATE SUBSCRIPTION</command> adds a new logical-replication
36+
subscription. The subscription name must be distinct from the name of
37+
any existing subscription in the current database.
3838
</para>
3939

4040
<para>
41-
The subscription represents a replication connection to the publisher. As
42-
such this command does not only add definitions in the local catalogs but
43-
also creates a replication slot on the publisher.
41+
A subscription represents a replication connection to the publisher.
42+
Hence, in addition to adding definitions in the local catalogs, this
43+
command normally creates a replication slot on the publisher.
4444
</para>
4545

4646
<para>
4747
A logical replication worker will be started to replicate data for the new
48-
subscription at the commit of the transaction where this command is run.
48+
subscription at the commit of the transaction where this command is run,
49+
unless the subscription is initially disabled.
4950
</para>
5051

5152
<para>
@@ -73,14 +74,15 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
7374
<term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
7475
<listitem>
7576
<para>
76-
The connection string to the publisher. For details
77-
see <xref linkend="libpq-connstring"/>.
77+
The <application>libpq</application> connection string defining how
78+
to connect to the publisher database. For details see
79+
<xref linkend="libpq-connstring"/>.
7880
</para>
7981
</listitem>
8082
</varlistentry>
8183

8284
<varlistentry>
83-
<term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable></literal></term>
85+
<term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable> [, ...]</literal></term>
8486
<listitem>
8587
<para>
8688
Names of the publications on the publisher to subscribe to.
@@ -105,25 +107,23 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
105107
<listitem>
106108
<para>
107109
Specifies whether the <command>CREATE SUBSCRIPTION</command>
108-
should connect to the publisher at all. Setting this to
109-
<literal>false</literal> will change default values of
110-
<literal>enabled</literal>, <literal>create_slot</literal> and
110+
command should connect to the publisher at all. The default
111+
is <literal>true</literal>. Setting this to
112+
<literal>false</literal> will force the values of
113+
<literal>create_slot</literal>, <literal>enabled</literal> and
111114
<literal>copy_data</literal> to <literal>false</literal>.
115+
(You cannot combine setting <literal>connect</literal>
116+
to <literal>false</literal> with
117+
setting <literal>create_slot</literal>, <literal>enabled</literal>,
118+
or <literal>copy_data</literal> to <literal>true</literal>.)
112119
</para>
113120

114121
<para>
115-
It is not allowed to combine <literal>connect</literal> set to
116-
<literal>false</literal> and <literal>enabled</literal>,
117-
<literal>create_slot</literal>, or <literal>copy_data</literal>
118-
set to <literal>true</literal>.
119-
</para>
120-
121-
<para>
122-
Since no connection is made when this option is set
123-
to <literal>false</literal>, the tables are not subscribed, and so
122+
Since no connection is made when this option is
123+
<literal>false</literal>, no tables are subscribed, and so
124124
after you enable the subscription nothing will be replicated.
125-
It is required to run
126-
<literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> in order
125+
You will need to then run
126+
<literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal>
127127
for tables to be subscribed.
128128
</para>
129129
</listitem>
@@ -135,6 +135,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
135135
<para>
136136
Specifies whether the command should create the replication slot on
137137
the publisher. The default is <literal>true</literal>.
138+
If set to <literal>false</literal>, you are responsible for
139+
creating the publisher's slot in some other way.
138140
</para>
139141
</listitem>
140142
</varlistentry>
@@ -143,8 +145,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
143145
<term><literal>enabled</literal> (<type>boolean</type>)</term>
144146
<listitem>
145147
<para>
146-
Specifies whether the subscription should be actively replicating,
147-
or whether it should be just setup but not started yet. The default
148+
Specifies whether the subscription should be actively replicating
149+
or whether it should just be set up but not started yet. The default
148150
is <literal>true</literal>.
149151
</para>
150152
</listitem>
@@ -154,15 +156,15 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
154156
<term><literal>slot_name</literal> (<type>string</type>)</term>
155157
<listitem>
156158
<para>
157-
Name of the replication slot to use. The default behavior is to
158-
use the name of the subscription for the slot name.
159+
Name of the publisher's replication slot to use. The default is
160+
to use the name of the subscription for the slot name.
159161
</para>
160162

161163
<para>
162-
When <literal>slot_name</literal> is set to
163-
<literal>NONE</literal>, there will be no replication slot
164-
associated with the subscription. This can be used if the
165-
replication slot will be created later manually. Such
164+
Setting <literal>slot_name</literal> to <literal>NONE</literal>
165+
means there will be no replication slot
166+
associated with the subscription. Use this when you will be
167+
creating the replication slot later manually. Such
166168
subscriptions must also have both <literal>enabled</literal> and
167169
<literal>create_slot</literal> set to <literal>false</literal>.
168170
</para>
@@ -172,7 +174,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
172174
</para>
173175

174176
<para>
175-
The following parameters control the replication behavior:
177+
The following parameters control the subscription's replication
178+
behavior after it has been created:
176179

177180
<variablelist>
178181

@@ -183,14 +186,14 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
183186
Specifies whether the subscription will request the publisher to
184187
send the data in binary format (as opposed to text).
185188
The default is <literal>false</literal>.
186-
Even when this option is enabled, only data types that have
189+
Even when this option is enabled, only data types having
187190
binary send and receive functions will be transferred in binary.
188191
</para>
189192

190193
<para>
191-
When doing cross-version replication, it could happen that the
194+
When doing cross-version replication, it could be that the
192195
publisher has a binary send function for some data type, but the
193-
subscriber lacks a binary receive function for the type. In
196+
subscriber lacks a binary receive function for that type. In
194197
such a case, data transfer will fail, and
195198
the <literal>binary</literal> option cannot be used.
196199
</para>
@@ -201,8 +204,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
201204
<term><literal>copy_data</literal> (<type>boolean</type>)</term>
202205
<listitem>
203206
<para>
204-
Specifies whether the existing data in the publications that are
205-
being subscribed to should be copied once the replication starts.
207+
Specifies whether to copy pre-existing data in the publications
208+
that are being subscribed to when the replication starts.
206209
The default is <literal>true</literal>.
207210
</para>
208211
</listitem>
@@ -212,9 +215,9 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
212215
<term><literal>streaming</literal> (<type>boolean</type>)</term>
213216
<listitem>
214217
<para>
215-
Specifies whether streaming of in-progress transactions should
216-
be enabled for this subscription. By default, all transactions
217-
are fully decoded on the publisher, and only then sent to the
218+
Specifies whether to enable streaming of in-progress transactions
219+
for this subscription. By default, all transactions
220+
are fully decoded on the publisher and only then sent to the
218221
subscriber as a whole.
219222
</para>
220223
</listitem>
@@ -261,18 +264,22 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
261264
</para>
262265

263266
<para>
264-
When two-phase commit is enabled then the decoded transactions are sent
265-
to the subscriber on the PREPARE TRANSACTION. By default, the transaction
266-
prepared on the publisher is decoded as a normal transaction at commit.
267+
When two-phase commit is enabled, prepared transactions are sent
268+
to the subscriber at the time of <command>PREPARE
269+
TRANSACTION</command>, and are processed as two-phase
270+
transactions on the subscriber too. Otherwise, prepared
271+
transactions are sent to the subscriber only when committed, and
272+
are then processed immediately by the subscriber.
267273
</para>
268274

269275
<para>
270-
The two-phase commit implementation requires that the replication has
271-
successfully passed the initial table synchronization phase. This means
272-
even when two_phase is enabled for the subscription, the internal
273-
two-phase state remains temporarily "pending" until the initialization
274-
phase is completed. See column
275-
<literal>subtwophasestate</literal> of <xref linkend="catalog-pg-subscription"/>
276+
The implementation of two-phase commit requires that replication
277+
has successfully finished the initial table synchronization
278+
phase. So even when <literal>two_phase</literal> is enabled for a
279+
subscription, the internal two-phase state remains
280+
temporarily <quote>pending</quote> until the initialization phase
281+
completes. See column <structfield>subtwophasestate</structfield>
282+
of <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
276283
to know the actual two-phase state.
277284
</para>
278285

0 commit comments

Comments
 (0)