From d9224a503eee53bf5eada62e7c166d9245c1268f Mon Sep 17 00:00:00 2001 From: Xuneng Zhou Date: Fri, 11 Sep 2026 11:42:21 +0800 Subject: [PATCH v3] Rename the WAIT FOR command to WAIT in the documentation The command tag is WAIT, but the reference page called the command "WAIT FOR" in its title, index entry, psql help name and throughout its prose, and so did the error messages. FOR is a noise word that makes the grammar read like English, exactly as INTO does for INSERT and FROM does for DELETE; neither of those is part of the command's name. Settle on WAIT everywhere the command is named, and keep WAIT FOR LSN wherever the syntax itself is being shown. Rename the reference page's id and file name to match, following cb2c696b1dd: v19 is not released, so the URL is not yet baked into a supported version, and every other page's id matches its title. Reported-by: Masahiko Sawada sawada.mshk@gmail.com Discussion: https://postgr.es/m/CAD21AoBdtiPTbm7T_aNeDON9JpFG9g%3DJDUP4WU-Y8t8_xqvR5Q%40mail.gmail.com Backpatch-through: 19 Author: Xuneng Zhou xunengzhou@gmail.com Reviewed-by: Alexander Korotkov aekorotkov@gmail.com --- doc/src/sgml/high-availability.sgml | 2 +- doc/src/sgml/ref/allfiles.sgml | 2 +- doc/src/sgml/ref/{wait_for.sgml => wait.sgml} | 30 +++++++++---------- doc/src/sgml/reference.sgml | 2 +- src/backend/commands/wait.c | 8 ++--- src/test/recovery/t/049_wait_for_lsn.pl | 8 ++--- 6 files changed, 26 insertions(+), 26 deletions(-) rename doc/src/sgml/ref/{wait_for.sgml => wait.sgml} (94%) 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 94% rename from doc/src/sgml/ref/wait_for.sgml rename to doc/src/sgml/ref/wait.sgml index 04ca9400426..9204924b1c1 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 @@ -217,7 +217,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 @@ -226,7 +226,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 @@ -258,12 +258,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 @@ -272,11 +272,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. @@ -287,7 +287,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 @@ -305,7 +305,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. @@ -368,7 +368,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/src/backend/commands/wait.c b/src/backend/commands/wait.c index 9ba4c75021e..d78f98e5266 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, @@ -171,8 +171,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 cb7d4d461de..b94936bd2a7 100644 --- a/src/test/recovery/t/049_wait_for_lsn.pl +++ b/src/test/recovery/t/049_wait_for_lsn.pl @@ -287,7 +287,7 @@ $node_standby->psql( "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/, + /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 +315,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 -- 2.50.1 (Apple Git-155)