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

