Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit ed94e85

Browse files
author
Amit Kapila
committed
Add XML ID attributes to create_publication.sgml.
This commit adds XML ID attributes to all varlistentries in create_publication.sgml. This allows us to include links to refer to publication options, making documents more readable. Author: Kuroda Hayato Reviewed-by: Peter Smith, Amit Kapila Discussion: https://postgr.es/m/TYAPR01MB58668219FEA4EC231486A433F58E9@TYAPR01MB5866.jpnprd01.prod.outlook.com
1 parent f95c1cd commit ed94e85

5 files changed

+68
-51
lines changed

doc/src/sgml/logical-replication.sgml

+40-28
Original file line numberDiff line numberDiff line change
@@ -367,7 +367,8 @@ INSERT 0 3
367367

368368
<para>
369369
Create publications for the tables. The publications <literal>pub2</literal>
370-
and <literal>pub3a</literal> disallow some <literal>publish</literal>
370+
and <literal>pub3a</literal> disallow some
371+
<link linkend="sql-createpublication-with-publish"><literal>publish</literal></link>
371372
operations. The publication <literal>pub3b</literal> has a row filter (see
372373
<xref linkend="logical-replication-row-filter"/>).
373374
<programlisting>
@@ -801,11 +802,12 @@ ALTER SUBSCRIPTION
801802

802803
<para>
803804
If the publication contains a partitioned table, the publication parameter
804-
<literal>publish_via_partition_root</literal> determines which row filter
805-
is used. If <literal>publish_via_partition_root</literal> is <literal>true</literal>,
806-
the <emphasis>root partitioned table's</emphasis> row filter is used. Otherwise,
807-
if <literal>publish_via_partition_root</literal> is <literal>false</literal>
808-
(default), each <emphasis>partition's</emphasis> row filter is used.
805+
<link linkend="sql-createpublication-with-publish-via-partition-root"><literal>publish_via_partition_root</literal></link>
806+
determines which row filter is used. If <literal>publish_via_partition_root</literal>
807+
is <literal>true</literal>, the <emphasis>root partitioned table's</emphasis>
808+
row filter is used. Otherwise, if <literal>publish_via_partition_root</literal>
809+
is <literal>false</literal> (default), each <emphasis>partition's</emphasis>
810+
row filter is used.
809811
</para>
810812

811813
</sect2>
@@ -829,8 +831,9 @@ ALTER SUBSCRIPTION
829831
<warning>
830832
<para>
831833
Because initial data synchronization does not take into account the
832-
<literal>publish</literal> parameter when copying existing table data,
833-
some rows may be copied that would not be replicated using DML. Refer to
834+
<link linkend="sql-createpublication-with-publish"><literal>publish</literal></link>
835+
parameter when copying existing table data, some rows may be copied that
836+
would not be replicated using DML. Refer to
834837
<xref linkend="logical-replication-snapshot"/>, and see
835838
<xref linkend="logical-replication-subscription-examples"/> for examples.
836839
</para>
@@ -851,7 +854,8 @@ ALTER SUBSCRIPTION
851854

