pgsql: Doc: Explain about Column List feature.
Doc: Explain about Column List feature.
Add a new logical replication section for "Column Lists" (analogous to the
Row Filters page). This explains how the feature can be used and the
caveats in it.
Author: Peter Smith
Reviewed-by: Shi yu, Vignesh C, Erik Rijkers, Amit Kapila
Backpatch-through: 15, where it was introduced
Discussion: /messages/by-id/CAHut+PvOuc9=_4TbASc5=VUqh16UWtFO3GzcKQK_5m1hrW3vqg@mail.gmail.com
Branch
------
master
Details
-------
https://git.postgresql.org/pg/commitdiff/f98d07424523ab5fefa6c6483dbf60d0d2fe1df3
Modified Files
--------------
doc/src/sgml/logical-replication.sgml | 217 +++++++++++++++++++++++++++++++
doc/src/sgml/ref/alter_publication.sgml | 12 +-
doc/src/sgml/ref/create_publication.sgml | 6 +-
3 files changed, 224 insertions(+), 11 deletions(-)
On 2022-Sep-07, Amit Kapila wrote:
Doc: Explain about Column List feature.
Add a new logical replication section for "Column Lists" (analogous to the
Row Filters page). This explains how the feature can be used and the
caveats in it.Author: Peter Smith
Reviewed-by: Shi yu, Vignesh C, Erik Rijkers, Amit Kapila
Backpatch-through: 15, where it was introduced
Discussion: /messages/by-id/CAHut+PvOuc9=_4TbASc5=VUqh16UWtFO3GzcKQK_5m1hrW3vqg@mail.gmail.com
Hi
I just read these docs and noticed that it mentions that column lists
can be used for security. As far as I remember, this is wrong: it is
the subscriber that builds the query to read column data during initial
sync, and the publisher doesn't forbid to read columns not in it, so it
is entirely possible for a malicious subscriber to read columns other
than those published. I'm pretty sure we discussed this at some point
during development of the feature.
So I suggest to mention this point explicitly in its own paragraph, to
avoid giving a false sense of security.
While going over this text I found some additional things that could
--in my opinion-- stand some improvement:
* It feels better to start the section saying that a list can be
specified; subscriber must have all those columns; omitting list
means to publish everything. That leads to shorter text (no need to
say "you need to have them all, oh wait you might only have a few").
* there's no reason to explain the syntax in vague terms and refer the
reader to the reference page.
* The first few <sect2> seem to give no useful structure, and instead
cause the text to become disorganized. I propose to remove them, and
instead mix the paragraphs in them so that we explain the rules and
the behavior, and lastly the effect on specific commands.
The attached patch effects those changes.
One more thing. There's a sect2 about combining column list. Part of it
seems pretty judgmental and I see no reason to have it in there; I
propose to remove it (it's not in this patch). I think we should just
say it doesn't work at present, here's how to work around it, and
perhaps even say that we may lift the restriction in the future. The
paragraph that starts with "Background:" is IMO out of place, and it
repeats the mistake that column lists are for security.
Lastly: In the create-publication reference page I think it would be
better to reword the Parameters section a bit. It mentions
FOR TABLE as a parameter, but the parameter is actually
<replaceable>table_name</replaceable>; and the row-filter and
column-list explanations are also put in there when they should be in
their own <replaceable>expression</> and <replaceable>column_name</>
varlistentries. I think splitting things that way would result in a
clearer explanation.
--
Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
Attachments:
column-list-wording.patchtext/x-diff; charset=us-asciiDownload
diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 0ab191e402..3ac6336be2 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -1093,70 +1093,55 @@ test_sub=# SELECT * FROM child ORDER BY a;
<title>Column Lists</title>
<para>
- By default, all columns of a published table will be replicated to the
- appropriate subscribers. The subscriber table must have at least all the
- columns of the published table. However, if a
- <firstterm>column list</firstterm> is specified then only the columns named
- in the list will be replicated. This means the subscriber-side table only
- needs to have those columns named by the column list. A user might choose to
- use column lists for behavioral, security or performance reasons.
+ Each publication can optionally specify which columns of each table are
+ replicated to subscribers. The table on the subscriber side must have at
+ least all the columns that are published. If no column list is specified,
+ then all columns in the publisher are replicated.
+ See <xref linkend="sql-createpublication"/> for details on the syntax.
</para>
- <sect2 id="logical-replication-col-list-rules">
- <title>Column List Rules</title>
+ <para>
+ The choice of columns can be based on behavioral or performance reasons.
+ However, do not rely on this feature for security: a malicious subscriber
+ is able to obtain data from columns that are not specifically
+ published. If security is a consideration, protections can be applied
+ at the publisher side.
+ </para>
- <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>
+ If no column list is specified, all columns of the table are replicated
+ through this publication, including any columns added later. This means
+ that having a column list which names all columns is not the same as having
+ no column list at all: if columns are added to the table afterwards, those
+ will not be replicated.
+ </para>
- <para>
- When specifying a column list, the order of columns is not important. If no
- column list is specified, all columns of the table are replicated through
- this publication, including any columns added later. This means a column
- list which names all columns is not quite the same as having no column list
- at all. For example, if additional columns are added to the table then only
- those named columns mentioned in the column list will continue to be
- replicated.
- </para>
+ <para>
+ A column list can contain only simple column references. The order
+ of columns in the list is not preserved.
+ </para>
- <para>
- Column lists have no effect for <literal>TRUNCATE</literal> command.
- </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
+ <literal>false</literal> (the default), each partition's column list is used.
+ </para>
- </sect2>
+ <para>
+ If a publication publishes <command>UPDATE</command> or
+ <command>DELETE</command> operations, any column list must include the
+ table's replica identity columns (see
+ <xref linkend="sql-altertable-replica-identity"/>).
+ If a publication publishes only <command>INSERT</command> operations, then
+ the column list may omit replica identity columns.
+ </para>
- <sect2 id="logical-replication-col-list-restrictions">
- <title>Column List Restrictions</title>
-
- <para>
- A column list can contain only simple column references.
- </para>
-
- <para>
- If a publication publishes <command>UPDATE</command> or
- <command>DELETE</command> operations, any column list must include the
- table's replica identity columns (see
- <xref linkend="sql-altertable-replica-identity"/>).
- If a publication publishes only <command>INSERT</command> operations, then
- the column list is arbitrary and may omit some replica identity columns.
- </para>
-
- </sect2>
-
- <sect2 id="logical-replication-col-list-partitioned">
- <title>Partitioned Tables</title>
-
- <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
- <literal>false</literal> (default), each partition's column list is used.
- </para>
-
- </sect2>
+ <para>
+ Column lists have no effect for the <literal>TRUNCATE</literal> command.
+ </para>
<sect2 id="logical-replication-col-list-initial-data-sync">
<title>Initial Data Synchronization</title>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index f61641896a..0a68c4bf73 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -94,7 +94,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
effect on <literal>TRUNCATE</literal> commands. See
<xref linkend="logical-replication-col-lists"/> for details about column
lists.
-</para>
+ </para>
<para>
Only persistent base tables and partitioned tables can be part of a
On Tue, Sep 13, 2022 at 10:11 PM Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:
On 2022-Sep-07, Amit Kapila wrote:
Doc: Explain about Column List feature.
Add a new logical replication section for "Column Lists" (analogous to the
Row Filters page). This explains how the feature can be used and the
caveats in it.Author: Peter Smith
Reviewed-by: Shi yu, Vignesh C, Erik Rijkers, Amit Kapila
Backpatch-through: 15, where it was introduced
Discussion: /messages/by-id/CAHut+PvOuc9=_4TbASc5=VUqh16UWtFO3GzcKQK_5m1hrW3vqg@mail.gmail.comHi
I just read these docs and noticed that it mentions that column lists
can be used for security. As far as I remember, this is wrong: it is
the subscriber that builds the query to read column data during initial
sync, and the publisher doesn't forbid to read columns not in it, so it
is entirely possible for a malicious subscriber to read columns other
than those published. I'm pretty sure we discussed this at some point
during development of the feature.So I suggest to mention this point explicitly in its own paragraph, to
avoid giving a false sense of security.
Thanks for the feedback.
The mention of 'security' in the page (as previously written) just
means to say that publications can prevent sensitive columns from
being replicated/subscribed by default. It was not intended to imply
those columns are immune from a malicious attack. Indeed, just having
another publication without any column lists could expose the same
sensitive columns.
I am fine with your rewording of the security part.
While going over this text I found some additional things that could
--in my opinion-- stand some improvement:
In general (because they have a lot of similarities), the wording and
the section structure of the "Column Lists" page tried to be
consistent with the "Row Filters" page. Perhaps this made everything
unnecessarily complex. Anyway, your suggested re-wording and removal
of those sections look OK to me - the content is the same AFAICT.
* It feels better to start the section saying that a list can be
specified; subscriber must have all those columns; omitting list
means to publish everything. That leads to shorter text (no need to
say "you need to have them all, oh wait you might only have a few").* there's no reason to explain the syntax in vague terms and refer the
reader to the reference page.* The first few <sect2> seem to give no useful structure, and instead
cause the text to become disorganized. I propose to remove them, and
instead mix the paragraphs in them so that we explain the rules and
the behavior, and lastly the effect on specific commands.The attached patch effects those changes.
For some reason I was unable to apply your supplied patch to master:
[postgres@CentOS7-x64 oss_postgres_misc]$ git apply column-list-wording.patch
column-list-wording.patch:16: trailing whitespace.
Each publication can optionally specify which columns of each table are
column-list-wording.patch:17: trailing whitespace.
replicated to subscribers. The table on the subscriber side must have at
column-list-wording.patch:18: trailing whitespace.
least all the columns that are published. If no column list is specified,
column-list-wording.patch:19: trailing whitespace.
then all columns in the publisher are replicated.
column-list-wording.patch:20: trailing whitespace.
See <xref linkend="sql-createpublication"/> for details on the syntax.
error: patch failed: doc/src/sgml/logical-replication.sgml:1093
error: doc/src/sgml/logical-replication.sgml: patch does not apply
error: patch failed: doc/src/sgml/ref/create_publication.sgml:94
error: doc/src/sgml/ref/create_publication.sgml: patch does not apply
One more thing. There's a sect2 about combining column list. Part of it
seems pretty judgmental and I see no reason to have it in there; I
propose to remove it (it's not in this patch). I think we should just
say it doesn't work at present, here's how to work around it, and
perhaps even say that we may lift the restriction in the future. The
paragraph that starts with "Background:" is IMO out of place, and it
repeats the mistake that column lists are for security.
It wasn't clear which part you felt was judgemental. I have removed
the "Background" paragraph but I have otherwise left that section and
Warning as-is because it still seemed useful for the user to know. You
can change/remove it if you disagree.
Lastly: In the create-publication reference page I think it would be
better to reword the Parameters section a bit. It mentions
FOR TABLE as a parameter, but the parameter is actually
<replaceable>table_name</replaceable>; and the row-filter and
column-list explanations are also put in there when they should be in
their own <replaceable>expression</> and <replaceable>column_name</>
varlistentries. I think splitting things that way would result in a
clearer explanation.
IMO this should be proposed as a separate patch. Some of those things
(e.g. FOR TABLE as a parameter) seem to have been written that way
since PG10.
~~~
PSA a new patch for the "Column Lists" page. AFAIK this is the same as
everything that you suggested (except for the Warning section which
was kept as mentioned above).
------
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v1-0001-pgdocs-Column-Lists-page.patchapplication/octet-stream; name=v1-0001-pgdocs-Column-Lists-page.patchDownload
From 93951e013158ed9e99bd595581ae897886d61205 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Wed, 14 Sep 2022 14:53:06 +1000
Subject: [PATCH v1] pgdocs Column Lists page.
Reworded and removed some sections per Alvaro's suggestions.
---
doc/src/sgml/logical-replication.sgml | 105 +++++++++++++------------------
doc/src/sgml/ref/create_publication.sgml | 2 +-
2 files changed, 43 insertions(+), 64 deletions(-)
diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 0ab191e..8acb32b 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -1093,70 +1093,55 @@ test_sub=# SELECT * FROM child ORDER BY a;
<title>Column Lists</title>
<para>
- By default, all columns of a published table will be replicated to the
- appropriate subscribers. The subscriber table must have at least all the
- columns of the published table. However, if a
- <firstterm>column list</firstterm> is specified then only the columns named
- in the list will be replicated. This means the subscriber-side table only
- needs to have those columns named by the column list. A user might choose to
- use column lists for behavioral, security or performance reasons.
+ Each publication can optionally specify which columns of each table are
+ replicated to subscribers. The table on the subscriber side must have at
+ least all the columns that are published. If no column list is specified,
+ then all columns in the publisher are replicated.
+ See <xref linkend="sql-createpublication"/> for details on the syntax.
</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>
- When specifying a column list, the order of columns is not important. If no
- column list is specified, all columns of the table are replicated through
- this publication, including any columns added later. This means a column
- list which names all columns is not quite the same as having no column list
- at all. For example, if additional columns are added to the table then only
- those named columns mentioned in the column list will continue to be
- replicated.
- </para>
-
- <para>
- Column lists have no effect for <literal>TRUNCATE</literal> command.
- </para>
-
- </sect2>
-
- <sect2 id="logical-replication-col-list-restrictions">
- <title>Column List Restrictions</title>
-
- <para>
- A column list can contain only simple column references.
- </para>
+ <para>
+ The choice of columns can be based on behavioral or performance reasons.
+ However, do not rely on this feature for security: a malicious subscriber
+ is able to obtain data from columns that are not specifically
+ published. If security is a consideration, protections can be applied
+ at the publisher side.
+ </para>
- <para>
- If a publication publishes <command>UPDATE</command> or
- <command>DELETE</command> operations, any column list must include the
- table's replica identity columns (see
- <xref linkend="sql-altertable-replica-identity"/>).
- If a publication publishes only <command>INSERT</command> operations, then
- the column list is arbitrary and may omit some replica identity columns.
- </para>
+ <para>
+ If no column list is specified, all columns of the table are replicated
+ through this publication, including any columns added later. This means
+ that having a column list which names all columns is not the same as having
+ no column list at all: if columns are added to the table afterwards, those
+ will not be replicated.
+ </para>
- </sect2>
+ <para>
+ A column list can contain only simple column references. The order
+ of columns in the list is not preserved.
+ </para>
- <sect2 id="logical-replication-col-list-partitioned">
- <title>Partitioned Tables</title>
+ <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
+ <literal>false</literal> (the default), each partition's column list is used.
+ </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
- <literal>false</literal> (default), each partition's column list is used.
- </para>
+ <para>
+ If a publication publishes <command>UPDATE</command> or
+ <command>DELETE</command> operations, any column list must include the
+ table's replica identity columns (see
+ <xref linkend="sql-altertable-replica-identity"/>).
+ If a publication publishes only <command>INSERT</command> operations, then
+ the column list may omit replica identity columns.
+ </para>
- </sect2>
+ <para>
+ Column lists have no effect for the <literal>TRUNCATE</literal> command.
+ </para>
<sect2 id="logical-replication-col-list-initial-data-sync">
<title>Initial Data Synchronization</title>
@@ -1193,12 +1178,6 @@ test_sub=# SELECT * FROM child ORDER BY a;
<literal>ALTER SUBSCRIPTION ... DROP PUBLICATION</literal> and then add it
back after adjusting the column list.
</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>
</sect2>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index f616418..0a68c4b 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -94,7 +94,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
effect on <literal>TRUNCATE</literal> commands. See
<xref linkend="logical-replication-col-lists"/> for details about column
lists.
-</para>
+ </para>
<para>
Only persistent base tables and partitioned tables can be part of a
--
1.8.3.1
On 2022-Sep-14, Peter Smith wrote:
PSA a new patch for the "Column Lists" page. AFAIK this is the same as
everything that you suggested
I don't get it. You send me my patch back, and claim it is a new patch?
I kindly request that when you review a patch, you do not hijack the
submitter's patch and claim it as your own. If a submitter goes mising
or states that they're unavailable to complete some work, then that's
okay, but otherwise it seems a bit offensive to me. I have seen that
repeatedly of late, and I find it quite rude.
--
Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
"Las cosas son buenas o malas segun las hace nuestra opinión" (Lisias)
On Wed, Sep 14, 2022 at 7:40 PM Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:
On 2022-Sep-14, Peter Smith wrote:
PSA a new patch for the "Column Lists" page. AFAIK this is the same as
everything that you suggestedI don't get it. You send me my patch back, and claim it is a new patch?
I kindly request that when you review a patch, you do not hijack the
submitter's patch and claim it as your own. If a submitter goes mising
or states that they're unavailable to complete some work, then that's
okay, but otherwise it seems a bit offensive to me. I have seen that
repeatedly of late, and I find it quite rude.
Hi Alvaro,
I'm sorry for any misunderstandings.
I attached the replacement patch primarily because the original did
not apply for me, so I had to re-make it at my end anyway so I could
see the result. I thought posting it might save others from having to
do the same.
Certainly I am not trying to hijack or claim ownership.
------
Kind Regards,
Peter Smith.
Fujitsu Australia
On 2022-Sep-14, Peter Smith wrote:
On Tue, Sep 13, 2022 at 10:11 PM Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:
On 2022-Sep-07, Amit Kapila wrote:
One more thing. There's a sect2 about combining column list. Part of it
seems pretty judgmental and I see no reason to have it in there; I
propose to remove it (it's not in this patch). I think we should just
say it doesn't work at present, here's how to work around it, and
perhaps even say that we may lift the restriction in the future. The
paragraph that starts with "Background:" is IMO out of place, and it
repeats the mistake that column lists are for security.It wasn't clear which part you felt was judgemental. I have removed
the "Background" paragraph but I have otherwise left that section and
Warning as-is because it still seemed useful for the user to know. You
can change/remove it if you disagree.
I meant the Background part that you remove, yeah.
Looking at the rendered docs again, I notice that section "31.4.5.
Combining Multiple Column Lists" is *only* the red-tinted Warning block.
That seems quite odd. I am tempted to remove the sect2 heading for that
one too. I am now wondering how to split things between the normative bits
"It is not supported to have a subscription comprising several
publications where the same table has been published with different
column lists."
and the informative bits
"This means changing the column lists of the tables being subscribed
could cause inconsistency of column lists among publications, in which
case the ALTER PUBLICATION will be successful but later the walsender
on the publisher, or the subscriber may throw an error. In this
scenario, the user needs to recreate the subscription after adjusting
the column list or drop the problematic publication using ALTER
SUBSCRIPTION ... DROP PUBLICATION and then add it back after adjusting
the column list."
Lastly: In the create-publication reference page I think it would be
better to reword the Parameters section a bit. It mentions
FOR TABLE as a parameter, but the parameter is actually
<replaceable>table_name</replaceable>; and the row-filter and
column-list explanations are also put in there when they should be in
their own <replaceable>expression</> and <replaceable>column_name</>
varlistentries. I think splitting things that way would result in a
clearer explanation.IMO this should be proposed as a separate patch. Some of those things
(e.g. FOR TABLE as a parameter) seem to have been written that way
since PG10.
Agreed.
--
Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/
"Aprender sin pensar es inútil; pensar sin aprender, peligroso" (Confucio)
On 2022-Sep-15, Alvaro Herrera wrote:
Looking at the rendered docs again, I notice that section "31.4.5.
Combining Multiple Column Lists" is *only* the red-tinted Warning block.
That seems quite odd. I am tempted to remove the sect2 heading for that
one too.
Pushed. I didn't modify this part; I spent too much time looking at it
trying to figure out how to do it. I think this bit really belongs in
the CREATE/ALTER docs rather than this chapter. But in order to support
having a separate <para> for the restriction on combination, we need a
separate <varlistentry> for the column_name parameter. So I'm going to
edit that one and I'll throw this change in.
Thanks, Peter, for the discussion.
--
Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/
"Pensar que el espectro que vemos es ilusorio no lo despoja de espanto,
sólo le suma el nuevo terror de la locura" (Perelandra, C.S. Lewis)
On 2022-Sep-15, Alvaro Herrera wrote:
On 2022-Sep-15, Alvaro Herrera wrote:
Looking at the rendered docs again, I notice that section "31.4.5.
Combining Multiple Column Lists" is *only* the red-tinted Warning block.
That seems quite odd. I am tempted to remove the sect2 heading for that
one too.Pushed. I didn't modify this part; I spent too much time looking at it
trying to figure out how to do it. I think this bit really belongs in
the CREATE/ALTER docs rather than this chapter. But in order to support
having a separate <para> for the restriction on combination, we need a
separate <varlistentry> for the column_name parameter. So I'm going to
edit that one and I'll throw this change in.
I figured out how to fix this one -- just remove the <sect2> tags, and
add a <title> tag to the <warning> box. The attached yields the
explanatory text in a separate box that doesn't have the silly
otherwise-empty section title. We add the 'id' that was in the sect2 to
the warning; with this, at the referencing end the full title is
rendered, which looks quite reasonable. I have attached screenshots of
both sides of this.
Compare the existing
https://www.postgresql.org/docs/15/logical-replication-col-lists.html#LOGICAL-REPLICATION-COL-LIST-COMBINING
Unless there are objections, I'll get this pushed to 15 and master.
--
Álvaro Herrera Breisgau, Deutschland — https://www.EnterpriseDB.com/
Attachments:
0001-Rework-warning-about-column-list-combining.patchtext/x-diff; charset=us-asciiDownload
From ac205b33a86d0aad41803440fb444c4c60f30a16 Mon Sep 17 00:00:00 2001
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
Date: Mon, 19 Dec 2022 16:33:34 +0100
Subject: [PATCH] Rework warning about column list combining
---
doc/src/sgml/logical-replication.sgml | 8 ++------
1 file changed, 2 insertions(+), 6 deletions(-)
diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 7fdf08b59d..e5692531c2 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -1303,40 +1303,36 @@ test_sub=# SELECT * FROM child ORDER BY a;
Column lists have no effect for the <literal>TRUNCATE</literal> command.
</para>
<para>
During initial data synchronization, only the published columns are
copied. However, if the subscriber is from a release prior to 15, then
all the columns in the table are copied during initial data synchronization,
ignoring any column lists.
</para>
- <sect2 id="logical-replication-col-list-combining">
- <title>Combining Multiple Column Lists</title>
-
- <warning>
+ <warning id="logical-replication-col-list-combining">
+ <title>Combining Column Lists from Multiple Subscriptions</title>
<para>
It is not supported to have a subscription comprising several publications
where the same table has been published with different column lists.
This means changing the column lists of the tables being subscribed could
cause inconsistency of column lists among publications, in which case
the <xref linkend="sql-alterpublication"/> will be successful but later
the walsender on the publisher, or the subscriber may throw an error. In
this scenario, the user needs to recreate the subscription after adjusting
the column list or drop the problematic publication using
<literal>ALTER SUBSCRIPTION ... DROP PUBLICATION</literal> and then add it
back after adjusting the column list.
</para>
</warning>
- </sect2>
-
<sect2 id="logical-replication-col-list-examples">
<title>Examples</title>
<para>
Create a table <literal>t1</literal> to be used in the following example.
<programlisting>
test_pub=# CREATE TABLE t1(id int, a text, b text, c text, d text, e text, PRIMARY KEY(id));
CREATE TABLE
</programlisting></para>
--
2.30.2
combining.pngimage/pngDownload
�PNG
IHDR x � �s/ sBIT��O� tEXtSoftware gnome-screenshot��>