Doc: Add a caution in alter publication.

Amit Kapila · Amit Kapila · commit b8a046081c43 · 2024-10-25T14:19:05.000+05:30
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
diff --git 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>
 
