From fc425a59b2f17427861033cb03df86b36b60db89 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Fri, 13 May 2022 18:18:27 +1000
Subject: [PATCH v1] PGDOCS tablesync ignores publish operation

The tablesync ignores the publication 'publish' operations during the initial data copy.

This is existing PG behaviour but it was not documented before.
This patch documents the behaviour and gives some examples.
---
 doc/src/sgml/logical-replication.sgml | 90 ++++++++++++++++++++++++++++++++++-
 1 file changed, 89 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 145ea71..8dfc8f7 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -459,6 +459,9 @@
     published with different <literal>WHERE</literal> clauses, rows that satisfy
     <emphasis>any</emphasis> of the expressions will be copied. See
     <xref linkend="logical-replication-row-filter-combining"/> for details.
+    Note that during the initial data synchronizaton (unlike normal replication)
+    the <literal>publish</literal> operation of the publisher is ignored. See
+    <xref linkend="logical-replication-snapshot"/> for details.
    </para>
 
    <note>
@@ -500,7 +503,8 @@
       </para>
      </listitem>
     </itemizedlist></para>
-
+    <para>
+    </para>
   </sect2>
 
   <sect2 id="logical-replication-row-filter-examples">
@@ -1095,7 +1099,91 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
      replication of the table is given back to the main apply process where
      replication continues as normal.
     </para>
+    <note>
+     <para>
+      Publication <literal>publish</literal> operations (
+      <literal>insert</literal>, <literal>update</literal>, <literal>delete</literal>,
+      ...) are ignored during the initial data copy.
+     </para>
+    </note>
+  </sect2>
+
+  <sect2 id="logical-replication-snapshot-example">
+    <title>Example</title>
+
+    <para>
+     Create some test tables on the publisher.
+<programlisting>
+test_pub=# CREATE TABLE t1(a int, b text, PRIMARY KEY(a));
+CREATE TABLE
+test_pub=# CREATE TABLE t2(c int, d text, PRIMARY KEY(c));
+CREATE TABLE
+</programlisting></para>
+
+    <para>
+     Create the same tables on the subscriber.
+<programlisting>
+test_sub=# CREATE TABLE t1(a int, b text, PRIMARY KEY(a));
+CREATE TABLE
+test_sub=# CREATE TABLE t2(c int, d text, PRIMARY KEY(c));
+CREATE TABLE
+</programlisting></para>
+
+    <para>
+     Insert data to the tables at the publisher side.
+<programlisting>
+test_pub=# INSERT INTO t1 VALUES (1, 'one'), (2, 'two'), (3, 'three');
+INSERT 0 3
+test_pub=# INSERT INTO t2 VALUES (1, 'A'), (2, 'B'), (3, 'C');
+INSERT 0 3
+</programlisting></para>
+
+    <para>
+     Create publications for the tables. The publication <literal>pub2</literal>
+     limits the <literal>publish</literal> operations.
+<programlisting>
+test_pub=# CREATE PUBLICATION pub1 FOR TABLE t1;
+CREATE PUBLICATION
+test_pub=# CREATE PUBLICATION pub2 FOR TABLE t2 WITH (publish = 'truncate');
+CREATE PUBLICATION
+</programlisting></para>
+
+    <para>
+     Create subscriptions to each of those publications. Subscriptions
+     will copy initial data by default.
+<programlisting>
+test_sub=# CREATE SUBSCRIPTION sub1
+test_sub-#CONNECTION 'host=localhost dbname=test_pub application_name=sub1'
+test_sub-#PUBLICATION pub1;
+CREATE SUBSCRIPTION
+test_sub=# CREATE SUBSCRIPTION sub2
+test_sub-#CONNECTION 'host=localhost dbname=test_pub application_name=sub2'
+test_sub-#PUBLICATION pub2;
+CREATE SUBSCRIPTION
+</programlisting></para>
+
+    <para>
+     Observe that initial table data is copied, regardless of the
+     <literal>publish</literal> operation of the publication.
+<programlisting>
+test_sub=# SELECT * FROM t1;
+ a |   b
+---+-------
+ 1 | one
+ 2 | two
+ 3 | three
+(3 rows)
+
+test_sub=# SELECT * FROM t2;
+ c | d
+---+---
+ 1 | A
+ 2 | B
+ 3 | C
+(3 rows)
+</programlisting></para>
   </sect2>
+
  </sect1>
 
  <sect1 id="logical-replication-monitoring">
-- 
1.8.3.1