From cd6d78c2eb6edb39304f10e5a916af8117be02b8 Mon Sep 17 00:00:00 2001 From: Sami Imseih Date: Wed, 9 Sep 2026 13:48:04 +0000 Subject: [PATCH v3 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 | 11 ++++++----- doc/src/sgml/ref/wait.sgml | 21 ++++++++++++++------- 2 files changed, 20 insertions(+), 12 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)' - 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. postgres=# SELECT pg_current_wal_insert_lsn(); @@ -1438,8 +1438,9 @@ 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 was retrieved from the primary + after the commit, subsequent read queries will reflect those updates. diff --git a/doc/src/sgml/ref/wait.sgml b/doc/src/sgml/ref/wait.sgml index 9056eb6726b..5412597b3cd 100644 --- a/doc/src/sgml/ref/wait.sgml +++ b/doc/src/sgml/ref/wait.sgml @@ -279,7 +279,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 @@ -337,9 +339,13 @@ WAIT FOR LSN 'lsn' You can use the WAIT 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. @@ -353,9 +359,10 @@ postgres=# SELECT pg_current_wal_insert_lsn(); (1 row) - Then an application could run WAIT - with the lsn obtained from primary. After that the - changes made on primary should be guaranteed to be visible on replica. + Then an application could run WAIT FOR + with the lsn obtained from the primary + after commit. After that, the changes made on the + primary should be guaranteed to be visible on the replica. postgres=# WAIT FOR LSN '0/0306EE20'; -- 2.50.1