Update the docs and comments for decoding of prepared xacts.

Commit a271a1b50e introduced decoding at prepare time in ReorderBuffer.
This can lead to deadlock for out-of-core logical replication solutions
that uses this feature to build distributed 2PC in case such transactions
lock [user] catalog tables exclusively. They need to inform users to not
have locks on catalog tables (via explicit LOCK command) in such
transactions.

Reported-by: Andres Freund
Discussion: https://postgr.es/m/20210222222847.tpnb6eg3yiykzpky@alap3.anarazel.de

diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml
index 6455664cb4f191ed060ec6ebf77e939780055bcb..85c55d641257959fb94c674609a0faeee2bf2116 100644 (file)
--- a/doc/src/sgml/logicaldecoding.sgml
+++ b/doc/src/sgml/logicaldecoding.sgml
@@ -1228,5 +1228,29 @@ stream_commit_cb(...);  <-- commit of the streamed transaction
     that name pattern will not be decoded as a two-phase commit transaction.
    </para>
 
+   <para>
+    The users that want to decode prepared transactions need to be careful about
+    below mentioned points:
+
+    <itemizedlist>
+     <listitem>
+      <para>
+       If the prepared transaction has locked [user] catalog tables exclusively
+       then decoding prepare can block till the main transaction is committed.
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
+       The logical replication solution that builds distributed two phase commit
+       using this feature can deadlock if the prepared transaction has locked
+       [user] catalog tables exclusively. They need to inform users to not have
+       locks on catalog tables (via explicit <command>LOCK</command> command) in
+       such transactions.
+      </para>
+     </listitem>
+    </itemizedlist>
+   </para>
+
   </sect1>
  </chapter>

diff --git a/src/backend/replication/logical/decode.c b/src/backend/replication/logical/decode.c
index afa1df00d0eafcfb44183ed308d083cdef27c2e1..657cb4af1e3bb80e8cfec6b4bc83ef4aff6fce98 100644 (file)
--- a/src/backend/replication/logical/decode.c
+++ b/src/backend/replication/logical/decode.c
@@ -362,6 +362,20 @@ DecodeXactOp(LogicalDecodingContext *ctx, XLogRecordBuffer *buf)
                                        break;
                                }
 
+                               /*
+                                * Note that if the prepared transaction has locked [user]
+                                * catalog tables exclusively then decoding prepare can block
+                                * till the main transaction is committed because it needs to
+                                * lock the catalog tables.
+                                *
+                                * XXX Now, this can even lead to a deadlock if the prepare
+                                * transaction is waiting to get it logically replicated for
+                                * distributed 2PC. Currently, we don't have an in-core
+                                * implementation of prepares for distributed 2PC but some
+                                * out-of-core logical replication solution can have such an
+                                * implementation. They need to inform users to not have locks
+                                * on catalog tables in such transactions.
+                                */
                                DecodePrepare(ctx, buf, &parsed);
                                break;
                        }