PGdoc: add ID attribute to create_publication.sgml
Started by Hayato Kuroda (Fujitsu)almost 3 years ago6 messages
Dear hackers,
This thread is motivated from [1]/messages/by-id/TYAPR01MB58667AE04D291924671E2051F5879@TYAPR01MB5866.jpnprd01.prod.outlook.com. This patch adds some links that refer publication options.
While adding missing ID attributes to create_subscription.sgml, we found that
this could extend to create_publication.sgml. In the file no entries have an XML
ID attribute, but I think that adding the attribute and links improves the readability.
How do you think?
[1]: /messages/by-id/TYAPR01MB58667AE04D291924671E2051F5879@TYAPR01MB5866.jpnprd01.prod.outlook.com
Best Regards,
Hayato Kuroda
FUJITSU LIMITED
Attachments:
v6-0001-Add-XML-ID-attributes-to-create_subscription.sgml.patchapplication/octet-stream; name=v6-0001-Add-XML-ID-attributes-to-create_subscription.sgml.patchDownload
From 6028ae381ad391651aa3eedf8d9e608981a715c0 Mon Sep 17 00:00:00 2001
From: Hayato Kuroda <kuroda.hayato@fujitsu.com>
Date: Wed, 22 Mar 2023 10:14:22 +0000
Subject: [PATCH v6] Add XML ID attributes to create_subscription.sgml
In commit ecb696, an XML ID attribute was added to only one varlistentry,
creating inconsistency with the commit 78ee60. This commit adds XML ID
attributes to all varlistentries in create_subscription.sgml for consistency.
Additionally, links are added to refer to the subscription options, enhancing
the readability of documents.
---
doc/src/sgml/config.sgml | 7 ++--
doc/src/sgml/logical-replication.sgml | 44 +++++++++++---------
doc/src/sgml/ref/alter_subscription.sgml | 49 ++++++++++++-----------
doc/src/sgml/ref/create_subscription.sgml | 30 +++++++-------
doc/src/sgml/ref/pg_dump.sgml | 7 ++--
5 files changed, 75 insertions(+), 62 deletions(-)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 71730cc52f..a1c36b4353 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -11742,9 +11742,10 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
On the publisher side, <varname>logical_replication_mode</varname>
allows streaming or serializing changes immediately in logical decoding.
When set to <literal>immediate</literal>, stream each change if the
- <literal>streaming</literal> option (see optional parameters set by
- <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>)
- is enabled, otherwise, serialize each change. When set to
+ <link linkend="sql-createsubscription-with-streaming">
+ <literal>streaming</literal></link> option of <link
+ linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command>
+ </link> is enabled, otherwise, serialize each change. When set to
<literal>buffered</literal>, the decoding will stream or serialize
changes when <varname>logical_decoding_work_mem</varname> is reached.
</para>
diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 3836d13ad3..3540be08e7 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -252,8 +252,9 @@
additional columns not provided by the published table. Any such columns
will be filled with the default value as specified in the definition of the
target table. However, logical replication in binary format is more
- restrictive. See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
- option</link> of <command>CREATE SUBSCRIPTION</command> for details.
+ restrictive. See the <link linkend="sql-createsubscription-with-binary">
+ <literal>binary</literal></link> option of <command>CREATE SUBSCRIPTION</command>
+ for details.
</para>
<sect2 id="logical-replication-subscription-slot">
@@ -587,7 +588,8 @@ ALTER SUBSCRIPTION
<para>
Example 2: Where the subscription says <literal>connect = false</literal>,
- but also specifies the <literal>slot_name</literal>
+ but also specifies the <link linkend="sql-createsubscription-with-slot-name">
+ <literal>slot_name</literal></link> option.
<itemizedlist>
<listitem>
<para>
@@ -704,8 +706,9 @@ ALTER SUBSCRIPTION
If the row filter evaluates to <literal>false</literal> or <literal>NULL</literal>
then the row is not replicated. The <literal>WHERE</literal> clause expression
is evaluated with the same role used for the replication connection (i.e.
- the role specified in the <literal>CONNECTION</literal> clause of the
- <xref linkend="sql-createsubscription"/>). Row filters have no effect for
+ the role specified in the <link linkend="sql-createsubscription-connection">
+ <literal>CONNECTION</literal></link> clause of the <xref
+ linkend="sql-createsubscription"/>). Row filters have no effect for
<command>TRUNCATE</command> command.
</para>
@@ -1500,10 +1503,12 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
<function>pg_replication_origin_advance()</function></link> function.
Before using this function, the subscription needs to be disabled temporarily
either by <command>ALTER SUBSCRIPTION ... DISABLE</command> or, the
- subscription can be used with the <literal>disable_on_error</literal> option.
- Then, you can use <function>pg_replication_origin_advance()</function> function
- with the <parameter>node_name</parameter> (i.e., <literal>pg_16395</literal>)
- and the next LSN of the finish LSN (i.e., 0/14C0379). The current position of
+ subscription can be used with the <link
+ linkend="sql-createsubscription-with-disable-on-error">
+ <literal>disable_on_error</literal></link> option. Then, you can use
+ <function>pg_replication_origin_advance()</function> function with the
+ <parameter>node_name</parameter> (i.e., <literal>pg_16395</literal>) and the
+ next LSN of the finish LSN (i.e., 0/14C0379). The current position of
origins can be seen in the <link linkend="view-pg-replication-origin-status">
<structname>pg_replication_origin_status</structname></link> system view.
Please note that skipping the whole transaction includes skipping changes that
@@ -1512,13 +1517,14 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
</para>
<para>
- When the streaming mode is <literal>parallel</literal>, the finish LSN of
- failed transactions may not be logged. In that case, it may be necessary to
- change the streaming mode to <literal>on</literal> or <literal>off</literal> and
- cause the same conflicts again so the finish LSN of the failed transaction will
- be written to the server log. For the usage of finish LSN, please refer to <link
- linkend="sql-altersubscription"><command>ALTER SUBSCRIPTION ...
- SKIP</command></link>.
+ When the <link linkend="sql-createsubscription-with-streaming">
+ <literal>streaming</literal></link> mode is <literal>parallel</literal>, the
+ finish LSN of failed transactions may not be logged. In that case, it may be
+ necessary to change the streaming mode to <literal>on</literal> or
+ <literal>off</literal> and cause the same conflicts again so the finish LSN
+ of the failed transaction will be written to the server log. For the usage
+ of finish LSN, please refer to <link linkend="sql-altersubscription">
+ <command>ALTER SUBSCRIPTION ... SKIP</command></link>.
</para>
</sect1>
@@ -1701,8 +1707,10 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
subscription. A disabled subscription or a crashed subscription will have
zero rows in this view. If the initial data synchronization of any
table is in progress, there will be additional workers for the tables
- being synchronized. Moreover, if the streaming transaction is applied in
- parallel, there may be additional parallel apply workers.
+ being synchronized. Moreover, if the <link
+ linkend="sql-createsubscription-with-streaming"><literal>streaming</literal>
+ </link> transaction is applied in parallel, there may be additional parallel
+ apply workers.
</para>
</sect1>
diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml
index e92346edef..a7e1e6bb41 100644
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -71,11 +71,12 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
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</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.
+ <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal>
+ </link> commit enabled, unless <link linkend="sql-createsubscription-with-copy-data">
+ <literal>copy_data</literal></link> 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>
@@ -175,12 +176,14 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
<para>
See <xref linkend="sql-createsubscription-notes"/> for details of
how <literal>copy_data = true</literal> can interact with the
- <literal>origin</literal> parameter.
+ <link linkend="sql-createsubscription-with-origin">
+ <literal>origin</literal></link> parameter.
</para>
<para>
- See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
- option</link> of <command>CREATE SUBSCRIPTION</command> for details
- about copying pre-existing data in binary format.
+ See the <link linkend="sql-createsubscription-with-binary">
+ <literal>binary</literal></link> parameter of
+ <command>CREATE SUBSCRIPTION</command> for details about copying
+ pre-existing data in binary format.
</para>
</listitem>
</varlistentry>
@@ -214,12 +217,13 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
<para>
This clause alters parameters originally set by
<xref linkend="sql-createsubscription"/>. See there for more
- information. The parameters that can be altered
- are <literal>slot_name</literal>,
- <literal>synchronous_commit</literal>,
- <literal>binary</literal>, <literal>streaming</literal>,
- <literal>disable_on_error</literal>, and
- <literal>origin</literal>.
+ information. The parameters that can be altered are
+ <link linkend="sql-createsubscription-with-slot-name"><literal>slot_name</literal></link>,
+ <link linkend="sql-createsubscription-with-synchronous-commit"><literal>synchronous_commit</literal></link>,
+ <link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>,
+ <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>,
+ <link linkend="sql-createsubscription-with-disable-on-error"><literal>disable_on_error</literal></link>,
+ and <link linkend="sql-createsubscription-with-origin"><literal>origin</literal></link>.
</para>
</listitem>
</varlistentry>
@@ -233,14 +237,13 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
resolved. By using the <command>ALTER SUBSCRIPTION ... SKIP</command> command,
the logical replication worker skips all data modification changes within
the transaction. This option has no effect on the transactions that are
- already prepared by enabling <literal>two_phase</literal> on
- subscriber.
- After the logical replication worker successfully skips the transaction or
- finishes a transaction, the LSN (stored in
- <structname>pg_subscription</structname>.<structfield>subskiplsn</structfield>)
- is cleared. See <xref linkend="logical-replication-conflicts"/> for
- the details of logical replication conflicts. Using this command requires
- superuser privilege.
+ already prepared by enabling <link linkend="sql-createsubscription-with-two-phase">
+ <literal>two_phase</literal></link> on the subscriber. After the logical
+ replication worker successfully skips the transaction or finishes a
+ transaction, the LSN (stored in <structname>pg_subscription</structname>.
+ <structfield>subskiplsn</structfield>) is cleared. See <xref
+ linkend="logical-replication-conflicts"/> for the details of logical
+ replication conflicts. Using this command requires superuser privilege.
</para>
<para>
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 9d4b9d4e33..a66b8025f3 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -61,7 +61,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<title>Parameters</title>
<variablelist>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-name">
<term><replaceable class="parameter">subscription_name</replaceable></term>
<listitem>
<para>
@@ -70,7 +70,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-connection">
<term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
<listitem>
<para>
@@ -81,7 +81,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-publication">
<term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable> [, ...]</literal></term>
<listitem>
<para>
@@ -90,7 +90,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with">
<term><literal>WITH ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
<listitem>
<para>
@@ -102,7 +102,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<variablelist>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-connect">
<term><literal>connect</literal> (<type>boolean</type>)</term>
<listitem>
<para>
@@ -129,7 +129,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-create-slot">
<term><literal>create_slot</literal> (<type>boolean</type>)</term>
<listitem>
<para>
@@ -145,7 +145,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-enabled">
<term><literal>enabled</literal> (<type>boolean</type>)</term>
<listitem>
<para>
@@ -156,7 +156,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-slot-name">
<term><literal>slot_name</literal> (<type>string</type>)</term>
<listitem>
<para>
@@ -185,7 +185,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<variablelist>
- <varlistentry id="sql-createsubscription-binary" xreflabel="binary">
+ <varlistentry id="sql-createsubscription-with-binary">
<term><literal>binary</literal> (<type>boolean</type>)</term>
<listitem>
<para>
@@ -222,7 +222,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-copy-data">
<term><literal>copy_data</literal> (<type>boolean</type>)</term>
<listitem>
<para>
@@ -243,7 +243,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-streaming">
<term><literal>streaming</literal> (<type>enum</type>)</term>
<listitem>
<para>
@@ -271,7 +271,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-synchronous-commit">
<term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
<listitem>
<para>
@@ -303,7 +303,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-two-phase">
<term><literal>two_phase</literal> (<type>boolean</type>)</term>
<listitem>
<para>
@@ -334,7 +334,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-disable-on-error">
<term><literal>disable_on_error</literal> (<type>boolean</type>)</term>
<listitem>
<para>
@@ -346,7 +346,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-origin">
<term><literal>origin</literal> (<type>string</type>)</term>
<listitem>
<para>
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index d6b1faa804..679fa727cd 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1458,9 +1458,10 @@ CREATE DATABASE foo WITH TEMPLATE template0;
truncate the target tables before initiating a new full table copy. If users
intend to copy initial data during refresh they must create the slot with
<literal>two_phase = false</literal>. After the initial sync, the
- <literal>two_phase</literal> option will be automatically enabled by the
- subscriber if the subscription had been originally created with
- <literal>two_phase = true</literal> option.
+ <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal>
+ </link> option will be automatically enabled by the subscriber if the
+ subscription had been originally created with <literal>two_phase = true</literal>
+ option.
</para>
</refsect1>
--
2.27.0
Re: PGdoc: add ID attribute to create_publication.sgml
On Thu, Mar 30, 2023 at 12:57 PM Hayato Kuroda (Fujitsu)
<kuroda.hayato@fujitsu.com> wrote:
Dear hackers,
This thread is motivated from [1]. This patch adds some links that refer publication options.
Is this the correct attachment?
------
Kind Regards,
Peter Smith,
Fujitsu Australia
RE: PGdoc: add ID attribute to create_publication.sgml
Dear Peter,
This thread is motivated from [1]. This patch adds some links that refer
publication options.
Is this the correct attachment?
Opps, I attached wrong one. Here is currect.
Best Regards,
Hayato Kuroda
FUJITSU LIMITED
Attachments:
0001-Add-XML-ID-attributes-to-create_publication.sgml.patchapplication/octet-stream; name=0001-Add-XML-ID-attributes-to-create_publication.sgml.patchDownload
From 62969ccf1346ef68dc19694998cfa117191cef56 Mon Sep 17 00:00:00 2001
From: Hayato Kuroda <kuroda.hayato@fujitsu.com>
Date: Fri, 24 Mar 2023 11:00:53 +0000
Subject: [PATCH] Add XML ID attributes to create_publication.sgml
This commit adds XML ID attributes to all varlistentries in
create_publication.sgml. Additionally, links are included to refer to publication
options, making documents more readable.
---
doc/src/sgml/logical-replication.sgml | 68 +++++++++++++----------
doc/src/sgml/ref/alter_publication.sgml | 8 ++-
doc/src/sgml/ref/create_publication.sgml | 14 ++---
doc/src/sgml/ref/create_subscription.sgml | 22 ++++----
doc/src/sgml/system-views.sgml | 7 ++-
5 files changed, 68 insertions(+), 51 deletions(-)
diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 6358c5da05..10ada41d80 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -367,7 +367,8 @@ INSERT 0 3
<para>
Create publications for the tables. The publications <literal>pub2</literal>
- and <literal>pub3a</literal> disallow some <literal>publish</literal>
+ and <literal>pub3a</literal> disallow some
+ <link linkend="sql-createpublication-with-publish"><literal>publish</literal></link>
operations. The publication <literal>pub3b</literal> has a row filter (see
<xref linkend="logical-replication-row-filter"/>).
<programlisting>
@@ -801,11 +802,12 @@ ALTER SUBSCRIPTION
<para>
If the publication contains a partitioned table, the publication parameter
- <literal>publish_via_partition_root</literal> determines which row filter
- is used. If <literal>publish_via_partition_root</literal> is <literal>true</literal>,
- the <emphasis>root partitioned table's</emphasis> row filter is used. Otherwise,
- if <literal>publish_via_partition_root</literal> is <literal>false</literal>
- (default), each <emphasis>partition's</emphasis> row filter is used.
+ <link linkend="sql-createpublication-with-publish-via-partition-root"><literal>publish_via_partition_root</literal></link>
+ determines which row filter is used. If <literal>publish_via_partition_root</literal>
+ is <literal>true</literal>, the <emphasis>root partitioned table's</emphasis>
+ row filter is used. Otherwise, if <literal>publish_via_partition_root</literal>
+ is <literal>false</literal> (default), each <emphasis>partition's</emphasis>
+ row filter is used.
</para>
</sect2>
@@ -829,8 +831,9 @@ ALTER SUBSCRIPTION
<warning>
<para>
Because initial data synchronization does not take into account the
- <literal>publish</literal> parameter when copying existing table data,
- some rows may be copied that would not be replicated using DML. Refer to
+ <link linkend="sql-createpublication-with-publish"><literal>publish</literal></link>
+ parameter when copying existing table data, some rows may be copied that
+ would not be replicated using DML. Refer to
<xref linkend="logical-replication-snapshot"/>, and see
<xref linkend="logical-replication-subscription-examples"/> for examples.
</para>
@@ -851,7 +854,8 @@ ALTER SUBSCRIPTION
<para>
If the subscription has several publications in which the same table has
- been published with different row filters (for the same <literal>publish</literal>
+ been published with different row filters (for the same
+ <link linkend="sql-createpublication-with-publish"><literal>publish</literal></link>
operation), those expressions get ORed together, so that rows satisfying
<emphasis>any</emphasis> of the expressions will be replicated. This means all
the other row filters for the same table become redundant if:
@@ -863,15 +867,17 @@ ALTER SUBSCRIPTION
</listitem>
<listitem>
<para>
- One of the publications was created using <literal>FOR ALL TABLES</literal>.
+ One of the publications was created using
+ <link linkend="sql-createpublication-for-all-tables"><literal>FOR ALL TABLES</literal></link>.
This clause does not allow row filters.
</para>
</listitem>
<listitem>
<para>
One of the publications was created using
- <literal>FOR TABLES IN SCHEMA</literal> and the table belongs to
- the referred schema. This clause does not allow row filters.
+ <link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>
+ and the table belongs to the referred schema. This clause does not allow
+ row filters.
</para>
</listitem>
</itemizedlist></para>
@@ -1136,9 +1142,9 @@ test_sub=# SELECT * FROM t1;
<para>
The following examples show how the publication parameter
- <literal>publish_via_partition_root</literal> determines whether the row
- filter of the parent or child table will be used in the case of partitioned
- tables.
+ <link linkend="sql-createpublication-with-publish-via-partition-root"><literal>publish_via_partition_root</literal></link>
+ determines whether the row filter of the parent or child table will be used
+ in the case of partitioned tables.
</para>
<para>
@@ -1291,15 +1297,16 @@ test_sub=# SELECT * FROM child ORDER BY a;
<para>
Specifying a column list when the publication also publishes
- <literal>FOR TABLES IN SCHEMA</literal> is not supported.
+ <link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>
+ is not supported.
</para>
<para>
For partitioned tables, the publication parameter
- <literal>publish_via_partition_root</literal> determines which column list
- is used. If <literal>publish_via_partition_root</literal> is
- <literal>true</literal>, the root partitioned table's column list is used.
- Otherwise, if <literal>publish_via_partition_root</literal> is
+ <link linkend="sql-createpublication-with-publish-via-partition-root"><literal>publish_via_partition_root</literal></link>
+ determines which column list is used. If <literal>publish_via_partition_root</literal>
+ is <literal>true</literal>, the root partitioned table's column list is
+ used. Otherwise, if <literal>publish_via_partition_root</literal> is
<literal>false</literal> (the default), each partition's column list is used.
</para>
@@ -1610,7 +1617,9 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
tables.) Publications can also specify that changes are to be replicated
using the identity and schema of the partitioned root table instead of
that of the individual leaf partitions in which the changes actually
- originate (see <link linkend="sql-createpublication"><command>CREATE PUBLICATION</command></link>).
+ originate (see
+ <link linkend="sql-createpublication-with-publish-via-partition-root"><literal>publish_via_partition_root</literal></link>
+ parameter of <command>CREATE PUBLICATION</command>).
</para>
</listitem>
</itemizedlist>
@@ -1676,9 +1685,11 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
</para>
<note>
<para>
- The publication <literal>publish</literal> parameter only affects what
- DML operations will be replicated. The initial data synchronization does
- not take this parameter into account when copying the existing table data.
+ The publication
+ <link linkend="sql-createpublication-with-publish"><literal>publish</literal></link>
+ parameter only affects what DML operations will be replicated. The
+ initial data synchronization does not take this parameter into account
+ when copying the existing table data.
</para>
</note>
</sect2>
@@ -1724,10 +1735,11 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
and <literal>TRIGGER</literal> privilege on such tables to trusted roles.
Moreover, if untrusted users can create tables, use only
publications that list tables explicitly. That is to say, create a
- subscription <literal>FOR ALL TABLES</literal> or
- <literal>FOR TABLES IN SCHEMA</literal> only when superusers trust
- every user permitted to create a non-temp table on the publisher or the
- subscriber.
+ subscription
+ <link linkend="sql-createpublication-for-all-tables"><literal>FOR ALL TABLES</literal></link>
+ or <link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>
+ only when superusers trust every user permitted to create a non-temp table
+ on the publisher or the subscriber.
</para>
<para>
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index cd20868bca..c8424bca15 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -54,7 +54,8 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
<literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> action on the
subscribing side in order to become effective. Note also that
<literal>DROP TABLES IN SCHEMA</literal> will not drop any schema tables
- that were specified using <literal>FOR TABLE</literal>/
+ that were specified using
+ <link linkend="sql-createpublication-for-table"><literal>FOR TABLE</literal></link>/
<literal>ADD TABLE</literal>, and the combination of <literal>DROP</literal>
with a <literal>WHERE</literal> clause is not allowed.
</para>
@@ -79,8 +80,9 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
To alter the owner, you must be able to <literal>SET ROLE</literal> to the
new owning role, and that role must have <literal>CREATE</literal>
privilege on the database.
- Also, the new owner of a <literal>FOR ALL TABLES</literal> or
- <literal>FOR TABLES IN SCHEMA</literal>
+ Also, the new owner of a
+ <link linkend="sql-createpublication-for-all-tables"><literal>FOR ALL TABLES</literal></link>
+ or <link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>
publication must be a superuser. However, a superuser can
change the ownership of a publication regardless of these restrictions.
</para>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index b2540c63ff..e3e1d04e73 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -54,7 +54,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
<title>Parameters</title>
<variablelist>
- <varlistentry>
+ <varlistentry id="sql-createpublication-name">
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
@@ -63,7 +63,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createpublication-for-table">
<term><literal>FOR TABLE</literal></term>
<listitem>
<para>
@@ -117,7 +117,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createpublication-for-all-tables">
<term><literal>FOR ALL TABLES</literal></term>
<listitem>
<para>
@@ -127,7 +127,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createpublication-for-tables-in-schema">
<term><literal>FOR TABLES IN SCHEMA</literal></term>
<listitem>
<para>
@@ -158,7 +158,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createpublication-with">
<term><literal>WITH ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
<listitem>
<para>
@@ -166,7 +166,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
following parameters are supported:
<variablelist>
- <varlistentry>
+ <varlistentry id="sql-createpublication-with-publish">
<term><literal>publish</literal> (<type>string</type>)</term>
<listitem>
<para>
@@ -188,7 +188,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createpublication-with-publish-via-partition-root">
<term><literal>publish_via_partition_root</literal> (<type>boolean</type>)</term>
<listitem>
<para>
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index a66b8025f3..b760388f7d 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -418,16 +418,18 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
the case of different <literal>WHERE</literal> clauses, if one of the
publications has no <literal>WHERE</literal> clause (referring to that
publish operation) or the publication is declared as
- <literal>FOR ALL TABLES</literal> or
- <literal>FOR TABLES IN SCHEMA</literal>, rows are always published
- regardless of the definition of the other expressions.
- If the subscriber is a <productname>PostgreSQL</productname> version before
- 15, then any row filtering is ignored during the initial data synchronization
- phase. For this case, the user might want to consider deleting any initially
- copied data that would be incompatible with subsequent filtering.
- Because initial data synchronization does not take into account the publication
- <literal>publish</literal> parameter when copying existing table data, some rows
- may be copied that would not be replicated using DML. See
+ <link linkend="sql-createpublication-for-all-tables"><literal>FOR ALL TABLES</literal></link>
+ or <link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>,
+ rows are always published regardless of the definition of the other
+ expressions. If the subscriber is a <productname>PostgreSQL</productname>
+ version before 15, then any row filtering is ignored during the initial data
+ synchronization phase. For this case, the user might want to consider
+ deleting any initially copied data that would be incompatible with
+ subsequent filtering. Because initial data synchronization does not take
+ into account the publication
+ <link linkend="sql-createpublication-with-publish"><literal>publish</literal></link>
+ parameter when copying existing table data, some rows may be copied that
+ would not be replicated using DML. See
<xref linkend="logical-replication-subscription-examples"/> for examples.
</para>
diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml
index 7c8fc3f654..bb1a418450 100644
--- a/doc/src/sgml/system-views.sgml
+++ b/doc/src/sgml/system-views.sgml
@@ -2145,9 +2145,10 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
information about the mapping between publications and information of
tables they contain. Unlike the underlying catalog
<link linkend="catalog-pg-publication-rel"><structname>pg_publication_rel</structname></link>,
- this view expands publications defined as <literal>FOR ALL TABLES</literal>
- and <literal>FOR TABLES IN SCHEMA</literal>, so for such publications
- there will be a row for each eligible table.
+ this view expands publications defined as
+ <link linkend="sql-createpublication-for-all-tables"><literal>FOR ALL TABLES</literal></link>
+ and <link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>,
+ so for such publications there will be a row for each eligible table.
</para>
<table>
--
2.27.0
Re: PGdoc: add ID attribute to create_publication.sgml
Hi Kuroda-san.
This patch had already gone through several review cycles when it was
known as v5-0002, in the previous thread [1]/messages/by-id/TYAPR01MB5866879FFE5E0A2726244216F5889@TYAPR01MB5866.jpnprd01.prod.outlook.com, so it is already LGTM.
Just to be sure, I applied it again, rebuilt the HTML docs, and
re-checked all the rendering.
I have marked the CF entry for this patch as "ready for committer"
------
[1]: /messages/by-id/TYAPR01MB5866879FFE5E0A2726244216F5889@TYAPR01MB5866.jpnprd01.prod.outlook.com
[2]: https://commitfest.postgresql.org/43/4260/
Kind Regards,
Peter Smith.
Fujitsu Australia
Re: PGdoc: add ID attribute to create_publication.sgml
On Thu, Mar 30, 2023 at 9:22 AM Peter Smith <smithpb2250@gmail.com> wrote:
I have marked the CF entry for this patch as "ready for committer"
LGTM. I'll push this tomorrow unless there are more comments for it.
--
With Regards,
Amit Kapila.
Re: PGdoc: add ID attribute to create_publication.sgml
On Thu, Mar 30, 2023 at 3:48 PM Amit Kapila <amit.kapila16@gmail.com> wrote:
On Thu, Mar 30, 2023 at 9:22 AM Peter Smith <smithpb2250@gmail.com> wrote:
I have marked the CF entry for this patch as "ready for committer"
LGTM. I'll push this tomorrow unless there are more comments for it.
Pushed.
--
With Regards,
Amit Kapila.