From b8a046081c43ce4a0a462812165f34b6026e60ef Mon Sep 17 00:00:00 2001
From: Amit Kapila <akapila@postgresql.org>
Date: Fri, 25 Oct 2024 14:19:05 +0530
Subject: [PATCH] Doc: Add a caution in alter publication.

Clarify that altering the 'publish_via_partition_root' option can lead to
data loss or duplication when a partition root table is specified as the
replication target.

Reported-by: Maxim Boguk
Author: Hayato Kuroda
Reviewed-by: Amit Kapila, Peter Smith, Vignesh C
Discussion: https://postgr.es/m/18644-6866bbd22178ee16@postgresql.org
---
 doc/src/sgml/ref/alter_publication.sgml | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index 44ae7e0e87..d5ea383e8b 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -154,6 +154,21 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
       This clause alters publication parameters originally set by
       <xref linkend="sql-createpublication"/>.  See there for more information.
      </para>
+     <caution>
+      <para>
+       Altering the <literal>publish_via_partition_root</literal> parameter can
+       lead to data loss or duplication at the subscriber because it changes
+       the identity and schema of the published tables. Note this happens only
+       when a partition root table is specified as the replication target.
+      </para>
+      <para>
+       This problem can be avoided by refraining from modifying partition leaf
+       tables after the <command>ALTER PUBLICATION ... SET</command> until the
+       <link linkend="sql-altersubscription"><command>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</command></link>
+       is executed and by only refreshing using the <literal>copy_data = off</literal>
+       option.
+      </para>
+     </caution>
     </listitem>
    </varlistentry>