From 13efac74d82a57435d998811f1e1a5c37251cc91 Mon Sep 17 00:00:00 2001 From: Sami Imseih Date: Wed, 9 Sep 2026 13:48:04 +0000 Subject: [PATCH v1 1/1] Clarify WAIT FOR read-your-writes documentation To achieve read-your-writes consistency with WAIT FOR, the target LSN must be captured after the transaction's COMMIT record. The existing documentation did not make that explicit, and could be read as allowing an LSN captured after a statement but before COMMIT. Document the COMMIT-LSN requirement explicitly in both the WAIT FOR reference page and the read-your-writes consistency section. --- doc/src/sgml/high-availability.sgml | 13 ++++++++----- doc/src/sgml/ref/wait_for.sgml | 19 +++++++++++++------ 2 files changed, 21 insertions(+), 11 deletions(-) diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index d58b16977cd..7e4fe3d3fc9 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -1409,9 +1409,10 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)' - 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. After committing the write + operations on the primary, the application retrieves a WAL location + that is at or after the transaction's COMMIT record, + using a function call like this. postgres=# SELECT pg_current_wal_insert_lsn(); @@ -1438,8 +1439,10 @@ postgres=# WAIT FOR LSN '0/306EE20'; (1 row) Once the command returns a status of success, it guarantees that all - changes up to the provided LSN have been applied, - ensuring that subsequent read queries will reflect the latest updates. + changes up to the provided LSN have been applied. + Therefore, if that LSN is at or after the write + transaction's COMMIT record on the primary, + subsequent read queries will reflect those updates. diff --git a/doc/src/sgml/ref/wait_for.sgml b/doc/src/sgml/ref/wait_for.sgml index 04ca9400426..e5b54d47afc 100644 --- a/doc/src/sgml/ref/wait_for.sgml +++ b/doc/src/sgml/ref/wait_for.sgml @@ -231,7 +231,9 @@ WAIT FOR LSN 'lsn' mode. 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. The + replica for reads and the primary for writes, provided that the target + LSN is at or after the relevant write transaction's + COMMIT record on the primary. The standby_flush 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 standby_write mode @@ -289,9 +291,13 @@ WAIT FOR LSN 'lsn' You can use WAIT FOR command to wait for the pg_lsn value. For example, an application could update - the movie table and get the lsn after - changes just made. This example uses pg_current_wal_insert_lsn - on primary server to get the lsn given that + the movie table and get an lsn that + is at or after the relevant write transaction's COMMIT + record. In the default autocommit mode shown here, the + UPDATE commits before the subsequent + SELECT. This example uses + pg_current_wal_insert_lsn on primary server to get + the lsn given that synchronous_commit could be set to off. @@ -306,8 +312,9 @@ postgres=# SELECT pg_current_wal_insert_lsn(); Then an application could run WAIT FOR - with the lsn obtained from primary. After that the - changes made on primary should be guaranteed to be visible on replica. + with the lsn obtained from primary by that + post-commit SELECT. After that the changes made on + primary should be guaranteed to be visible on replica. postgres=# WAIT FOR LSN '0/0306EE20'; -- 2.50.1