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 8819973c774337585f20a2deda4f67b8c9ec34d6..cd5dd0319913b8bdc0706d3546797e8d02ea8d8a 100644 (file)
--- 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