database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2026-10-23 13:29:09 +03:00
Code Activity

Rename the WAIT FOR command to WAIT in the documentation

Browse Source 
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
cb2c696b1d: 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
This commit is contained in:
Alexander Korotkov
2026-09-14 14:13:30 +03:00
parent f260c03bcc
commit 1a562a2661
7 changed files with 28 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/src/sgml/high-availability.sgml
View File

@@ -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>.

2
doc/src/sgml/ref/allfiles.sgml
View File

@@ -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">

30
doc/src/sgml/ref/wait_for.sgml → doc/src/sgml/ref/wait.sgml
View File

@@ -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 &mdash; 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>

2
doc/src/sgml/reference.sgml
View File

@@ -217,7 +217,7 @@
&update;
&vacuum;
&values;
&waitFor;
&wait;
</reference>

4
doc/src/sgml/release-19.sgml
View File

@@ -56,7 +56,7 @@
<listitem>
<para>
A new <link linkend="sql-waitfor"><command>WAIT FOR</command></link>
A new <link linkend="sql-wait"><command>WAIT</command></link>
command that waits until a standby has replayed changes up to a chosen
point, thereby supporting <quote>read-your-writes</quote> query patterns
on standbys.
@@ -1501,7 +1501,7 @@ Author: Alexander Korotkov <akorotkov@postgresql.org>
<listitem>
<para>
Add <link linkend="sql-waitfor"><command>WAIT FOR</command></link> command to allow standbys to wait for <link linkend="wal-internals"><acronym>LSN</acronym></link> values to be written, flushed, or replayed (Kartyshov Ivan, Alexander Korotkov, Xuneng Zhou)
Add <link linkend="sql-wait"><command>WAIT</command></link> command to allow standbys to wait for <link linkend="wal-internals"><acronym>LSN</acronym></link> values to be written, flushed, or replayed (Kartyshov Ivan, Alexander Korotkov, Xuneng Zhou)
<ulink url="&commit_baseurl;447aae13b">&sect;</ulink>
<ulink url="&commit_baseurl;49a181b5d">&sect;</ulink>
</para>

8
src/backend/commands/wait.c
View File

@@ -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

9
src/test/recovery/t/049_wait_for_lsn.pl
View File

@@ -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