852855
<para>
853856
If the subscription has several publications in which the same table has
854-
been published with different row filters (for the same <literal>publish</literal>
857+
been published with different row filters (for the same
858+
<link linkend="sql-createpublication-with-publish"><literal>publish</literal></link>
855859
operation), those expressions get ORed together, so that rows satisfying
856860
<emphasis>any</emphasis> of the expressions will be replicated. This means all
857861
the other row filters for the same table become redundant if:
@@ -863,15 +867,17 @@ ALTER SUBSCRIPTION
863867
</listitem>
864868
<listitem>
865869
<para>
866-
One of the publications was created using <literal>FOR ALL TABLES</literal>.
870+
One of the publications was created using
871+
<link linkend="sql-createpublication-for-all-tables"><literal>FOR ALL TABLES</literal></link>.
867872
This clause does not allow row filters.
868873
</para>
869874
</listitem>
870875
<listitem>
871876
<para>
872877
One of the publications was created using
873-
<literal>FOR TABLES IN SCHEMA</literal> and the table belongs to
874-
the referred schema. This clause does not allow row filters.
878+
<link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>
879+
and the table belongs to the referred schema. This clause does not allow
880+
row filters.
875881
</para>
876882
</listitem>
877883
</itemizedlist></para>
@@ -1136,9 +1142,9 @@ test_sub=# SELECT * FROM t1;
11361142

11371143
<para>
11381144
The following examples show how the publication parameter
1139-
<literal>publish_via_partition_root</literal> determines whether the row
1140-
filter of the parent or child table will be used in the case of partitioned
1141-
tables.
1145+
<link linkend="sql-createpublication-with-publish-via-partition-root"><literal>publish_via_partition_root</literal></link>
1146+
determines whether the row filter of the parent or child table will be used
1147+
in the case of partitioned tables.
11421148
</para>
11431149

11441150
<para>
@@ -1291,15 +1297,16 @@ test_sub=# SELECT * FROM child ORDER BY a;
12911297

12921298
<para>
12931299
Specifying a column list when the publication also publishes
1294-
<literal>FOR TABLES IN SCHEMA</literal> is not supported.
1300+
<link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>
1301+
is not supported.
12951302
</para>
12961303

12971304
<para>
12981305
For partitioned tables, the publication parameter
1299-
<literal>publish_via_partition_root</literal> determines which column list
1300-
is used. If <literal>publish_via_partition_root</literal> is
1301-
<literal>true</literal>, the root partitioned table's column list is used.
1302-
Otherwise, if <literal>publish_via_partition_root</literal> is
1306+
<link linkend="sql-createpublication-with-publish-via-partition-root"><literal>publish_via_partition_root</literal></link>
1307+
determines which column list is used. If <literal>publish_via_partition_root</literal>
1308+
is <literal>true</literal>, the root partitioned table's column list is
1309+
used. Otherwise, if <literal>publish_via_partition_root</literal> is
13031310
<literal>false</literal> (the default), each partition's column list is used.
13041311
</para>
13051312

@@ -1610,7 +1617,9 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
16101617
tables.) Publications can also specify that changes are to be replicated
16111618
using the identity and schema of the partitioned root table instead of
16121619
that of the individual leaf partitions in which the changes actually
1613-
originate (see <link linkend="sql-createpublication"><command>CREATE PUBLICATION</command></link>).
1620+
originate (see
1621+
<link linkend="sql-createpublication-with-publish-via-partition-root"><literal>publish_via_partition_root</literal></link>
1622+
parameter of <command>CREATE PUBLICATION</command>).
16141623
</para>
16151624
</listitem>
16161625
</itemizedlist>
@@ -1676,9 +1685,11 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
16761685
</para>
16771686
<note>
16781687
<para>
1679-
The publication <literal>publish</literal> parameter only affects what
1680-
DML operations will be replicated. The initial data synchronization does
1681-
not take this parameter into account when copying the existing table data.
1688+
The publication
1689+
<link linkend="sql-createpublication-with-publish"><literal>publish</literal></link>
1690+
parameter only affects what DML operations will be replicated. The
1691+
initial data synchronization does not take this parameter into account
1692+
when copying the existing table data.
16821693
</para>
16831694
</note>
16841695
</sect2>
@@ -1724,10 +1735,11 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
17241735
and <literal>TRIGGER</literal> privilege on such tables to trusted roles.
17251736
Moreover, if untrusted users can create tables, use only
17261737
publications that list tables explicitly. That is to say, create a
1727-
subscription <literal>FOR ALL TABLES</literal> or
1728-
<literal>FOR TABLES IN SCHEMA</literal> only when superusers trust
1729-
every user permitted to create a non-temp table on the publisher or the
1730-
subscriber.
1738+
subscription
1739+
<link linkend="sql-createpublication-for-all-tables"><literal>FOR ALL TABLES</literal></link>
1740+
or <link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>
1741+
only when superusers trust every user permitted to create a non-temp table
1742+
on the publisher or the subscriber.
17311743
</para>
17321744

17331745
<para>

doc/src/sgml/ref/alter_publication.sgml

+5-3
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,8 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
5454
<literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> action on the
5555
subscribing side in order to become effective. Note also that
5656
<literal>DROP TABLES IN SCHEMA</literal> will not drop any schema tables
57-
that were specified using <literal>FOR TABLE</literal>/
57+
that were specified using
58+
<link linkend="sql-createpublication-for-table"><literal>FOR TABLE</literal></link>/
5859
<literal>ADD TABLE</literal>, and the combination of <literal>DROP</literal>
5960
with a <literal>WHERE</literal> clause is not allowed.
6061
</para>
@@ -79,8 +80,9 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
7980
To alter the owner, you must be able to <literal>SET ROLE</literal> to the
8081
new owning role, and that role must have <literal>CREATE</literal>
8182
privilege on the database.
82-
Also, the new owner of a <literal>FOR ALL TABLES</literal> or
83-
<literal>FOR TABLES IN SCHEMA</literal>
83+
Also, the new owner of a
84+
<link linkend="sql-createpublication-for-all-tables"><literal>FOR ALL TABLES</literal></link>
85+
or <link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>
8486
publication must be a superuser. However, a superuser can
8587
change the ownership of a publication regardless of these restrictions.
8688
</para>

doc/src/sgml/ref/create_publication.sgml

