DOCS - pg_replication_slot . Fix the 'inactive_since' description

From: Peter Smith <smithpb2250(at)gmail(dot)com>
To: PostgreSQL Hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org>
Subject: DOCS - pg_replication_slot . Fix the 'inactive_since' description
Date: 2024-09-02 00:16:50
Message-ID: CAHut+PuvsyA5v8y7rYoY9mkDQzUhwaESM05yCByTMaDoRh30tA@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

Hi hackers. While reviewing another thread I had cause to look at the
docs for the pg_replication_slot 'inactive_since' field [1] for the
first time.

I was confused by the description, which is as follows:
----
inactive_since timestamptz
The time since the slot has become inactive. NULL if the slot is
currently being used.
----

Then I found the github history for the patch [2], and the
accompanying long thread discussion [3] about the renaming of that
field. I have no intention to re-open that can-of-worms, but OTOH I
feel the first sentence of the field description is wrong and needs
fixing.

Specifically, IMO describing something as "The time since..." means
some amount of elapsed time since some occurrence, but that is not the
correct description for this timestamp field.

This is not just a case of me being pedantic. For example, here is
what Chat-GPT had to say:
----
I asked:
What does "The time since the slot has become inactive." mean?

ChatGPT said:
"The time since the slot has become inactive" refers to the duration
that has passed from the moment a specific slot (likely a database
replication slot or a similar entity) stopped being active. In other
words, it measures how much time has elapsed since the slot
transitioned from an active state to an inactive state.

For example, if a slot became inactive 2 hours ago, "the time since
the slot has become inactive" would be 2 hours.
----

To summarize, the current description wrongly describes the field as a
time duration:
"The time since the slot has become inactive."

I suggest replacing it with:
"The slot has been inactive since this time."

The attached patch makes this suggested change.

======
[1] docs - https://www.postgresql.org/docs/devel/view-pg-replication-slots.html
[2] thread - https://www.postgresql.org/message-id/CA+Tgmob_Ta-t2ty8QrKHBGnNLrf4ZYcwhGHGFsuUoFrAEDw4sA@mail.gmail.com
[3] push - https://github.com/postgres/postgres/commit/6d49c8d4b4f4a20eb5b4c501d78cf894fa13c0ea

Kind Regards,
Peter Smith.
Fujitsu Australia

Attachment Content-Type Size
v1-0001-fix-description-for-inactive_since.patch application/octet-stream 1003 bytes

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Michael Paquier 2024-09-02 00:30:20 Re: In-placre persistance change of a relation
Previous Message Michael Paquier 2024-09-02 00:10:26 Re: [PATCH] pg_stat_activity: make slow/hanging authentication more visible