Skip to content

Commit de5a47a

Browse files
author
Amit Kapila
committed
Add XML ID attributes to create_subscription.sgml.
Commit ecb6965 added an XML ID attribute to one varlistentry in create_subscription.sgml. Following 78ee60e, this commit adds XML ID attributes to all varlistentries in create_subscription.sgml. Additionally, links are added to refer to the subscription options, enhancing the readability of documents. Author: Kuroda Hayato Reviewed-by: Peter Smith, Amit Kapila Discussion: https://postgr.es/m/TYAPR01MB58667AE04D291924671E2051F5879@TYAPR01MB5866.jpnprd01.prod.outlook.com
1 parent 00d9dcf commit de5a47a

File tree

5 files changed

+67
-52
lines changed

5 files changed

+67
-52
lines changed

‎doc/src/sgml/config.sgml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11768,8 +11768,9 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
1176811768
On the publisher side, <varname>logical_replication_mode</varname>
1176911769
allows streaming or serializing changes immediately in logical decoding.
1177011770
When set to <literal>immediate</literal>, stream each change if the
11771-
<literal>streaming</literal> option (see optional parameters set by
11772-
<link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>)
11771+
<link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>
11772+
option of
11773+
<link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>
1177311774
is enabled, otherwise, serialize each change. When set to
1177411775
<literal>buffered</literal>, the decoding will stream or serialize
1177511776
changes when <varname>logical_decoding_work_mem</varname> is reached.

‎doc/src/sgml/logical-replication.sgml

Lines changed: 25 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -252,8 +252,9 @@
252252
additional columns not provided by the published table. Any such columns
253253
will be filled with the default value as specified in the definition of the
254254
target table. However, logical replication in binary format is more
255-
restrictive. See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
256-
option</link> of <command>CREATE SUBSCRIPTION</command> for details.
255+
restrictive. See the
256+
<link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>
257+
option of <command>CREATE SUBSCRIPTION</command> for details.
257258
</para>
258259

259260
<sect2 id="logical-replication-subscription-slot">
@@ -587,7 +588,9 @@ ALTER SUBSCRIPTION
587588

588589
<para>
589590
Example 2: Where the subscription says <literal>connect = false</literal>,
590-
but also specifies the <literal>slot_name</literal>
591+
but also specifies the
592+
<link linkend="sql-createsubscription-with-slot-name"><literal>slot_name</literal></link>
593+
option.
591594
<itemizedlist>
592595
<listitem>
593596
<para>
@@ -704,9 +707,10 @@ ALTER SUBSCRIPTION
704707
If the row filter evaluates to <literal>false</literal> or <literal>NULL</literal>
705708
then the row is not replicated. The <literal>WHERE</literal> clause expression
706709
is evaluated with the same role used for the replication connection (i.e.
707-
the role specified in the <literal>CONNECTION</literal> clause of the
708-
<xref linkend="sql-createsubscription"/>). Row filters have no effect for
709-
<command>TRUNCATE</command> command.
710+
the role specified in the
711+
<link linkend="sql-createsubscription-connection"><literal>CONNECTION</literal></link>
712+
clause of the <xref linkend="sql-createsubscription"/>). Row filters have
713+
no effect for <command>TRUNCATE</command> command.
710714
</para>
711715

712716
</sect2>
@@ -1500,9 +1504,10 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
15001504
<function>pg_replication_origin_advance()</function></link> function.
15011505
Before using this function, the subscription needs to be disabled temporarily
15021506
either by <command>ALTER SUBSCRIPTION ... DISABLE</command> or, the
1503-
subscription can be used with the <literal>disable_on_error</literal> option.
1504-
Then, you can use <function>pg_replication_origin_advance()</function> function
1505-
with the <parameter>node_name</parameter> (i.e., <literal>pg_16395</literal>)
1507+
subscription can be used with the
1508+
<link linkend="sql-createsubscription-with-disable-on-error"><literal>disable_on_error</literal></link>
1509+
option. Then, you can use <function>pg_replication_origin_advance()</function>
1510+
function with the <parameter>node_name</parameter> (i.e., <literal>pg_16395</literal>)
15061511
and the next LSN of the finish LSN (i.e., 0/14C0379). The current position of
15071512
origins can be seen in the <link linkend="view-pg-replication-origin-status">
15081513
<structname>pg_replication_origin_status</structname></link> system view.
@@ -1512,11 +1517,13 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
15121517
</para>
15131518

