Improve WAIT FOR read-your-writes consistency doc

Hi Sami,

On Wed, Sep 9, 2026 at 5:42 AM Sami Imseih <samimseih.pg@gmail.com> wrote:

The WAIT FOR docs say that "The standby_replay 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."

I think that needs one more caveat.

WAIT FOR success does not guarantee read-your-writes if the supplied LSN
is before the transaction's COMMIT record.

Maybe the last sentence should be qualified with:

" .... the primary for writes, provided that the target LSN was
captured after COMMIT on the primary."

This may be obvious to users of this feature, but perhaps worth being
more explicit about it.

Thoughts?

Thanks for raising this! I agree this may need to be harnessed. If we
change this line, we might also want to modify the
read-your-writes-consistency chapter.
<sect2 id="read-your-writes-consistency">
<title>Read-Your-Writes Consistency</title>

I am also wondering whether a example like this is helpful, though it is
somehow duplicated with the existing one:
postgres=# BEGIN;
BEGIN
postgres=*# UPDATE movie SET genre = 'Dramatic' WHERE genre = 'Drama';
UPDATE 100
postgres=*# COMMIT;
COMMIT
postgres=# SELECT pg_current_wal_insert_lsn();

--
Regards,
Xuneng Zhou
HighGo Software Co., Ltd.

Thanks for the feedback.

Thanks for raising this! I agree this may need to be harnessed. If we change this line, we might also want to modify the read-your-writes-consistency chapter.
<sect2 id="read-your-writes-consistency">
<title>Read-Your-Writes Consistency</title>

Yes, that needs to mention the COMMIT LSN explicitly.

I am also wondering whether a example like this is helpful, though it is somehow duplicated with the existing one:
postgres=# BEGIN;
BEGIN
postgres=*# UPDATE movie SET genre = 'Dramatic' WHERE genre = 'Drama';
UPDATE 100
postgres=*# COMMIT;
COMMIT
postgres=# SELECT pg_current_wal_insert_lsn();

Rather than change the example, just updated the explanation of the
example with the proper commit wording.

WDYT of the attached?

--
Sami

On Wed, Sep 9, 2026 at 9:57 PM Sami Imseih <samimseih.pg@gmail.com> wrote:

Thanks for the feedback.

Thanks for raising this! I agree this may need to be harnessed. If we change this line, we might also want to modify the read-your-writes-consistency chapter.
<sect2 id="read-your-writes-consistency">
<title>Read-Your-Writes Consistency</title>

Yes, that needs to mention the COMMIT LSN explicitly.

I am also wondering whether a example like this is helpful, though it is somehow duplicated with the existing one:
postgres=# BEGIN;
BEGIN
postgres=*# UPDATE movie SET genre = 'Dramatic' WHERE genre = 'Drama';
UPDATE 100
postgres=*# COMMIT;
COMMIT
postgres=# SELECT pg_current_wal_insert_lsn();

Rather than change the example, just updated the explanation of the
example with the proper commit wording.

WDYT of the attached?

Just a trivial comment:

+    This is achieved by the following steps.  After committing the write
+    operations on the primary, the application retrieves a WAL location
+    that is at or after the transaction's <literal>COMMIT</literal> record,
+    using a function call like this.

We might need to specify the word 'end' clearly to avoid
misunderstanding the LSN position as the beginning of the commit
record.

at or after the *end* of the write transaction’s COMMIT record.

--
Regards,
Xuneng Zhou
HighGo Software Co., Ltd.

Thanks!

WDYT of the attached?

Just a trivial comment:

+    This is achieved by the following steps.  After committing the write
+    operations on the primary, the application retrieves a WAL location
+    that is at or after the transaction's <literal>COMMIT</literal> record,
+    using a function call like this.

We might need to specify the word 'end' clearly to avoid
misunderstanding the LSN position as the beginning of the commit
record.

at or after the *end* of the write transaction’s COMMIT record.

I rather the comment be more high-level, and we just need to convey
that the function should be called after the commit.

See the attached.

--
Sami Imseih
Amazon Web Services (AWS)

Hi,

Attached is a rebase.

--
Sami Imseih
Amazon Web Services (AWS)

[RMT hat]

Please note that this one is now listed as an open item for v19.

--
nathan

On Tue, Sep 15, 2026 at 4:27 PM Sami Imseih <samimseih.pg@gmail.com> wrote:

Attached is a rebase.

I've made this following changes to the patch.
1) Change <command>WAIT FOR</command> back to <command>WAIT</command>
(see a23ab4862cfe).
2) In the example, app gets lsn at or after *the end* of the relevant
write transaction's COMMIT record. If we say lsn at the COMMIT record
then it might be interpreted as at he beginning of that record (and
that is wrong).

I'm going to push this if no objections.

------
Regards,
Alexander Korotkov
Supabase

On Wed, Sep 16, 2026 at 5:30 PM Alexander Korotkov <aekorotkov@gmail.com>
wrote:

On Tue, Sep 15, 2026 at 4:27 PM Sami Imseih <samimseih.pg@gmail.com>
wrote:

Attached is a rebase.

I've made this following changes to the patch.
1) Change <command>WAIT FOR</command> back to <command>WAIT</command>
(see a23ab4862cfe).
2) In the example, app gets lsn at or after *the end* of the relevant
write transaction's COMMIT record. If we say lsn at the COMMIT record
then it might be interpreted as at he beginning of that record (and
that is wrong).

I'm going to push this if no objections.

LGTM

Sami

On Thu, Sep 17, 2026 at 1:42 AM Sami Imseih <samimseih.pg@gmail.com> wrote:

On Wed, Sep 16, 2026 at 5:30 PM Alexander Korotkov <aekorotkov@gmail.com> wrote:

On Tue, Sep 15, 2026 at 4:27 PM Sami Imseih <samimseih.pg@gmail.com> wrote:

Attached is a rebase.

I've made this following changes to the patch.
1) Change <command>WAIT FOR</command> back to <command>WAIT</command>
(see a23ab4862cfe).
2) In the example, app gets lsn at or after *the end* of the relevant
write transaction's COMMIT record. If we say lsn at the COMMIT record
then it might be interpreted as at he beginning of that record (and
that is wrong).

I'm going to push this if no objections.

LGTM

Thank you, pushed.

------
Regards,
Alexander Korotkov
Supabase