Re: WAIT FOR NO_THROW option could use some documentation

Hi Rithvika,

Thanks for the patch, that was a quick turnaround. The examples of
retrying the wait or directing
subsequent reads to the primary explain the intended client control flow
and address Peter's concern.

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

This seems a little too broad. If WAIT FOR is executed after a
savepoint, the application can recover using ROLLBACK TO SAVEPOINT
without discarding work performed before the savepoint. Previously
committed work is also unaffected when the command is executed in
autocommit mode.

As a suggestion, perhaps this part could say:

* Use this option when a timeout or the server not being in recovery
is an expected outcome that the application can handle, for example by
retrying the wait or directing subsequent reads to the primary. Without
this option, either outcome raises an error. Within a transaction
block, the application must then roll back the transaction or roll back
to a savepoint before issuing further commands.*

> + 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
> + <literal>TIMEOUT</literal> is also specified.

This distinction is useful. I suggest saying "changes only how these
wait outcomes are reported" instead of "affects only the outcome",
since NO_THROW changes the reporting behavior rather than the outcome
of the wait itself.

As a suggestion, this could read:

* This option changes only how these wait outcomes are reported.
Errors that prevent the command from running are still raised. The
option also does not limit how long the command waits; specify TIMEOUT
to bound the wait.*

Regards,
Kiran Kaki

On Mon, Aug 31, 2026 at 11:39 AM Rithvika Devisetti <
devisettirithvika(at)gmail(dot)com> wrote:

>
> On Sun, 2026-08-31 at 07:47 +0200, Peter Eisentraut wrote:
> > I don't find any documentation for the WAIT FOR NO_THROW option other
> > than a few short sentences in the man page about what it does
> > technically. But I don't find anything about why one would want to use
> > it (or not).
>
> Hello,
>
> Attached is a patch.
>
> The reason I settled on is that the difference is transactional. The
> error raised without NO_THROW aborts the current transaction, so a
> caller that treats a timeout as recoverable (retry, fall back to the
> primary, report the delay) has to roll back first and discard whatever
> else that transaction had done. With NO_THROW the session is
> unaffected and the caller can branch on the returned status. I
> confirmed this: a timeout inside a transaction block leaves it aborted,
> while the same wait with NO_THROW leaves the session usable.
>
> Regards,
> Rithvika Devisetti
>
> On Mon, Aug 31, 2026 at 7:47 AM Peter Eisentraut <peter(at)eisentraut(dot)org>
> wrote:
>
>> I don't find any documentation for the WAIT FOR NO_THROW option other
>> than a few short sentences in the man page about what it does
>> technically. But I don't find anything about why one would want to use
>> it (or not). I suspect this option was added with some particular
>> client control flow in mind, but I think this needs to be explained
>> somewhere.
>>
>>
>>