15141519
<para>
1515-
When the streaming mode is <literal>parallel</literal>, the finish LSN of
1516-
failed transactions may not be logged. In that case, it may be necessary to
1517-
change the streaming mode to <literal>on</literal> or <literal>off</literal> and
1518-
cause the same conflicts again so the finish LSN of the failed transaction will
1519-
be written to the server log. For the usage of finish LSN, please refer to <link
1520+
When the
1521+
<link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>
1522+
mode is <literal>parallel</literal>, the finish LSN of failed transactions
1523+
may not be logged. In that case, it may be necessary to change the streaming
1524+
mode to <literal>on</literal> or <literal>off</literal> and cause the same
1525+
conflicts again so the finish LSN of the failed transaction will be written
1526+
to the server log. For the usage of finish LSN, please refer to <link
15201527
linkend="sql-altersubscription"><command>ALTER SUBSCRIPTION ...
15211528
SKIP</command></link>.
15221529
</para>
@@ -1701,8 +1708,10 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
17011708
subscription. A disabled subscription or a crashed subscription will have
17021709
zero rows in this view. If the initial data synchronization of any
17031710
table is in progress, there will be additional workers for the tables
1704-
being synchronized. Moreover, if the streaming transaction is applied in
1705-
parallel, there may be additional parallel apply workers.
1711+
being synchronized. Moreover, if the
1712+
<link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>
1713+
transaction is applied in parallel, there may be additional parallel apply
1714+
workers.
17061715
</para>
17071716
</sect1>
17081717

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

Lines changed: 21 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -71,10 +71,11 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
7171
executed inside a transaction block.
7272

7373
These commands also cannot be executed when the subscription has
74-
<literal>two_phase</literal> commit enabled,
75-
unless <literal>copy_data</literal> is <literal>false</literal>.
76-
See column <structfield>subtwophasestate</structfield> of
77-
<link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
74+
<link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal></link>
75+
commit enabled, unless
76+
<link linkend="sql-createsubscription-with-copy-data"><literal>copy_data</literal></link>
77+
is <literal>false</literal>. See column <structfield>subtwophasestate</structfield>
78+
of <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
7879
to know the actual two-phase state.
7980
</para>
8081
</refsect1>
@@ -175,12 +176,14 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
175176
<para>
176177
See <xref linkend="sql-createsubscription-notes"/> for details of
177178
how <literal>copy_data = true</literal> can interact with the
178-
<literal>origin</literal> parameter.
179+
<link linkend="sql-createsubscription-with-origin"><literal>origin</literal></link>
180+
parameter.
179181
</para>
180182
<para>
181-
See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
182-
option</link> of <command>CREATE SUBSCRIPTION</command> for details
183-
about copying pre-existing data in binary format.
183+
See the
184+
<link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>
185+
parameter of <command>CREATE SUBSCRIPTION</command> for details about
186+
copying pre-existing data in binary format.
184187
</para>
185188
</listitem>
186189
</varlistentry>
@@ -214,12 +217,13 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
214217
<para>
215218
This clause alters parameters originally set by
216219
<xref linkend="sql-createsubscription"/>. See there for more
217-
information. The parameters that can be altered
218-
are <literal>slot_name</literal>,
219-
<literal>synchronous_commit</literal>,
220-
<literal>binary</literal>, <literal>streaming</literal>,
221-
<literal>disable_on_error</literal>, and
222-
<literal>origin</literal>.
220+
information. The parameters that can be altered are
221+
<link linkend="sql-createsubscription-with-slot-name"><literal>slot_name</literal></link>,
222+
<link linkend="sql-createsubscription-with-synchronous-commit"><literal>synchronous_commit</literal></link>,
223+
<link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>,
224+
<link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>,
225+
<link linkend="sql-createsubscription-with-disable-on-error"><literal>disable_on_error</literal></link>,
226+
and <link linkend="sql-createsubscription-with-origin"><literal>origin</literal></link>.
223227
</para>
224228
</listitem>
225229
</varlistentry>
@@ -233,8 +237,9 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
233237
resolved. By using the <command>ALTER SUBSCRIPTION ... SKIP</command> command,
234238
the logical replication worker skips all data modification changes within
235239
the transaction. This option has no effect on the transactions that are
236-
already prepared by enabling <literal>two_phase</literal> on
237-
subscriber.
240+
already prepared by enabling
241+
<link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal></link>
242+
on the subscriber.
238243
After the logical replication worker successfully skips the transaction or
239244
finishes a transaction, the LSN (stored in
240245
<structname>pg_subscription</structname>.<structfield>subskiplsn</structfield>)

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

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
6161
<title>Parameters</title>
6262

6363
<variablelist>
64-
<varlistentry>
64+
<varlistentry id="sql-createsubscription-name">
6565
<term><replaceable class="parameter">subscription_name</replaceable></term>
6666
<listitem>
6767
<para>
@@ -70,7 +70,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
7070
</listitem>
7171
</varlistentry>
7272

