From c327b27e01bb2f5ab290d4b70fa990d328d84f13 Mon Sep 17 00:00:00 2001
From: Hou Zhijie <houzj.fnst@cn.fujitsu.com>
Date: Tue, 13 Aug 2024 16:08:36 +0800
Subject: [PATCH v19 1/2] Doc: explain the log format of logical replication
 conflict

This commit adds a detailed explanation of the log format for logical
replication conflicts to the documentation. It aims to help users better
understand conflict logs.
---
 doc/src/sgml/logical-replication.sgml | 69 +++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 885a2d70ae..8cbd8624a5 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -1666,6 +1666,75 @@ test_sub=# SELECT * FROM t1 ORDER BY id;
     log.
   </para>
 
+  <para>
+   The log format for logical replication conflicts is as follows:
+<screen>
+LOG:  conflict detected on relation "schemaname.tablename": conflict=<literal>conflict_type</literal>
+DETAIL:  <literal>detailed explaination</literal>.
+<literal>Key</literal> (column_name, ...)=(column_name, ...); <literal>existing local tuple</literal> (column_name, ...)=(column_name, ...); <literal>remote tuple</literal> (column_name, ...)=(column_name, ...); <literal>replica identity</literal> (column_name, ...)=(column_name, ...).
+</screen>
+   The log provides the following information:
+   <itemizedlist>
+    <listitem>
+     <para>
+      The <literal>LOG</literal> line includes the name of the local relation
+      involved in the conflict and the <literal>conflict_type</literal> (e.g.,
+      <literal>insert_exists</literal>, <literal>update_exists</literal>).
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      The origin, transaction ID, and commit timestamp of the transaction that
+      modified the existing local tuple, if available, are included in the
+      <literal>detailed explanation</literal> section of the first sentence in
+      the <literal>DETAIL</literal> line.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      The <literal>key</literal> section in the second sentence of the
+      <literal>DETAIL</literal> line includes the key values of the tuple that
+      already exists in the local relation for <literal>insert_exists</literal>
+      or <literal>update_exists</literal> conflicts.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      The <literal>existing local tuple</literal> section in the second
+      sentence of the <literal>DETAIL</literal> line includes the local tuple
+      if its origin differs from the remote tuple in cases of
+      <literal>update_differ</literal> or <literal>delete_differ</literal>
+      conflicts, or if the key value conflicts with the remote tuple in cases
+      of <literal>insert_exists</literal> or <literal>update_exists</literal>
+      conflicts.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      The <literal>remote tuple</literal> section of the second sentence in the
+      <literal>DETAIL</literal> line includes the new tuple from the remote
+      insert or update operation that caused the conflict. Note that for an
+      update operation, the column value of the new tuple may be NULL if the
+      value is unchanged.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      The <literal>replica identity</literal> section of the second sentence in
+      the <literal>DETAIL</literal> line includes the replica identity key
+      values that used to search for the existing local tuple to be updated or
+      deleted. This may include the full tuple value if the local relation is
+      marked with <literal>REPLICA IDENTITY FULL</literal>.
+     </para>
+    </listitem>
+   </itemizedlist>
+  </para>
+
   <para>
    Logical replication operations are performed with the privileges of the role
    which owns the subscription.  Permissions failures on target tables will
-- 
2.30.0.windows.2