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

doc: Explain when to use the WAIT NO_THROW option

Browse Source 
The description of NO_THROW covered what the option does but not when an
application would want it.  Explain that it suits callers that treat
timeout or not in recovery as expected results to be handled as part of
ordinary control flow, note the obligation to check the returned status,
and give the reason to omit the option.

Be precise about the option's scope: it changes only how those two wait
outcomes are reported.  Soften the description's claim that the command
"returns a status string instead of throwing errors" accordingly, and say
that invalid input still raises an error, as does any condition checked
before the wait begins.  Name two of those conditions as examples rather
than listing them, since the set grows.

Author: Rithvika Devisetti <devisettirithvika@gmail.com>
Reported-by: Peter Eisentraut <peter@eisentraut.org>
Reviewed-by: Kiran Kaki <itskkpg@gmail.com>
Reviewed-by: Xuneng Zhou <xunengzhou@gmail.com>
Reviewed-by: Satyanarayana Narlapuram <satyanarlapuram@gmail.com>
Reviewed-by: Alexander Korotkov <aekorotkov@gmail.com>
Discussion: https://postgr.es/m/14415b05-16d0-446f-ba7d-c891db8b3406%40eisentraut.org
Backpatch-through: 19
This commit is contained in:
Alexander Korotkov
2026-09-17 09:32:17 +03:00
parent 999ce9bcd8
commit e87c55f4d8
1 changed files with 35 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
doc/src/sgml/ref/wait.sgml
View File

@@ -54,8 +54,8 @@ WAIT FOR LSN '<replaceable class="parameter">lsn</replaceable>'
(<literal>standby_replay</literal>, <literal>standby_write</literal>,
<literal>standby_flush</literal>), an error is also emitted if the
server is promoted before the <parameter>lsn</parameter> is reached.
If <parameter>NO_THROW</parameter> is specified, the command returns
a status string instead of throwing errors.
If <parameter>NO_THROW</parameter> is specified, the command reports
these outcomes as a status string instead of raising an error.
</para>
<para>
@@ -172,6 +172,39 @@ WAIT FOR LSN '<replaceable class="parameter">lsn</replaceable>'
running on the primary. In this case the result status can be
obtained from the return value.
</para>
<para>
Use this option when <literal>timeout</literal> or
<literal>not in recovery</literal> is an expected result that the
application intends to handle, for example by retrying the wait,
reporting replication delay, or choosing another server for a
subsequent operation. The command then returns the result as a
status, which the application must check before assuming that the
target <acronym>LSN</acronym> was reached. Omit the option when
the application must not proceed unless the target
<acronym>LSN</acronym> is reached, so that an unsuccessful wait
stops normal execution with an error.
</para>
<para>
Returning a status also leaves an explicit transaction usable;
without this option, the corresponding error requires rolling back
the transaction, or rolling back to a savepoint, before further
commands can be issued.
</para>
<para>
This option changes only how <literal>timeout</literal> and
<literal>not in recovery</literal> are reported. Other errors are
still raised. That covers invalid input, such as a malformed
<acronym>LSN</acronym> or an unrecognized option value, and every
condition that is checked before the wait begins, such as
requesting <literal>primary_flush</literal> during recovery or
holding a lock while waiting for a standby
<acronym>LSN</acronym>. The option also does not limit the
duration of the wait; specify <literal>TIMEOUT</literal> for that
purpose.
</para>
</listitem>
</varlistentry>
</variablelist>