DOCS - inactive_since field readability

From: Peter Smith <smithpb2250(at)gmail(dot)com>
To: PostgreSQL Hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org>
Subject: DOCS - inactive_since field readability
Date: 2025-02-07 06:34:45
Message-ID: CAHut+PssvVMTWVtUPto6HbPO8pgVsvtzndt_FdBomA_Oq4zf3w@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

Hi hackers.

This thread proposes to improve the readability of the
'inactive_since' field description (see pg_replication_slots system
view).

No changes to any facts, just the wording.

The current description looks like this:
------
The time when the slot became inactive. NULL if the slot is currently
being streamed. If the slot becomes invalid, this value will never be
updated. Note that for slots on the standby that are being synced from
a primary server (whose synced field is true), the inactive_since
indicates the time when slot synchronization (see Section 47.2.3) was
most recently stopped. NULL if the slot has always been synchronized.
On standby, this is useful for slots that are being synced from a
primary server (whose synced field is true) so they know when the slot
stopped being synchronized.
------

Notice there are two very different descriptions depending on the context:
- one for when the replication slot is on the primary server
- and another description for when the slot is on the standby and
being synced from the primary.

e.g. how to interpret NULL values is entirely different:
* NULL if the slot is currently being streamed.
* NULL if the slot has always been synchronized.

IMO the separation of these distinct contexts is not as apparent as it
could be ==> Patch 0001.

~~~

Patch 0001.

This patch simply adds a blank line between these description parts.

======

Patch 0002 (optional)

The 2nd part description seems overly wordy due to unnecessary repetitions.
* "Note that for slots on the standby that are being synced from a
primary server (whose synced field is true) ..."
* "On standby, this is useful for slots that are being synced from a
primary server (whose synced field is true) ..."

I've had a go at rewording this paragraph in the 0002 patch.

======

Thoughts?

======
Kind Regards,
Peter Smith.
Fujitsu Australia

Attachment Content-Type Size
v1-0001-DOCS-inactive_since.-Add-blank-line.patch application/octet-stream 959 bytes
v1-0002-DOCS-inactive_since.-2nd-para-wording.patch application/octet-stream 1.9 KB

Browse pgsql-hackers by date

  From Date Subject
Next Message wenhui qiu 2025-02-07 06:40:22 Re: Trigger more frequent autovacuums of heavy insert tables
Previous Message Michael Paquier 2025-02-07 06:07:18 Re: Statistics Import and Export