From 700baa7e34b454b52cef07055d28cb262f9f9830 Mon Sep 17 00:00:00 2001
From: Alexander Korotkov <akorotkov@postgresql.org>
Date: Wed, 16 Sep 2026 15:39:43 +0300
Subject: [PATCH v4] doc: Say which LSN gives read-your-writes with WAIT

The reference page and the read-your-writes section both presented
WAIT in standby_replay mode as enough for read-your-writes, without
saying which LSN to wait for.  Read as written, an LSN taken after the
last statement but before COMMIT would do, and it would not: the standby
position WAIT compares against is the end of the last replayed record, so
a target that falls inside the COMMIT record is satisfied while that
record is still unapplied.

Say that the target must be at or after the end of the write
transaction's COMMIT record, and note in the example that autocommit is
what puts the UPDATE's commit before the call that reads the position.

Author: Sami Imseih <samimseih.pg@gmail.com>
Reviewed-by: Xuneng Zhou <xunengzhou@gmail.com>
Reviewed-by: Alexander Korotkov <aekorotkov@gmail.com>
Discussion: https://postgr.es/m/CAN12%2BYKN7gXb1o9bDWgfA%3D6wjDrqNEgt%2BrXJiAWXgPCXQ5TqpA%40mail.gmail.com
Backpatch-through: 19
---
 doc/src/sgml/high-availability.sgml | 11 ++++++-----
 doc/src/sgml/ref/wait.sgml          | 19 +++++++++++++------
 2 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index b24bb2ec45f..7253f9d8287 100644
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -1409,9 +1409,9 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)'
    </para>
 
    <para>
-    This is achieved by the following steps.  After performing write
-    operations, the application retrieves the current WAL location using a
-    function call like this.
+    This is achieved by the following steps.  Once the write transaction
+    has committed, the application retrieves a WAL location from the
+    primary using a function call like this.
 
 <programlisting>
 postgres=# SELECT pg_current_wal_insert_lsn();
@@ -1438,8 +1438,9 @@ postgres=# WAIT FOR LSN '0/306EE20';
 (1 row)
 </programlisting>
     Once the command returns a status of success, it guarantees that all
-    changes up to the provided <acronym>LSN</acronym> have been applied,
-    ensuring that subsequent read queries will reflect the latest updates.
+    changes up to the provided <acronym>LSN</acronym> have been applied.
+    Therefore, if that <acronym>LSN</acronym> was retrieved from the primary
+    after the commit, subsequent read queries will reflect those updates.
    </para>
   </sect2>
 
diff --git a/doc/src/sgml/ref/wait.sgml b/doc/src/sgml/ref/wait.sgml
index 9056eb6726b..542fa6b0047 100644
--- a/doc/src/sgml/ref/wait.sgml
+++ b/doc/src/sgml/ref/wait.sgml
@@ -279,7 +279,9 @@ WAIT FOR LSN '<replaceable class="parameter">lsn</replaceable>'
    <parameter>mode</parameter>. The <literal>standby_replay</literal> mode
    waits for the LSN to be replayed (applied to the database), which is
    useful to achieve read-your-writes consistency while using an async
-   replica for reads and the primary for writes. The
+   replica for reads and the primary for writes, provided that the target
+   <acronym>LSN</acronym> is at or after the end of the relevant write
+   transaction's <literal>COMMIT</literal> record on the primary. The
    <literal>standby_flush</literal> mode waits for the WAL to be flushed
    to durable storage on the replica, or to have already been replayed
    from WAL present on the standby. The <literal>standby_write</literal> mode
@@ -337,9 +339,13 @@ WAIT FOR LSN '<replaceable class="parameter">lsn</replaceable>'
   <para>
    You can use the <command>WAIT</command> command to wait for
    the <type>pg_lsn</type> value.  For example, an application could update
-   the <literal>movie</literal> table and get the <acronym>lsn</acronym> after
-   changes just made.  This example uses <function>pg_current_wal_insert_lsn</function>
-   on primary server to get the <acronym>lsn</acronym> given that
+   the <literal>movie</literal> table and get an <acronym>lsn</acronym> that
+   is at or after the end of the relevant write transaction's
+   <literal>COMMIT</literal> record.  In the default autocommit mode shown
+   here, the <command>UPDATE</command> commits before the subsequent
+   <command>SELECT</command>.  This example uses
+   <function>pg_current_wal_insert_lsn</function> on primary server to get
+   the <acronym>lsn</acronym> given that
    <varname>synchronous_commit</varname> could be set to
    <literal>off</literal>.
 
@@ -354,8 +360,9 @@ postgres=# SELECT pg_current_wal_insert_lsn();
 </programlisting>
 
    Then an application could run <command>WAIT</command>
-   with the <parameter>lsn</parameter> obtained from primary.  After that the
-   changes made on primary should be guaranteed to be visible on replica.
+   with the <parameter>lsn</parameter> obtained from the primary after the
+   commit.  After that, the changes made on the primary should be guaranteed
+   to be visible on the replica.
 
 <programlisting>
 postgres=# WAIT FOR LSN '0/0306EE20';
-- 
2.55.0