From 67b60c8f4ff89f4d5c2ad9907f329cd118392eb2 Mon Sep 17 00:00:00 2001
From: Amit Kapila <akapila@postgresql.org>
Date: Sat, 19 Jun 2021 15:17:15 +0530
Subject: [PATCH v2] Doc: Update caveats in synchronous logical replication.

Reported-by: Simon Riggs
Author: Takamichi Osumi
Reviewed-by: Amit Kapila
Discussion: https://www.postgresql.org/message-id/20210222222847.tpnb6eg3yiykzpky@alap3.anarazel.de
---
 doc/src/sgml/logicaldecoding.sgml | 28 +++++++++++++++-------------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml
index 1765ea6..db8718b 100644
--- a/doc/src/sgml/logicaldecoding.sgml
+++ b/doc/src/sgml/logicaldecoding.sgml
@@ -1097,40 +1097,42 @@ OutputPluginWrite(ctx, true);
 
     <para>
      In synchronous replication setup, a deadlock can happen, if the transaction
-     has locked [user] catalog tables exclusively. This is because logical decoding of
-     transactions can lock catalog tables to access them. To avoid this users
-     must refrain from taking an exclusive lock on [user] catalog tables. This can
-     happen in the following ways:
+     has locked [user] catalog tables exclusively. See
+     <xref linkend="logicaldecoding-capabilities"/> for information on user
+     catalog tables. This is because logical decoding of transactions can lock
+     catalog tables to access them. To avoid this users must refrain from taking
+     an exclusive lock on [user] catalog tables. This can happen in the following
+     ways:
 
      <itemizedlist>
       <listitem>
        <para>
         Issuing an explicit <command>LOCK</command> on <structname>pg_class</structname>
-        (or any other catalog table) in a transaction.
+        (or any other [user] catalog table) in a transaction.
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Perform <command>CLUSTER</command> on <structname>pg_class</structname> in
-        a transaction.
+        Perform <command>CLUSTER</command> on <structname>pg_class</structname> (or any
+        other [user] catalog table) in a transaction.
        </para>
       </listitem>
 
       <listitem>
        <para>
         <command>PREPARE TRANSACTION</command> after <command>LOCK</command> command
-        on <structname>pg_class</structname> and allow logical decoding of two-phase
-        transactions.
+        on <structname>pg_class</structname> (or any other [user] catalog table) and
+        allow logical decoding of two-phase transactions.
        </para>
       </listitem>
 
       <listitem>
        <para>
         <command>PREPARE TRANSACTION</command> after <command>CLUSTER</command>
-        command on <structname>pg_trigger</structname> and allow logical decoding of
-        two-phase transactions. This will lead to deadlock only when published table
-        have a trigger.
+        command on <structname>pg_trigger</structname> (or any other [user] catalog
+        table) and allow logical decoding of two-phase transactions. This will lead
+        to deadlock only when published table have a trigger.
        </para>
       </listitem>
 
@@ -1311,7 +1313,7 @@ stream_commit_cb(...);  &lt;-- commit of the streamed transaction
        [user] catalog tables exclusively. To avoid this users must refrain from
        having locks on catalog tables (e.g. explicit <command>LOCK</command> command)
        in such transactions.
-       (See <xref linkend="logicaldecoding-synchronous-caveats"/> for the details.)
+       See <xref linkend="logicaldecoding-synchronous-caveats"/> for the details.
       </para>
      </listitem>
     </itemizedlist>
-- 
1.8.3.1