v15-0003-Doccumentation-patch.patch
text/x-patch
Filename: v15-0003-Doccumentation-patch.patch
Type: text/x-patch
Part: 1
From d230616135c4d6313d3e9bd72d5d3cd2b5362433 Mon Sep 17 00:00:00 2001
From: Dilip Kumar <dilipkumarb@google.com>
Date: Sun, 21 Dec 2025 18:51:57 +0530
Subject: [PATCH v15 3/5] Doccumentation patch
---
doc/src/sgml/logical-replication.sgml | 122 +++++++++++++++++++++-
doc/src/sgml/ref/alter_subscription.sgml | 12 ++-
doc/src/sgml/ref/create_subscription.sgml | 36 +++++++
3 files changed, 164 insertions(+), 6 deletions(-)
diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index b3faaa675ef..5544f9beb02 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -253,7 +253,11 @@
The subscription is added using <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link> and
can be stopped/resumed at any time using the
<link linkend="sql-altersubscription"><command>ALTER SUBSCRIPTION</command></link> command and removed using
- <link linkend="sql-dropsubscription"><command>DROP SUBSCRIPTION</command></link>.
+ <link linkend="sql-dropsubscription"><command>DROP SUBSCRIPTION</command></link>. When the
+ <literal>conflict_log_destination</literal> parameter is set to <literal>table</literal>
+ or <literal>all</literal>, the system automatically manages a dedicated conflict
+ storage table. This table is dropped automatically when the subscription is
+ removed via <command>DROP SUBSCRIPTION</command>.
</para>
<para>
@@ -289,6 +293,16 @@
option of <command>CREATE SUBSCRIPTION</command> for details.
</para>
+ <para>
+ Conflicts that occur during replication are typically logged as plain text
+ in the server log, which can be difficult for automated monitoring and
+ analysis. The <command>CREATE SUBSCRIPTION</command> command provides the
+ <link linkend="sql-createsubscription-params-with-conflict-log-destination">
+ <literal>conflict_log_destination</literal></link> option to record detailed
+ conflict information in a structured, queryable format, significantly
+ improving post-mortem analysis and operational visibility of the replication
+ setup by logging to a system-managed table.
+
<sect2 id="logical-replication-subscription-slot">
<title>Logical Replication Slot Management</title>
@@ -2006,9 +2020,14 @@ Publications:
</para>
<para>
- Additional logging is triggered, and the conflict statistics are collected (displayed in the
- <link linkend="monitoring-pg-stat-subscription-stats"><structname>pg_stat_subscription_stats</structname></link> view)
- in the following <firstterm>conflict</firstterm> cases:
+ Additional logging is triggered, and the conflict statistics are collected
+ (displayed in the <link linkend="monitoring-pg-stat-subscription-stats">
+ <structname>pg_stat_subscription_stats</structname></link> view)
+ in the following <firstterm>conflict</firstterm> cases. If the subscription
+ was created with the <literal>conflict_log_destination</literal> set to
+ <literal>table</literal>, detailed conflict information is also inserted
+ into an internally managed table named <literal>conflict_log_table_<subscription_oid></literal>,
+ providing a structured record of all conflicts.
<variablelist>
<varlistentry id="conflict-insert-exists" xreflabel="insert_exists">
<term><literal>insert_exists</literal></term>
@@ -2117,6 +2136,92 @@ Publications:
log.
</para>
+ <para>
+ When the <literal>conflict_log_destination</literal> is set to
+ <literal>table</literal>, the system automatically creates a new table with
+ a predefined schema to log conflict details. This table is created in the
+ owner's schema, is owned by the subscription owner, and logs system fields.
+ The schema of this table is detailed in
+ <xref linkend="logical-replication-conflict-log-schema"/>.
+ </para>
+
+ <table id="logical-replication-conflict-log-schema">
+ <title>Conflict Log History Table Schema</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Column</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>relid</literal></entry>
+ <entry><type>oid</type></entry>
+ <entry>The OID of the local table where the conflict occurred.</entry>
+ </row>
+ <row>
+ <entry><literal>schemaname</literal></entry>
+ <entry><type>text</type></entry>
+ <entry>The schema name of the conflicting table.</entry>
+ </row>
+ <row>
+ <entry><literal>relname</literal></entry>
+ <entry><type>text</type></entry>
+ <entry>The name of the conflicting table.</entry>
+ </row>
+ <row>
+ <entry><literal>conflict_type</literal></entry>
+ <entry><type>text</type></entry>
+ <entry>The type of conflict that occurred (e.g., <literal>insert_exists</literal>).</entry>
+ </row>
+ <row>
+ <entry><literal>remote_xid</literal></entry>
+ <entry><type>xid</type></entry>
+ <entry>The remote transaction ID that caused the conflict.</entry>
+ </row>
+ <row>
+ <entry><literal>remote_commit_lsn</literal></entry>
+ <entry><type>pg_lsn</type></entry>
+ <entry>The final LSN of the remote transaction.</entry>
+ </row>
+ <row>
+ <entry><literal>remote_commit_ts</literal></entry>
+ <entry><type>timestamptz</type></entry>
+ <entry>The remote commit timestamp of the remote transaction.</entry>
+ </row>
+ <row>
+ <entry><literal>remote_origin</literal></entry>
+ <entry><type>text</type></entry>
+ <entry>The origin of the remote transaction.</entry>
+ </row>
+ <row>
+ <entry><literal>remote_tuple</literal></entry>
+ <entry><type>json</type></entry>
+ <entry>The JSON representation of the incoming remote row that caused the conflict.</entry>
+ </row>
+ <row>
+ <entry><literal>local_conflicts</literal></entry>
+ <entry><type>json[]</type></entry>
+ <entry>
+ An array of JSON objects representing the local state for each conflict attempt.
+ Each object includes the local transaction ID (<literal>xid</literal>), commit
+ timestamp (<literal>commit_ts</literal>), origin (<literal>origin</literal>),
+ conflicting key data (<literal>key</literal>), and the full local row
+ image (<literal>tuple</literal>).
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ The conflicting row data, including the original local tuple and
+ the remote tuple, is stored in <type>JSON</type> columns (<literal>local_tuple</literal>
+ and <literal>remote_tuple</literal>) for flexible querying and analysis.
+ </para>
+
<para>
The log format for logical replication conflicts is as follows:
<synopsis>
@@ -2412,6 +2517,15 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
key or replica identity defined for it.
</para>
</listitem>
+
+ <listitem>
+ <para>
+ The internal table automatically created when <literal>conflict_log_destination</literal>
+ is set to <literal>table</literal> or <literal>all</literal> is excluded from
+ logical replication. It will not be published, even if a publication on the
+ subscriber is defined using <literal>FOR ALL TABLES</literal>.
+ </para>
+ </listitem>
</itemizedlist>
</sect1>
diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml
index 27c06439f4f..2f3bb0618f5 100644
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -280,8 +280,9 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
<link linkend="sql-createsubscription-params-with-origin"><literal>origin</literal></link>,
<link linkend="sql-createsubscription-params-with-failover"><literal>failover</literal></link>,
<link linkend="sql-createsubscription-params-with-two-phase"><literal>two_phase</literal></link>,
- <link linkend="sql-createsubscription-params-with-retain-dead-tuples"><literal>retain_dead_tuples</literal></link>, and
- <link linkend="sql-createsubscription-params-with-max-retention-duration"><literal>max_retention_duration</literal></link>.
+ <link linkend="sql-createsubscription-params-with-retain-dead-tuples"><literal>retain_dead_tuples</literal></link>,
+ <link linkend="sql-createsubscription-params-with-max-retention-duration"><literal>max_retention_duration</literal></link> and,
+ <link linkend="sql-createsubscription-params-with-conflict-log-destination"><literal>conflict_log_destination</literal></link>.
Only a superuser can set <literal>password_required = false</literal>.
</para>
@@ -339,6 +340,13 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
<quote><literal>pg_conflict_detection</literal></quote>, created to retain
dead tuples for conflict detection, will be dropped.
</para>
+
+ <para>
+ When switching <literal>conflict_log_destination</literal> to <literal>table</literal>,
+ the system will ensure the internal logging table exists. If switching away
+ from <literal>table</literal>, the logging stops, but the previously recorded
+ data remains until the subscription is dropped.
+ </para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 197be0c6f6b..3fa891bc4ae 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -274,6 +274,42 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
+ <varlistentry id="sql-createsubscription-params-with-conflict-log-destination">
+ <term><literal>conflict_log_destination</literal> (<type>enum</type>)</term>
+ <listitem>
+ <para>
+ Specifies the destination for recording logical replication conflicts.
+ The supported values are <literal>log</literal>, <literal>table</literal>,
+ and <literal>all</literal>. The default is <literal>log</literal>.
+ </para>
+ <para>
+ The available destinations are:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>log</literal>: Conflict details are recorded in the server log.
+ This is the default behavior.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>table</literal>: The system automatically creates a structured table named
+ <literal>pg_conflict_<subid></literal> in the subscription owner's schema.
+ This allows for easy querying and analysis of conflicts. This table is
+ automatically dropped when the subscription is removed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>all</literal>: Records the conflict information to both the server log
+ and the dedicated conflict table.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry id="sql-createsubscription-params-with-streaming">
<term><literal>streaming</literal> (<type>enum</type>)</term>
<listitem>
--
2.43.0