Document a few caveats in synchronous logical replication.

In a synchronous logical setup, locking [user] catalog tables can cause
deadlock. This is because logical decoding of transactions can lock
catalog tables to access them so exclusively locking those in transactions
can lead to deadlock. To avoid this users must refrain from having
exclusive locks on catalog tables.

Author: Takamichi Osumi
Reviewed-by: Vignesh C, Amit Kapila
Backpatch-through: 9.6
Discussion: https://www.postgresql.org/message-id/20210222222847.tpnb6eg3yiykzpky%40alap3.anarazel.de

diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml
index 8af438c61f320c6930df77e753a4239005acc035..463d7f93676388278a67790bf2f45ab8e38ffbd2 100644 (file)
--- a/doc/src/sgml/logicaldecoding.sgml
+++ b/doc/src/sgml/logicaldecoding.sgml
@@ -724,27 +724,65 @@ OutputPluginWrite(ctx, true);
 
   
    Synchronous Replication Support for Logical Decoding
+   
+    Overview
 
-   
-    Logical decoding can be used to build
-    synchronous
-    replication solutions with the same user interface as synchronous
-    replication for streaming
-    replication.  To do this, the streaming replication interface
-    (see ) must be used to stream out
-    data. Clients have to send Standby status update (F)
-    (see ) messages, just like streaming
-    replication clients do.
-   
-
-   
     
-     A synchronous replica receiving changes via logical decoding will work in
-     the scope of a single database. Since, in contrast to
-     that, synchronous_standby_names currently is
-     server wide, this means this technique will not work properly if more
-     than one database is actively used.
+     Logical decoding can be used to build
+     synchronous
+     replication solutions with the same user interface as synchronous
+     replication for streaming
+     replication.  To do this, the streaming replication interface
+     (see ) must be used to stream out
+     data. Clients have to send Standby status update (F)
+     (see ) messages, just like streaming
+     replication clients do.
+    
+
+    
+     
+      A synchronous replica receiving changes via logical decoding will work in
+      the scope of a single database. Since, in contrast to
+      that, synchronous_standby_names currently is
+      server wide, this means this technique will not work properly if more
+      than one database is actively used.
      
-   
+    
+   
+
+   
+    Caveats
+
+    
+     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:
+
+     
+      
+       
+        Issuing an explicit LOCK on pg_class
+        (or any other catalog table) in a transaction.
+       
+      
+
+      
+       
+        Perform CLUSTER on pg_class in a
+        transaction.
+       
+      
+
+      
+       
+        Executing TRUNCATE on [user] catalog table in a
+        transaction.
+       
+      
+     
+    
+