+7-7
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
5454
<title>Parameters</title>
5555

5656
<variablelist>
57-
<varlistentry>
57+
<varlistentry id="sql-createpublication-name">
5858
<term><replaceable class="parameter">name</replaceable></term>
5959
<listitem>
6060
<para>
@@ -63,7 +63,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
6363
</listitem>
6464
</varlistentry>
6565

66-
<varlistentry>
66+
<varlistentry id="sql-createpublication-for-table">
6767
<term><literal>FOR TABLE</literal></term>
6868
<listitem>
6969
<para>
@@ -117,7 +117,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
117117
</listitem>
118118
</varlistentry>
119119

120-
<varlistentry>
120+
<varlistentry id="sql-createpublication-for-all-tables">
121121
<term><literal>FOR ALL TABLES</literal></term>
122122
<listitem>
123123
<para>
@@ -127,7 +127,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
127127
</listitem>
128128
</varlistentry>
129129

130-
<varlistentry>
130+
<varlistentry id="sql-createpublication-for-tables-in-schema">
131131
<term><literal>FOR TABLES IN SCHEMA</literal></term>
132132
<listitem>
133133
<para>
@@ -158,15 +158,15 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
158158
</listitem>
159159
</varlistentry>
160160

161-
<varlistentry>
161+
<varlistentry id="sql-createpublication-with">
162162
<term><literal>WITH ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
163163
<listitem>
164164
<para>
165165
This clause specifies optional parameters for a publication. The
166166
following parameters are supported:
167167

168168
<variablelist>
169-
<varlistentry>
169+
<varlistentry id="sql-createpublication-with-publish">
170170
<term><literal>publish</literal> (<type>string</type>)</term>
171171
<listitem>
172172
<para>
@@ -188,7 +188,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
188188
</listitem>
189189
</varlistentry>
190190

191-
<varlistentry>
191+
<varlistentry id="sql-createpublication-with-publish-via-partition-root">
192192
<term><literal>publish_via_partition_root</literal> (<type>boolean</type>)</term>
193193
<listitem>
194194
<para>

doc/src/sgml/ref/create_subscription.sgml

+12-10
Original file line numberDiff line numberDiff line change
@@ -438,16 +438,18 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
438438
the case of different <literal>WHERE</literal> clauses, if one of the
439439
publications has no <literal>WHERE</literal> clause (referring to that
440440
publish operation) or the publication is declared as
441-
<literal>FOR ALL TABLES</literal> or
442-
<literal>FOR TABLES IN SCHEMA</literal>, rows are always published
443-
regardless of the definition of the other expressions.
444-
If the subscriber is a <productname>PostgreSQL</productname> version before
445-
15, then any row filtering is ignored during the initial data synchronization
446-
phase. For this case, the user might want to consider deleting any initially
447-
copied data that would be incompatible with subsequent filtering.
448-
Because initial data synchronization does not take into account the publication
449-
<literal>publish</literal> parameter when copying existing table data, some rows
450-
may be copied that would not be replicated using DML. See
441+
<link linkend="sql-createpublication-for-all-tables"><literal>FOR ALL TABLES</literal></link>
442+
or <link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>,
443+
rows are always published regardless of the definition of the other
444+
expressions. If the subscriber is a <productname>PostgreSQL</productname>
445+
version before 15, then any row filtering is ignored during the initial data
446+
synchronization phase. For this case, the user might want to consider
447+
deleting any initially copied data that would be incompatible with
448+
subsequent filtering. Because initial data synchronization does not take
449+
into account the publication
450+
<link linkend="sql-createpublication-with-publish"><literal>publish</literal></link>
451+
parameter when copying existing table data, some rows may be copied that
452+
would not be replicated using DML. See
451453
<xref linkend="logical-replication-subscription-examples"/> for examples.
452454
</para>
453455

doc/src/sgml/system-views.sgml

+4-3
Original file line numberDiff line numberDiff line change
@@ -2145,9 +2145,10 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
21452145
information about the mapping between publications and information of
21462146
tables they contain. Unlike the underlying catalog
21472147
<link linkend="catalog-pg-publication-rel"><structname>pg_publication_rel</structname></link>,
2148-
this view expands publications defined as <literal>FOR ALL TABLES</literal>
2149-
and <literal>FOR TABLES IN SCHEMA</literal>, so for such publications
2150-
there will be a row for each eligible table.
2148+
this view expands publications defined as
2149+
<link linkend="sql-createpublication-for-all-tables"><literal>FOR ALL TABLES</literal></link>
2150+
and <link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>,
2151+
so for such publications there will be a row for each eligible table.
21512152
</para>
21522153

21532154
<table>

0 commit comments

Comments
 (0)