From 57fec71b0f87f7bb0a04a34d082e24324b4fda39 Mon Sep 17 00:00:00 2001 From: Rithvika Devisetti Date: Fri, 4 Sep 2026 22:32:06 -0700 Subject: [PATCH v3] doc: Explain when to use the WAIT FOR NO_THROW option 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. Per discussion, be precise about the option's scope: it changes only how those two wait outcomes are reported. Invalid inputs still raise errors, as does requesting primary_flush during recovery, which is rejected before the wait begins. Soften the description's claim that the command "returns a status string instead of throwing errors" accordingly, and note that the option does not bound the wait. Reported-by: Peter Eisentraut Reviewed-by: Kiran Kaki Reviewed-by: Xuneng Zhou Reviewed-by: Satyanarayana Narlapuram --- doc/src/sgml/ref/wait_for.sgml | 35 ++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/doc/src/sgml/ref/wait_for.sgml b/doc/src/sgml/ref/wait_for.sgml index 04ca9400426..12cf62ed1db 100644 --- a/doc/src/sgml/ref/wait_for.sgml +++ b/doc/src/sgml/ref/wait_for.sgml @@ -54,8 +54,8 @@ WAIT FOR LSN 'lsn' (standby_replay, standby_write, standby_flush), an error is also emitted if the server is promoted before the lsn is reached. - If NO_THROW is specified, the command returns - a status string instead of throwing errors. + If NO_THROW is specified, the command reports + these outcomes as a status string instead of raising an error. @@ -164,6 +164,37 @@ WAIT FOR LSN 'lsn' running on the primary. In this case the result status can be obtained from the return value. + + + Use this option when timeout or + not in recovery 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 LSN was reached. Omit the option when + the application must not proceed unless the target + LSN is reached, so that an unsuccessful wait + stops normal execution with an error. + + + + 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. + + + + This option changes only how timeout and + not in recovery are reported. Other errors are + still raised, including invalid inputs such as a malformed + LSN or an unrecognized option value, and + requesting primary_flush during recovery, which + is rejected before the wait begins. The option also does not + limit the duration of the wait; specify TIMEOUT + for that purpose. + -- 2.54.0