2 files changed, 38 insertions, 0 deletions

diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml
index 6455664cb4f..85c55d64125 100644
--- 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 afa1df00d0e..657cb4af1e3 100644
--- 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;
 			}