Re: WAIT FOR NO_THROW option could use some documentation

Hi,

Thanks for raising this and proposing the patch!

On Tue, Sep 1, 2026 at 6:26 AM Kiran Kaki <itskkpg(at)gmail(dot)com> wrote:
>
> 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.

+ 1. I prefer this direction more.

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

These lines seem to be useful.

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

I am not the author who added the option. So the following are just
some random guesses for the motivation of introducing it after doing
some archeological works[1] [2] [3] [4].

Different return statuses were introduced so that an application could
determine why a wait ended. Reaching the target LSN, reaching the
timeout, and discovering that the server is no longer in recovery are
operationally different results. Reporting them as 'success',
'timeout', and 'not in recovery' gives clients a stable,
machine-readable interface instead of forcing them to parse error
messages, which may also be localized.

'NO_THROW' was added to make those statuses available for ordinary
application control flow. Without it, 'timeout' and 'not in recovery'
are raised as SQL errors. With it, they are returned as status values,
allowing the application to retry, report replication lag, refresh its
routing information, or direct a subsequent read to the primary. In
that sense, 'NO_THROW' selects how these expected wait outcomes are
reported: through the error channel or through the result row.

Avoiding an aborted transaction is a secondary benefit. When
'NO_THROW' returns a status, an explicit transaction remains usable;
otherwise, the application must roll back the transaction or to a
savepoint. But transaction preservation was not the principal
motivation. Without distinct return statuses, merely suppressing
errors would be of little use because the application would not know
whether the target LSN had actually been reached.

[This piece is written and revised by Sol from my instructions. I
don't have enough time to write a version of mine.]

[1] https://www.postgresql.org/message-id/ZtUF17gF0pNpwZDI%40paquier.xyz
[2] https://www.postgresql.org/message-id/E1t3wZa-002Dtg-PT%40gemulon.postgresql.org
[3] https://www.postgresql.org/message-id/CAPpHfduN68AzUHvzzPG80qwa-27QXjd820tzcjoUk2Tc6_O%3D5A%40mail.gmail.com
[4] https://www.postgresql.org/message-id/CAPpHfdt5VCM1DoodvVoiRUaoRuXrNEzAmrMQ-eLa0E7wByXaKw@mail.gmail.com

One side-note -- please read the section related to top-posting in this page:

"Finally, our community generally does not "top post" in response to
mailing list threads (See Wikipedia: Top Postingfor a definition of
top posting, and Top Posting Deprecated for discussion of why we
discourage it)."

https://wiki.postgresql.org/wiki/Mailing_Lists

--
Regards,
Xuneng Zhou
HighGo Software Co., Ltd.