diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index d58b16977cd..b24bb2ec45f 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -1426,7 +1426,7 @@ postgres=# SELECT pg_current_wal_insert_lsn(); The LSN obtained from the primary is then communicated to the standby server. This can be managed at the application level or via the connection pooler. On the standby, the application issues the - command to block further processing until + command to block further processing until the standby's WAL replay process reaches (or exceeds) the specified LSN. diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index 141ada9c50a..b7ea1f37291 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -189,7 +189,7 @@ Complete list of usable sgml source files in this directory. - + diff --git a/doc/src/sgml/ref/wait_for.sgml b/doc/src/sgml/ref/wait.sgml similarity index 95% rename from doc/src/sgml/ref/wait_for.sgml rename to doc/src/sgml/ref/wait.sgml index 77b7674f93e..9056eb6726b 100644 --- a/doc/src/sgml/ref/wait_for.sgml +++ b/doc/src/sgml/ref/wait.sgml @@ -1,21 +1,21 @@ - - - WAIT FOR + + + WAIT - WAIT FOR + WAIT 7 SQL - Language Statements - WAIT FOR + WAIT wait for WAL to reach a target LSN @@ -225,7 +225,7 @@ WAIT FOR LSN 'lsn' Notes - WAIT FOR must be executed as a top-level command. + WAIT must be executed as a top-level command. It cannot be executed from a function, procedure, or DO block. It also requires that no active or registered snapshot be held, and therefore cannot be used in contexts @@ -274,7 +274,7 @@ WAIT FOR LSN 'lsn' - WAIT FOR waits until the specified + WAIT waits until the specified lsn is reached according to the specified mode. The standby_replay mode waits for the LSN to be replayed (applied to the database), which is @@ -306,12 +306,12 @@ WAIT FOR LSN 'lsn' - WAIT FOR compares only the numeric + WAIT compares only the numeric LSN; it has no notion of which timeline a WAL record belongs to. This matters when a standby continues recovery across an upstream timeline switch — for example, a cascading standby whose upstream gets promoted. In that case - WAIT FOR will return success + WAIT will return success as soon as the position used by the selected wait mode reaches or passes the numeric LSN, regardless of which timeline that LSN belongs to. Applications that need to @@ -320,11 +320,11 @@ WAIT FOR LSN 'lsn' - On a standby server, WAIT FOR sessions may be + On a standby server, WAIT sessions may be interrupted by recovery conflicts. Some recovery conflicts are unavoidable: for example, replaying a tablespace drop resolves conflicts by terminating all backends, regardless of what they are - doing. Applications using WAIT FOR on a standby + doing. Applications using WAIT on a standby should be prepared to handle such interruptions, for example by retrying the command or falling back to an alternative mechanism. @@ -335,7 +335,7 @@ WAIT FOR LSN 'lsn' Examples - You can use WAIT FOR command to wait for + 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 @@ -353,7 +353,7 @@ postgres=# SELECT pg_current_wal_insert_lsn(); (1 row) - Then an application could run WAIT FOR + 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. @@ -416,7 +416,7 @@ ERROR: timed out while waiting for target LSN 0/0306EE20 to be replayed; curren - The same example uses WAIT FOR with + The same example uses WAIT with the NO_THROW option: diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml index d9fdbb5d254..1dc7d6f8319 100644 --- a/doc/src/sgml/reference.sgml +++ b/doc/src/sgml/reference.sgml @@ -217,7 +217,7 @@ &update; &vacuum; &values; - &waitFor; + &wait; diff --git a/doc/src/sgml/release-19.sgml b/doc/src/sgml/release-19.sgml index a1c86100ed1..98e54eafb1d 100644 --- a/doc/src/sgml/release-19.sgml +++ b/doc/src/sgml/release-19.sgml @@ -56,7 +56,7 @@ - A new WAIT FOR + A new WAIT command that waits until a standby has replayed changes up to a chosen point, thereby supporting read-your-writes query patterns on standbys. @@ -1501,7 +1501,7 @@ Author: Alexander Korotkov -Add WAIT FOR command to allow standbys to wait for LSN values to be written, flushed, or replayed (Kartyshov Ivan, Alexander Korotkov, Xuneng Zhou) +Add WAIT command to allow standbys to wait for LSN values to be written, flushed, or replayed (Kartyshov Ivan, Alexander Korotkov, Xuneng Zhou) § § diff --git a/src/backend/commands/wait.c b/src/backend/commands/wait.c index b6b11522ea6..2223e91a3e3 100644 --- a/src/backend/commands/wait.c +++ b/src/backend/commands/wait.c @@ -54,8 +54,8 @@ ExecWaitStmt(ParseState *pstate, WaitStmt *stmt, bool isTopLevel, ereport(ERROR, (errcode(ERRCODE_FEATURE_NOT_SUPPORTED), errmsg("%s can only be executed as a top-level statement", - "WAIT FOR"), - errdetail("WAIT FOR cannot be used within a function, procedure, or DO block."))); + "WAIT"), + errdetail("WAIT cannot be used within a function, procedure, or DO block."))); /* Parse and validate the mandatory LSN */ lsn = DatumGetLSN(DirectFunctionCall1(pg_lsn_in, @@ -155,8 +155,8 @@ ExecWaitStmt(ParseState *pstate, WaitStmt *stmt, bool isTopLevel, if (HaveRegisteredOrActiveSnapshot()) ereport(ERROR, errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE), - errmsg("WAIT FOR must be called without an active or registered snapshot"), - errdetail("WAIT FOR cannot be executed within a transaction with an isolation level higher than READ COMMITTED.")); + errmsg("WAIT must be called without an active or registered snapshot"), + errdetail("WAIT cannot be executed within a transaction with an isolation level higher than READ COMMITTED.")); /* * As the result we should hold no snapshot, and correspondingly our xmin diff --git a/src/test/recovery/t/049_wait_for_lsn.pl b/src/test/recovery/t/049_wait_for_lsn.pl index 7769a0d80cc..3bc936e0f91 100644 --- a/src/test/recovery/t/049_wait_for_lsn.pl +++ b/src/test/recovery/t/049_wait_for_lsn.pl @@ -286,8 +286,7 @@ $node_standby->psql( 'postgres', "BEGIN ISOLATION LEVEL REPEATABLE READ; SELECT 1; WAIT FOR LSN '${lsn3}';", stderr => \$stderr); -ok( $stderr =~ - /WAIT FOR must be called without an active or registered snapshot/, +ok( $stderr =~ /WAIT must be called without an active or registered snapshot/, "get an error when running in a transaction with an isolation level higher than REPEATABLE READ" ); @@ -315,21 +314,21 @@ $node_standby->psql( 'postgres', "SELECT pg_wal_replay_wait_wrap('${lsn3}');", stderr => \$stderr); -ok($stderr =~ /WAIT FOR can only be executed as a top-level statement/, +ok($stderr =~ /WAIT can only be executed as a top-level statement/, "get an error when running within a function"); $node_standby->psql( 'postgres', "CALL pg_wal_replay_wait_proc('${lsn3}');", stderr => \$stderr); -ok($stderr =~ /WAIT FOR can only be executed as a top-level statement/, +ok($stderr =~ /WAIT can only be executed as a top-level statement/, "get an error when running within a procedure"); $node_standby->psql( 'postgres', "DO \$\$ BEGIN EXECUTE format('WAIT FOR LSN %L;', '${lsn3}'); END \$\$;", stderr => \$stderr); -ok($stderr =~ /WAIT FOR can only be executed as a top-level statement/, +ok($stderr =~ /WAIT can only be executed as a top-level statement/, "get an error when running within a DO block"); # 6. Check parameter validation error cases on standby before promotion