73-
<varlistentry>
73+
<varlistentry id="sql-createsubscription-connection">
7474
<term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
7575
<listitem>
7676
<para>
@@ -81,7 +81,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
8181
</listitem>
8282
</varlistentry>
8383

84-
<varlistentry>
84+
<varlistentry id="sql-createsubscription-publication">
8585
<term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable> [, ...]</literal></term>
8686
<listitem>
8787
<para>
@@ -90,7 +90,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
9090
</listitem>
9191
</varlistentry>
9292

93-
<varlistentry>
93+
<varlistentry id="sql-createsubscription-with">
9494
<term><literal>WITH ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
9595
<listitem>
9696
<para>
@@ -102,7 +102,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
102102

103103
<variablelist>
104104

105-
<varlistentry>
105+
<varlistentry id="sql-createsubscription-with-connect">
106106
<term><literal>connect</literal> (<type>boolean</type>)</term>
107107
<listitem>
108108
<para>
@@ -129,7 +129,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
129129
</listitem>
130130
</varlistentry>
131131

132-
<varlistentry>
132+
<varlistentry id="sql-createsubscription-with-create-slot">
133133
<term><literal>create_slot</literal> (<type>boolean</type>)</term>
134134
<listitem>
135135
<para>
@@ -145,7 +145,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
145145
</listitem>
146146
</varlistentry>
147147

148-
<varlistentry>
148+
<varlistentry id="sql-createsubscription-with-enabled">
149149
<term><literal>enabled</literal> (<type>boolean</type>)</term>
150150
<listitem>
151151
<para>
@@ -156,7 +156,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
156156
</listitem>
157157
</varlistentry>
158158

159-
<varlistentry>
159+
<varlistentry id="sql-createsubscription-with-slot-name">
160160
<term><literal>slot_name</literal> (<type>string</type>)</term>
161161
<listitem>
162162
<para>
@@ -185,7 +185,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
185185

186186
<variablelist>
187187

188-
<varlistentry id="sql-createsubscription-binary" xreflabel="binary">
188+
<varlistentry id="sql-createsubscription-with-binary">
189189
<term><literal>binary</literal> (<type>boolean</type>)</term>
190190
<listitem>
191191
<para>
@@ -222,7 +222,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
222222
</listitem>
223223
</varlistentry>
224224

225-
<varlistentry>
225+
<varlistentry id="sql-createsubscription-with-copy-data">
226226
<term><literal>copy_data</literal> (<type>boolean</type>)</term>
227227
<listitem>
228228
<para>
@@ -243,7 +243,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
243243
</listitem>
244244
</varlistentry>
245245

246-
<varlistentry>
246+
<varlistentry id="sql-createsubscription-with-streaming">
247247
<term><literal>streaming</literal> (<type>enum</type>)</term>
248248
<listitem>
249249
<para>
@@ -271,7 +271,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
271271
</listitem>
272272
</varlistentry>
273273

274-
<varlistentry>
274+
<varlistentry id="sql-createsubscription-with-synchronous-commit">
275275
<term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
276276
<listitem>
277277
<para>
@@ -303,7 +303,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
303303
</listitem>
304304
</varlistentry>
305305

306-
<varlistentry>
306+
<varlistentry id="sql-createsubscription-with-two-phase">
307307
<term><literal>two_phase</literal> (<type>boolean</type>)</term>
308308
<listitem>
309309
<para>
@@ -334,7 +334,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
334334
</listitem>
335335
</varlistentry>
336336

337-
<varlistentry>
337+
<varlistentry id="sql-createsubscription-with-disable-on-error">
338338
<term><literal>disable_on_error</literal> (<type>boolean</type>)</term>
339339
<listitem>
340340
<para>
@@ -346,7 +346,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
346346
</listitem>
347347
</varlistentry>
348348

349-
<varlistentry>
349+
<varlistentry id="sql-createsubscription-with-origin">
350350
<term><literal>origin</literal> (<type>string</type>)</term>
351351
<listitem>
352352
<para>

‎doc/src/sgml/ref/pg_dump.sgml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1458,9 +1458,9 @@ CREATE DATABASE foo WITH TEMPLATE template0;
14581458
truncate the target tables before initiating a new full table copy. If users
14591459
intend to copy initial data during refresh they must create the slot with
14601460
<literal>two_phase = false</literal>. After the initial sync, the
1461-
<literal>two_phase</literal> option will be automatically enabled by the
1462-
subscriber if the subscription had been originally created with
1463-
<literal>two_phase = true</literal> option.
1461+
<link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal></link>
1462+
option will be automatically enabled by the subscriber if the subscription
1463+
had been originally created with <literal>two_phase = true</literal> option.
14641464
</para>
14651465
</refsect1>
14661466

0 commit comments

Comments
 (0)