Re: WAIT FOR NO_THROW option could use some documentation

Thank you everyone for the suggestions.
v3 attached, folding in the remaining points.

The description now says the command "reports these outcomes as a
status string instead of raising an error", tying it to the timeout and
promotion cases named just above rather than claiming suppression
generally.

The option entry uses the consolidated wording from earlier in the
thread, and its last paragraph now names what still errors: invalid
inputs (Satya's malformed-LSN and unrecognized-mode examples), and
requesting primary_flush during recovery, which is rejected before the
wait begins, per Xuneng's note.

On Sat, Sep 5, 2026 at 12:23 AM Xuneng Zhou <xunengzhou(at)gmail(dot)com> wrote:

>
>
> On Fri, Sep 4, 2026 at 8:26 AM SATYANARAYANA NARLAPURAM <
> satyanarlapuram(at)gmail(dot)com> wrote:
> >
> >
> >
> > On Thu, Sep 3, 2026 at 4:20 PM Robert Haas <robertmhaas(at)gmail(dot)com>
> wrote:
> >>
> >> On Thu, Sep 3, 2026 at 4:39 PM Peter Eisentraut <peter(at)eisentraut(dot)org>
> wrote:
> >> > On 03.09.26 17:21, SATYANARAYANA NARLAPURAM wrote:
> >> > > Maybe something along these lines - "NO_THROW option safely
> prevents the
> >> > > database
> >> > > from aborting an active transaction, allowing subsequent queries
> within
> >> > > the transaction
> >> > > to proceed without losing prior work"?
> >> >
> >> > Maybe that's what it is meant for, but that seems separate from the
> >> > status reporting mechanism. It could also send an error message to
> the
> >> > client but not abort the transaction on the server.
> >>
> >> I think sending an error without aborting the transaction on the
> >> server would invite too much confusion. But I also wonder if the
> >> documentation's claim that this option will just cause the server to
> >> categorically not throw errors can really be correct. In most places
> >> where we have an error-suppression facility of some kind, it's much
> >> more narrowly scoped.
> >
> >
> > Agree with Robert on this. I would say the error suppression is narrow
> here as well.
>
> Yeah, I also think Robert is right for not claiming it absolutely.
>
> "If NO_THROW is specified, the command returns a status string instead of
> throwing errors."
>
> We may need to soften this line.
>
> > When an incorrect mode or LSN is provided, it throws an error even with
> the NO_THROW option.
> >
> >
> > postgres=# WAIT FOR LSN '0/306EEk0' WITH (TIMEOUT '100ms', NO_THROW,
> MODE primary_flush);
> > ERROR: invalid input syntax for type pg_lsn: "0/306EEk0"
> > postgres=# WAIT FOR LSN '0/306EE0' WITH (TIMEOUT '100ms', NO_THROW, MODE
> primary_flush2);
> > ERROR: unrecognized value for WAIT option "mode": "primary_flush2"
>
> Thanks for testing this. I agree that the behavior is not aligned with the
> description of doc. The behavior itself seems fine to me, what we need to
> change is the doc. These errors are not supposed to be suppressed because
> they are not valid inputs in the first place. Another one error needs
> consideration is primary_flush waiting in standby. Currently, we prevent
> this use by erroring out before entering the wait, hence no_throw option
> cannot suppress it. I think this behavior is fine. To suppressithat error
> implies that we want a new return status like 'in recovery' after valid
> waiting. However, that needs seems not true because we don't expect a
> primary being demoted to a standby. We might still need extra description
> for it.
>
> --
> Regards,
> Xuneng Zhou
> HighGo Software Co., Ltd.
>