From 094cff5ad50715eeac2d94430c340c877f10826c Mon Sep 17 00:00:00 2001 From: Rithvika Devisetti Date: Mon, 31 Aug 2026 10:46:11 -0700 Subject: [PATCH] doc: Explain when to use the WAIT FOR NO_THROW option The description of NO_THROW covered what the option does but not why one would choose it. Explain that the error raised otherwise aborts the current transaction, along with the reason to omit the option, and note that NO_THROW neither suppresses errors unrelated to the wait's outcome nor bounds the wait itself. Reported-by: Peter Eisentraut --- doc/src/sgml/ref/wait_for.sgml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/src/sgml/ref/wait_for.sgml b/doc/src/sgml/ref/wait_for.sgml index 01dc2a84a1a..3ce74429d84 100644 --- a/doc/src/sgml/ref/wait_for.sgml +++ b/doc/src/sgml/ref/wait_for.sgml @@ -164,6 +164,24 @@ WAIT FOR LSN 'lsn' running on the primary. In this case the result status can be get from the return value. + + + Use this when an unsuccessful wait is an expected outcome rather + than a fault. The error raised otherwise aborts the current + transaction, so a caller that responds to a timeout by waiting + again or reading from the primary instead would have to roll back + and discard any work already done. Omit it when the application + cannot usefully proceed without the target + LSN, since a returned status, unlike an error, + is silently ignored by a caller that does not inspect it. + + + + This option affects only the outcome of the wait. Conditions that + prevent the command from running at all still raise an error, and + the wait is still unbounded unless + TIMEOUT is also specified. + -- 2.54.0