mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Copy-edit docs for logical replication column lists

Browse Source 
There was a excessive structure, leading to somewhat disorganized
presentation of the information. Remove a few tags and reorder
paragraphs to make the text flow more easily.  Also, reword some of it
to be more concise.

The bit about column list combination is not modified, other than to
remove an uninteresting (and IMO confusing and wrong) paragraph; I
intend to deal with it differently afterwards.

Backpatch to 15.

Discussion: https://postgr.es/m/20220913121138.yn7ekkfysxzhkm2u@alvherre.pgsql
This commit is contained in:
Alvaro Herrera 2022-09-15 18:04:00 +02:00
parent 918de37652
commit 3a06a79cd1
No known key found for this signature in database
GPG Key ID: 1C20ACB9D5C564AE
2 changed files with 47 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
doc/src/sgml/logical-replication.sgml
View File

@ -1093,44 +1093,39 @@ test_sub=# SELECT * FROM child ORDER BY a;
<title>Column Lists</title> <title>Column Lists</title>
<para> <para>
By default, all columns of a published table will be replicated to the Each publication can optionally specify which columns of each table are
appropriate subscribers. The subscriber table must have at least all the replicated to subscribers. The table on the subscriber side must have at
columns of the published table. However, if a least all the columns that are published. If no column list is specified,
<firstterm>column list</firstterm> is specified then only the columns named then all columns in the publisher are replicated.
in the list will be replicated. This means the subscriber-side table only See <xref linkend="sql-createpublication"/> for details on the syntax.
needs to have those columns named by the column list. A user might choose to
use column lists for behavioral, security or performance reasons.
</para>
<sect2 id="logical-replication-col-list-rules">
<title>Column List Rules</title>
<para>
A column list is specified per table following the table name, and enclosed
by parentheses. See <xref linkend="sql-createpublication"/> for details.
</para> </para>
<para> <para>
When specifying a column list, the order of columns is not important. If no The choice of columns can be based on behavioral or performance reasons.
column list is specified, all columns of the table are replicated through However, do not rely on this feature for security: a malicious subscriber
this publication, including any columns added later. This means a column is able to obtain data from columns that are not specifically
list which names all columns is not quite the same as having no column list published. If security is a consideration, protections can be applied
at all. For example, if additional columns are added to the table then only at the publisher side.
those named columns mentioned in the column list will continue to be
replicated.
</para> </para>
<para> <para>
Column lists have no effect for <literal>TRUNCATE</literal> command. If no column list is specified, any columns added later are automatically
replicated. This means that having a column list which names all columns
is not the same as having no column list at all.
</para> </para>
</sect2> <para>
A column list can contain only simple column references. The order
<sect2 id="logical-replication-col-list-restrictions"> of columns in the list is not preserved.
<title>Column List Restrictions</title> </para>
<para> <para>
A column list can contain only simple column references. 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
<literal>false</literal> (the default), each partition's column list is used.
</para> </para>
<para> <para>
@ -1139,44 +1134,20 @@ test_sub=# SELECT * FROM child ORDER BY a;
table's replica identity columns (see table's replica identity columns (see
<xref linkend="sql-altertable-replica-identity"/>). <xref linkend="sql-altertable-replica-identity"/>).
If a publication publishes only <command>INSERT</command> operations, then If a publication publishes only <command>INSERT</command> operations, then
the column list is arbitrary and may omit some replica identity columns. the column list may omit replica identity columns.
</para> </para>
</sect2>
<sect2 id="logical-replication-col-list-partitioned">
<title>Partitioned Tables</title>
<para> <para>
For partitioned tables, the publication parameter Column lists have no effect for the <literal>TRUNCATE</literal> command.
<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
<literal>false</literal> (default), each partition's column list is used.
</para> </para>
</sect2>
<sect2 id="logical-replication-col-list-initial-data-sync">
<title>Initial Data Synchronization</title>
<para> <para>
If the subscription requires copying pre-existing table data and a During initial data synchronization, only the published columns are
publication specifies a column list, only data from those columns will be copied. However, if the subscriber is from a release prior to 15, then
copied. all the columns in the table are copied during initial data synchronization,
ignoring any column lists.
</para> </para>
<note>
<para>
If the subscriber is in a release prior to 15, copy pre-existing data
doesn't use column lists even if they are defined in the publication.
This is because old releases can only copy the entire table data.
</para>
</note>
</sect2>
<sect2 id="logical-replication-col-list-combining"> <sect2 id="logical-replication-col-list-combining">
<title>Combining Multiple Column Lists</title> <title>Combining Multiple Column Lists</title>
@ -1193,12 +1164,6 @@ test_sub=# SELECT * FROM child ORDER BY a;
<literal>ALTER SUBSCRIPTION ... DROP PUBLICATION</literal> and then add it <literal>ALTER SUBSCRIPTION ... DROP PUBLICATION</literal> and then add it
back after adjusting the column list. back after adjusting the column list.
</para> </para>
<para>
Background: The main purpose of the column list feature is to allow
statically different table shapes on publisher and subscriber, or hide
sensitive column data. In both cases, it doesn't seem to make sense to
combine column lists.
</para>
</warning> </warning>
</sect2> </sect2>