From: Alexander Korotkov <akorotkov@postgresql.org>
Date: Sun, 3 May 2026 13:20:41 +0000 (+0300)
Subject: Document that WAIT FOR LSN is timeline-blind
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=21d290161b11adc92a49da8e71fda69c20032618;p=thirdparty%2Fpostgresql.git

Document that WAIT FOR LSN is timeline-blind

WAIT FOR LSN compares only the numeric LSN and has no notion of which
timeline a WAL record belongs to.  There are many possible scenarios when
timeline-switching can break read-your-writes consistency.  The proper
analysis and timeline support is possible in the next major release.  Yet
just document the current behaviour.

Reported-by: Xuneng Zhou <xunengzhou@gmail.com>
Author: Alexander Korotkov <aekorotkov@gmail.com>
---

diff --git a/doc/src/sgml/ref/wait_for.sgml b/doc/src/sgml/ref/wait_for.sgml
index 8819973c774..cd5dd031991 100644
--- a/doc/src/sgml/ref/wait_for.sgml
+++ b/doc/src/sgml/ref/wait_for.sgml
@@ -257,6 +257,20 @@ WAIT FOR LSN '<replaceable class="parameter">lsn</replaceable>'
    timeline.
   </para>
 
+  <para>
+   <command>WAIT FOR</command> compares only the numeric
+   <acronym>LSN</acronym>; it has no notion of which timeline a WAL
+   record belongs to.  This matters when a standby continues recovery
+   across an upstream timeline switch &mdash; for example, a cascading
+   standby whose upstream gets promoted.  In that case
+   <command>WAIT FOR</command> will return <literal>success</literal>
+   as soon as the position used by the selected wait mode reaches or
+   passes the numeric <acronym>LSN</acronym>, regardless of which
+   timeline that <acronym>LSN</acronym> belongs to.  Applications that need to
+   confirm the target refers to the expected timeline must validate
+   the timeline themselves.
+  </para>
+
   <para>
    On a standby server, <command>WAIT FOR</command> sessions may be
    interrupted by recovery conflicts.  Some recovery conflicts are