From 2af020eacb8b74232a0570f72a05dd1f274f68de Mon Sep 17 00:00:00 2001 From: Alexander Korotkov Date: Thu, 17 Sep 2026 09:33:20 +0300 Subject: [PATCH] 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 Reviewed-by: Xuneng Zhou Reviewed-by: Alexander Korotkov 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)' - 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 68ca7101eba..cddcbf09695 100644 --- a/doc/src/sgml/ref/wait.sgml +++ b/doc/src/sgml/ref/wait.sgml @@ -312,7 +312,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 end of 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 @@ -370,9 +372,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 end of 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. @@ -387,8 +393,9 @@ postgres=# SELECT pg_current_wal_insert_lsn(); 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. + with the lsn obtained from the primary after the + commit. After that, the changes made on the primary should be guaranteed + to be visible on the replica. postgres=# WAIT FOR LSN '0/0306EE20';