From 42616b05ed1011d0e9715a6331df9666d4dd17dd Mon Sep 17 00:00:00 2001
From: Amit Kapila <akapila@postgresql.org>
Date: Fri, 4 Sep 2026 09:41:31 +0530
Subject: [PATCH v3 2/2] Document retention caveats for retain_dead_tuples.

The information for conflict detection also accumulates while a
subscription is enabled but its apply worker is not running, not only
while the subscription is disabled. Note that, and point at the xmin of
the pg_conflict_detection slot as the way to see how much is being
retained.

max_retention_duration is evaluated by a running apply worker, so it
places no bound on the accumulation in either case. Say so, along with
the only remedy, which is to disable retain_dead_tuples.

Detection of update_deleted additionally requires track_commit_timestamp.
A warning is issued if retain_dead_tuples is enabled while that is off,
but disabling it afterwards silently leaves the retention in place while
the conflict is reported as update_missing, so document that too.

Author: Amit Kapila <amit.kapila16@gmail.com>
Discussion: https://postgr.es/m/TY4PR01MB177182F547A62FC2666EC04EC94B72@TY4PR01MB17718.jpnprd01.prod.outlook.com
Backpatch-through: 19, where it was introduced
---
 doc/src/sgml/ref/create_subscription.sgml | 26 +++++++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 25a81e2e62a..a4ea1f29c3a 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -542,7 +542,13 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
            the subscription is disabled; thus, the information will accumulate
            until the subscription is enabled. To prevent excessive accumulation,
            it is recommended to disable <literal>retain_dead_tuples</literal>
-           if the subscription will be inactive for an extended period.
+           if the subscription will be inactive for an extended period. The
+           same applies while the subscription is enabled but its apply worker
+           is not running, for example because the worker repeatedly fails to
+           apply a change. The oldest information being retained can be seen as
+           the <structfield>xmin</structfield> of the
+           <quote><literal>pg_conflict_detection</literal></quote> slot in
+           <link linkend="view-pg-replication-slots">pg_replication_slots</link>.
           </para>
 
           <para>
@@ -593,6 +599,17 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
           publisher. For the changes originating from different origins,
           reliable conflict detection cannot be guaranteed.
          </para>
+
+         <para>
+          Detection of <xref linkend="conflict-update-deleted"/> also requires
+          <link linkend="guc-track-commit-timestamp"><varname>track_commit_timestamp</varname></link>
+          to be enabled on the subscriber, and a warning is issued if
+          <literal>retain_dead_tuples</literal> is enabled while it is not. If
+          <varname>track_commit_timestamp</varname> is disabled afterwards, the
+          information for conflict detection continues to be retained, but the
+          conflict is reported as <xref linkend="conflict-update-missing"/>
+          instead, so the retention no longer serves its purpose.
+         </para>
         </listitem>
        </varlistentry>
 
@@ -626,7 +643,12 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
          <para>
           This option is effective only when
           <literal>retain_dead_tuples</literal> is enabled and the apply
-          worker associated with the subscription is active.
+          worker associated with the subscription is active. If the
+          subscription is disabled, or its apply worker is not running, the
+          retention duration is not evaluated and the information for conflict
+          detection continues to accumulate regardless of this setting. In that
+          case retention can only be stopped by disabling
+          <literal>retain_dead_tuples</literal>.
          </para>
          <warning>
           <para>
-- 
2.43.0