From 01f53cbacf3ce068d827d7b4c0be241eacaa8ee1 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 v20] 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 | 75 +++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 885a2d70ae..8ea695074b 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -1666,6 +1666,81 @@ test_sub=# SELECT * FROM t1 ORDER BY id;
     log.
   </para>
 
+  <para>
+   The log format for logical replication conflicts is as follows:
+<synopsis>
+LOG:  conflict detected on relation "<replaceable>schemaname</replaceable>.<replaceable>tablename</replaceable>": conflict=<replaceable>conflict_type</replaceable>
+DETAIL:  <replaceable class="parameter">detailed explanation</replaceable>.
+<optional>
+<literal>Key</literal> (<replaceable>column_name</replaceable>, ...)=(<replaceable>column_value</replaceable>, ...)</optional>
+<optional>; <literal>existing local tuple</literal> <optional>(<replaceable>column_name</replaceable>, ...)=</optional>(<replaceable>column_value</replaceable>, ...)</optional><optional>; <literal>remote tuple</literal> <optional>(<replaceable>column_name</replaceable>, ...)=</optional>(<replaceable>column_value</replaceable>, ...)</optional><optional>; <literal>replica identity</literal> {(<replaceable>column_name</replaceable>, ...)=(<replaceable>column_value</replaceable>, ...) | full (<replaceable>column_value</replaceable>, ...)}</optional>.
+</synopsis>
+   The log provides the following information:
+   <variablelist>
+    <varlistentry>
+     <term><literal>LOG</literal></term>
+      <listitem>
+       <itemizedlist>
+        <listitem>
+         <para>
+         The name of the local relation involved in the conflict and the conflict
+         type (e.g., <literal>insert_exists</literal>,
+         <literal>update_exists</literal>).
+         </para>
+        </listitem>
+       </itemizedlist>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><literal>DETAIL</literal></term>
+      <listitem>
+      <itemizedlist>
+       <listitem>
+        <para>
+         The origin, transaction ID, and commit timestamp of the transaction that
+         modified the existing local tuple, if available, are included in the
+         <replaceable class="parameter">detailed explanation</replaceable>.
+        </para>
+       </listitem>
+       <listitem>
+        <para>
+         The <literal>key</literal> section includes the key values of the local
+         tuple that violated a unique constraint <literal>insert_exists</literal>
+         or <literal>update_exists</literal> conflicts.
+        </para>
+       </listitem>
+       <listitem>
+        <para>
+         The <literal>existing local tuple</literal> section 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 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 will be null
+         if the value is unchanged and toasted.
+        </para>
+       </listitem>
+       <listitem>
+        <para>
+         The <literal>replica identity</literal> section 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>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </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