From: Alvaro Herrera <alvherre@alvh.no-ip.org>
Date: Fri, 23 Dec 2022 16:49:51 +0000 (+0100)
Subject: Rework <warning> box about column list combining in logical replication
X-Git-Url: http://git.postgresql.org/gitweb/-?a=commitdiff_plain;h=c6f21b2ac215ad870a95159ea22024f734429622;p=users%2Frhaas%2Fpostgres.git

Rework <warning> box about column list combining in logical replication

After some copy-edit I made in commit 3a06a79cd137, we have a <sect2>
that only contains a warning box.  This doesn't look good.  Rework by
moving the sect2 title to be the warning's title, and put the 'id' to it
as well, so that the external reference continues to work.

Backpatch to 15.

In branch master, I also take the opportunity to add titles to a couple
of other warning boxes elsewhere in the documentation.

Discussion: https://postgr.es/m/20221219164713.ccnlvtkyj6lmshqq@alvherre.pgsql
---

diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 7fdf08b59d..7b9bb00e5a 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -1310,26 +1310,30 @@ test_sub=# SELECT * FROM child ORDER BY a;
    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>Warning: Combining Column Lists from Multiple Publications</title>
+    <para>
+     There's currently no support for subscriptions comprising several
+     publications where the same table has been published with different
+     column lists.  <xref linkend="sql-createsubscription"/> disallows
+     creating such subscriptions, but it is still possible to get into
+     that situation by adding or altering column lists on the publication
+     side after a subscription has been created.
+    </para>
     <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.
+     This means changing the column lists of tables on publications that are
+     already subscribed could lead to errors being thrown on the subscriber
+     side.
+    </para>
+    <para>
+     If a subscription is affected by this problem, the only way to resume
+     replication is to adjust one of the column lists on the publication
+     side so that they all match; and then either recreate the subscription,
+     or use <literal>ALTER SUBSCRIPTION ... DROP PUBLICATION</literal> to
+     remove one of the offending publications and add it again.
     </para>
    </warning>
 
-  </sect2>
-
   <sect2 id="logical-replication-col-list-examples">
    <title>Examples</title>
 
diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index 337f6dd429..b87ad5cc53 100644
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -1676,11 +1676,13 @@ SELECT pg_advisory_lock(q.id) FROM
     </para>
 
     <warning>
+     <title>Warning: Serializable Transactions and Data Replication</title>
      <para>
       This level of integrity protection using Serializable transactions
-      does not yet extend to hot standby mode (<xref linkend="hot-standby"/>).
-      Because of that, those using hot standby may want to use Repeatable
-      Read and explicit locking on the primary.
+      does not yet extend to hot standby mode (<xref linkend="hot-standby"/>)
+      or logical replicas.
+      Because of that, those using hot standby or logical replication
+      may want to use Repeatable Read and explicit locking on the primary.
      </para>
     </warning>
    </sect2>
diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml
index 69d6924b3a..768024c491 100644
--- a/doc/src/sgml/ref/pg_rewind.sgml
+++ b/doc/src/sgml/ref/pg_rewind.sgml
@@ -103,6 +103,7 @@ PostgreSQL documentation
   </para>
 
   <warning>
+   <title>Warning: Failures while Rewinding</title>
    <para>
     If <application>pg_rewind</application> fails while processing, then
     the data folder of the target is likely not in a state that can be