postgres.git / summary / log / commit / refs
commit a23ab4862cfebb9aba58f713854b7d5e42d5f947
Author: Alexander Korotkov <akorotkov@postgresql.org>
Date: Mon Sep 14 11:13:30 2026 +0000
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
Author: Xuneng Zhou xunengzhou@gmail.com
Reviewed-by: Alexander Korotkov aekorotkov@gmail.com
Discussion: https://postgr.es/m/CAD21AoBdtiPTbm7T_aNeDON9JpFG9g%3DJDUP4WU-Y8t8_xqvR5Q%40mail.gmail.com
Backpatch-through: 19
doc/src/sgml/high-availability.sgml | 2 +-
doc/src/sgml/ref/allfiles.sgml | 2 +-
wait.sgml} | 30 +++++++++++++--------------
doc/src/sgml/reference.sgml | 2 +-
src/backend/commands/wait.c | 8 +++----
src/test/recovery/t/049_wait_for_lsn.pl | 9 ++++----
6 files changed, 26 insertions(+), 27 deletions(-)
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 <acronym>LSN</acronym> 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
- <xref linkend="sql-waitfor"/> command to block further processing until
+ <xref linkend="sql-wait"/> command to block further processing until
the standby's WAL replay process reaches (or exceeds) the specified
<acronym>LSN</acronym>.
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.
<!ENTITY update SYSTEM "update.sgml">
<!ENTITY vacuum SYSTEM "vacuum.sgml">
<!ENTITY values SYSTEM "values.sgml">
-<!ENTITY waitFor SYSTEM "wait_for.sgml">
+<!ENTITY wait SYSTEM "wait.sgml">
<!-- applications and utilities -->
<!ENTITY clusterdb SYSTEM "clusterdb.sgml">
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 @@
<!--
-doc/src/sgml/ref/wait_for.sgml
+doc/src/sgml/ref/wait.sgml
PostgreSQL documentation
-->
-<refentry id="sql-waitfor">
- <indexterm zone="sql-waitfor">
- <primary>WAIT FOR</primary>
+<refentry id="sql-wait">
+ <indexterm zone="sql-wait">
+ <primary>WAIT</primary>
</indexterm>
<refmeta>
- <refentrytitle>WAIT FOR</refentrytitle>
+ <refentrytitle>WAIT</refentrytitle>
<manvolnum>7</manvolnum>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
- <refname>WAIT FOR</refname>
+ <refname>WAIT</refname>
<refpurpose>wait for WAL to reach a target <acronym>LSN</acronym></refpurpose>
</refnamediv>
@@ -225,7 +225,7 @@ WAIT FOR LSN '<replaceable class="parameter">lsn</replaceable>'
<refsect1>
<title>Notes</title>
<para>
- <command>WAIT FOR</command> must be executed as a top-level command.
+ <command>WAIT</command> must be executed as a top-level command.
It cannot be executed from a function, procedure, or
<command>DO</command> 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 '<replaceable class="parameter">lsn</replaceable>'
</para>
<para>
- <command>WAIT FOR</command> waits until the specified
+ <command>WAIT</command> waits until the specified
<parameter>lsn</parameter> is reached according to the specified
<parameter>mode</parameter>. The <literal>standby_replay</literal> mode
waits for the LSN to be replayed (applied to the database), which is
@@ -306,12 +306,12 @@ WAIT FOR LSN '<replaceable class="parameter">lsn</replaceable>'
</para>
<para>
- <command>WAIT FOR</command> compares only the numeric
+ <command>WAIT</command> compares only the numeric
<acronym>LSN</acronym>; 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
- <command>WAIT FOR</command> will return <literal>success</literal>
+ <command>WAIT</command> will return <literal>success</literal>
as soon as the position used by the selected wait mode reaches or
passes the numeric <acronym>LSN</acronym>, regardless of which
timeline that <acronym>LSN</acronym> belongs to. Applications that need to
@@ -320,11 +320,11 @@ WAIT FOR LSN '<replaceable class="parameter">lsn</replaceable>'
</para>
<para>
- On a standby server, <command>WAIT FOR</command> sessions may be
+ On a standby server, <command>WAIT</command> 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 <command>WAIT FOR</command> on a standby
+ doing. Applications using <command>WAIT</command> on a standby
should be prepared to handle such interruptions, for example by
retrying the command or falling back to an alternative mechanism.
</para>
@@ -335,7 +335,7 @@ WAIT FOR LSN '<replaceable class="parameter">lsn</replaceable>'
<title>Examples</title>
<para>
- You can use <command>WAIT FOR</command> command to wait for
+ You can use the <command>WAIT</command> command to wait for
the <type>pg_lsn</type> value. For example, an application could update
the <literal>movie</literal> table and get the <acronym>lsn</acronym> after
changes just made. This example uses <function>pg_current_wal_insert_lsn</function>
@@ -353,7 +353,7 @@ postgres=# SELECT pg_current_wal_insert_lsn();
(1 row)
</programlisting>
- Then an application could run <command>WAIT FOR</command>
+ Then an application could run <command>WAIT</command>
with the <parameter>lsn</parameter> 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
</para>
<para>
- The same example uses <command>WAIT FOR</command> with
+ The same example uses <command>WAIT</command> with the
<parameter>NO_THROW</parameter> option:
<programlisting>
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;
</reference>
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
[parent: 6c44473c2dee]