Re: Should the WAIT FOR command tag be "WAIT" or "WAIT FOR"?

On Mon, Aug 31, 2026 at 7:52 AM Xuneng Zhou <xunengzhou(at)gmail(dot)com> wrote:
> On Sat, Aug 29, 2026 at 5:40 AM Masahiko Sawada <sawada(dot)mshk(at)gmail(dot)com> wrote:
> >
> > On Fri, Aug 28, 2026 at 1:11 PM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> > >
> > > Masahiko Sawada <sawada(dot)mshk(at)gmail(dot)com> writes:
> > > > While reviewing a patch for the WAIT FOR command I noticed that its
> > > > command tag is "WAIT" rather than "WAIT FOR". I could not find this
> > > > discussed in the main thread, although I have not read all of them, so
> > > > I might miss something. I want to confirm it because a command tag is
> > > > not something we can revisit later when we release v19.0.
> > >
> > > I think it's fine. The FOR is a noise word that's useful only to
> > > make the command's grammar vaguely resemble English. For precedent,
> > > consider INSERT, which must have INTO but that's not part of the
> > > command tag.
> >
> > Good point. A difference between INSERT and WAIT is that the doc uses
> > "WAIT FOR" as its command name instead of "WAIT" whereas it uses
> > "INSERT" for INSERT statements:
> >
> > % git grep -e "<command>WAIT.*</command>"
> > doc/src/sgml/ref/wait_for.sgml: <command>WAIT FOR</command> must be
> > executed as a top-level command.
> > doc/src/sgml/ref/wait_for.sgml: <command>WAIT FOR</command> waits
> > until the specified
> > doc/src/sgml/ref/wait_for.sgml: <command>WAIT FOR</command> compares
> > only the numeric
> > doc/src/sgml/ref/wait_for.sgml: <command>WAIT FOR</command> will
> > return <literal>success</literal>
> > doc/src/sgml/ref/wait_for.sgml: On a standby server, <command>WAIT
> > FOR</command> sessions may be
> > doc/src/sgml/ref/wait_for.sgml: doing. Applications using
> > <command>WAIT FOR</command> on a standby
> > doc/src/sgml/ref/wait_for.sgml: You can use <command>WAIT
> > FOR</command> command to wait for
> > doc/src/sgml/ref/wait_for.sgml: Then an application could run
> > <command>WAIT FOR</command>
> > doc/src/sgml/ref/wait_for.sgml: The same example uses <command>WAIT
> > FOR</command> with
> > doc/src/sgml/release-19.sgml: A new <link
> > linkend="sql-wait-for"><command>WAIT FOR</command></link>
> > doc/src/sgml/release-19.sgml:Add <link
> > linkend="sql-wait-for"><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)
> >
> > >
> > > > Strictly the same rule would argue for
> > > > "WAIT FOR LSN", but "WAIT FOR" is the name the manual gives the
> > > > command, and it leaves room if other things become waitable in the
> > > > future.
> > >
> > > If anything, I'd change the manual. "WAIT FOR" is neither short
> > > nor a useful description of what's being waited for. Either "WAIT"
> > > or "WAIT FOR LSN" would be more plausible as a page heading.
> >
> > Agreed.
>
> Thanks for raising this. The above reasoning makes sense to me. Here's
> a patch for it.

Thank you for the patch. I think we should do some additional renames.
1. Change <command>WAIT FOR</command> to <command>WAIT</command> in
the page body.
2. The two error messages in commands/wait.c: WAIT FOR => WAIT
3. The reference id sql-waitfor => sql-wait
4. File name ref/wait_for.sgml => ref/wait.sgml, and the entity
&waitFor => &wait

------
Regards,
Alexander Korotkov
Supabase