Doc: explain the log format of logical replication conflicts.

This commit adds a detailed explanation of the log format for logical
replication conflicts.

Author: Hou Zhijie
Reviewed-by: Shveta Malik, Peter Smith, Hayato Kuroda
Discussion: https://postgr.es/m/OS0PR01MB5716352552DFADB8E9AD1D8994C92@OS0PR01MB5716.jpnprd01.prod.outlook.com
Discussion: https://postgr.es/m/OS0PR01MB57162EDE8BA17F3EE08A24CA948D2@OS0PR01MB5716.jpnprd01.prod.outlook.com

diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 08f89e01ada80a8d8b852634562b568a8aef93c2..bee7e02983be96dcb1480219de1b937553d221c2 100644 (file)
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -1666,6 +1666,111 @@ test_sub=# SELECT * FROM t1 ORDER BY id;
     log.
   
 
+  
+   The log format for logical replication conflicts is as follows:
+
+LOG:  conflict detected on relation "schemaname.tablename": conflict=conflict_type
+DETAIL:  detailed_explanation.
+{detail_values [; ... ]}.
+
+where detail_values is one of:
+
+    Key (column_name , ...)=(column_value , ...)
+    existing local tuple (column_name , ...)=(column_value , ...)
+    remote tuple (column_name , ...)=(column_value , ...)
+    replica identity {(column_name , ...)=(column_value , ...) | full (column_name , ...)=(column_value , ...)}
+
+
+   The log provides the following information:
+   
+    
+     LOG
+      
+       
+        
+         
+         schemaname.tablename
+         identifies the local relation involved in the conflict.
+         
+        
+        
+         
+         conflict_type is the type of conflict that occurred
+         (e.g., insert_exists, update_exists).
+         
+        
+       
+      
+    
+
+    
+     DETAIL
+      
+      
+       
+        
+         detailed_explanation includes
+         the origin, transaction ID, and commit timestamp of the transaction that
+         modified the existing local tuple, if available.
+        
+       
+       
+        
+         The Key section includes the key values of the local
+         tuple that violated a unique constraint for
+         insert_exists or update_exists
+         conflicts.
+        
+       
+       
+        
+         The existing local tuple section includes the local
+         tuple if its origin differs from the remote tuple for
+         update_differ or delete_differ
+         conflicts, or if the key value conflicts with the remote tuple for
+         insert_exists or update_exists
+         conflicts.
+        
+       
+       
+        
+         The remote tuple 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.
+        
+       
+       
+        
+         The replica identity section includes the replica
+         identity key values that were 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
+         REPLICA IDENTITY FULL.
+        
+       
+       
+        
+         column_name is the column name.
+         For existing local tuple, remote tuple,
+         and replica identity full cases, column names are
+         logged only if the user lacks the privilege to access all columns of
+         the table. If column names are present, they appear in the same order
+         as the corresponding column values.
+        
+       
+       
+        
+         column_value is the column value.
+         The large column values are truncated to 64 bytes.
+        
+       
+      
+     
+    
+   
+  
+
   
    Logical replication operations are performed with the privileges of the role
    which owns the subscription.  Permissions failures on target tables will