On Thu, Sep 17, 2026 at 5:53 PM Sami Imseih <samimseih.pg@gmail.com> wrote:
>
> > > Done in v6.
> >
> > Xuneng, Sami, do you think v6 is good enough?
>
> I think the user-facing documentation can be simplified considerably while
> preserving the important information. I prefer the below changes on top
> of v6:
>
> 1/ State directly that WAIT cannot be executed while the current transaction
> holds a snapshot.
> 2/ Clarify that WAIT itself does not acquire a snapshot.
> 3/ Explain that it can therefore be executed before the first snapshot-taking
> statement in a REPEATABLE READ or SERIALIZABLE transaction.
> 4/ Briefly explain why holding a snapshot can prevent a standby wait from
> completing.
>
>
> ```
> <command>DO</command> block. It also cannot be executed while the
> - current transaction holds a snapshot. A transaction running at an
> - isolation level higher than <literal>READ COMMITTED</literal> holds one
> - from its first query until it ends, so <command>WAIT</command> is
> - accepted before that query and rejected after it. An open cursor or an
> - exported snapshot has the same effect at any isolation level.
> - </para>
> -
> - <para>
> - The restriction above exists because such a snapshot could stand in
> - the way of the very replay being waited for: replaying a record that
> - removes rows the snapshot can still see raises a recovery conflict.
> - This conflict could be resolved by delaying the replay or by cancelling
> - this session. Having to run without a snapshot is also the reason why
> - <command>WAIT</command> is a command rather than a function or a procedure,
> - which execute with one held.
> - </para>
> -
> - <para>
> - The other standby modes are not independent of replay either, even though
> - they do not wait for it directly. Their positions advance as WAL arrives,
> - but WAL is recycled only at restartpoints, and a restartpoint cannot be
> - created past a checkpoint record that replay has not reached. While
> - replay is held back, <filename>pg_wal</filename> therefore keeps growing
> - past <xref linkend="guc-max-wal-size"/>, and reception stops once the file
> - system fills.
> + current transaction holds a snapshot.
> + <command>WAIT</command> itself does not acquire a snapshot, so it can be
> + executed before the first snapshot-taking statement in a
> + <literal>REPEATABLE READ</literal> or <literal>SERIALIZABLE</literal>
> + transaction. Holding a snapshot while using a standby wait mode could
> + delay WAL replay and prevent the wait from completing.
> </para>
> ```
Agreed. v7 attached: three paragraphs collapsed into one, close to your
wording. I kept three bits from v6:
* mention the cursor and the exported snapshot as those who may hold snapshots;
* "which standby_replay waits for and the other standby modes
ultimately depend on", so that write and flush are not read as exempt;
* "that is also why WAIT is a command rather than a function or a
procedure", which makes the restriction in the first sentence follow
from the same rule instead of looking arbitrary.
------
Regards,
Alexander Korotkov
Supabase
