Re: Mention idle_replication_slot_timeout in pg_replication_slots docs

On Thu, Jun 26, 2025 at 1:33 PM Fujii Masao <masao.fujii@oss.nttdata.com> wrote:
>
>
>
> On 2025/06/26 15:46, Nisha Moond wrote:
> > On Wed, Jun 25, 2025 at 9:56 PM Fujii Masao <masao.fujii@oss.nttdata.com> wrote:
> >>
> >> Hi,
> >>
> >> The pg_replication_slots documentation mentions only max_slot_wal_keep_size
> >> as a condition under which the wal_status column can show unreserved or lost.
> >> However, since commit ac0e33136ab, idle_replication_slot_timeout can also
> >> cause this behavior when it is set. This has not been documented yet.
> >> https://www.postgresql.org/docs/devel/view-pg-replication-slots.html
> >>
> >
> > +1 to the doc update.
>
> Thanks for the review!
>
>
> >> So, how about updating the documentation to also mention
> >> idle_replication_slot_timeout as a factor that can cause wal_status to
> >> become unreserved or lost? Patch attached.
> >>
> >
> > Since idle_replication_slot_timeout can only cause wal_status to
> > become 'lost' and not 'unreserved', perhaps we can reword the sentence
> > slightly for clarity, suggestion -
> > "The last two states are seen when max_slot_wal_keep_size is
> > non-negative and, the 'lost' state may also appear when
> > idle_replication_slot_timeout is greater than zero."
>
> I was thinking that when idle_replication_slot_timeout triggers,
> the following functions are called, and that wal_status can become
> "unreserved" before ReplicationSlotRelease() runs. It's very short
> period, though. Am I wrong?
>
> ReplicationSlotMarkDirty();
> ReplicationSlotSave();
> ReplicationSlotRelease();
>

Thank you for pointing it out.
You are correct that while the checkpointer is in the process of
invalidating a slot, it sets its PID as the slot’s active_pid. During
this short window, if a user queries pg_replication_slot, the
underlying function pg_get_replication_slots will compute the
wal_status as 'unreserved' for the invalidated slot because the slot
has a valid active_pid.

That said, it's reasonable to mention in the doc that 'unreserved' may
appear when idle_replication_slot_timeout is greater than zero, as
this can indeed happen. So, let's retain the current description.

However, this behavior isn’t specific to
idle_replication_slot_timeout. For example, when a slot is being
invalidated due to a different cause "wal_level_insufficient",
'unreserved' may also briefly appear in wal_status.

The current patch LGTM.

--
Thanks,
Nisha