Thread
Commits
-
Doc: Improve pg_replication_slots.inactive_since description.
- 164bac92f08c 18.0 landed
-
DOCS - inactive_since field readability
Peter Smith <smithpb2250@gmail.com> — 2025-02-07T06:34:45Z
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
-
Re: DOCS - inactive_since field readability
Amit Kapila <amit.kapila16@gmail.com> — 2025-02-11T11:10:48Z
On Fri, Feb 7, 2025 at 12:05 PM Peter Smith <smithpb2250@gmail.com> wrote: > > > I've had a go at rewording this paragraph in the 0002 patch. > The change in 0001 looks odd after seeing it in HTML format. We should either add one empty line between two paragraphs otherwise it doesn't appear good. Did you see multi-paragraphs in any other column definitions? For the 0002 patch, I find the following changes as improvements, * <para> - Note that for slots on the standby to + For standby slots * On standby, this is useful for slots - that are being synced from a primary server (whose - <structfield>synced</structfield> field is <literal>true</literal>) - so they know when the slot stopped being synchronized. to This helps standby slots + track when synchronization was interrupted. Other than that, I find the current wording okay. -- With Regards, Amit Kapila. -
Re: DOCS - inactive_since field readability
Peter Smith <smithpb2250@gmail.com> — 2025-02-13T22:33:35Z
On Tue, Feb 11, 2025 at 10:10 PM Amit Kapila <amit.kapila16@gmail.com> wrote: > ... > The change in 0001 looks odd after seeing it in HTML format. We should > either add one empty line between two paragraphs otherwise it doesn't > appear good. Did you see multi-paragraphs in any other column > definitions? > > For the 0002 patch, I find the following changes as improvements, > * > <para> > - Note that for slots on the standby > to > + For standby slots > > * > On standby, this is useful for slots > - that are being synced from a primary server (whose > - <structfield>synced</structfield> field is <literal>true</literal>) > - so they know when the slot stopped being synchronized. > to > This helps standby slots > + track when synchronization was interrupted. > > Other than that, I find the current wording okay. > Hi Amit, thanks for the feedback! ////// Patch 0001 The pg_replication_slots system view is unusual in that there can be entirely different descriptions of the same field depending on the context, such as: a- for logical slots b- for physical slots c- for primary servers versus standby servers IIUC your 0001 feedback says that a blank line might be ok, but just doing it for 'active_since' and nothing else makes it look odd. So, I have modified the 0001 patch to add blank lines separating those different contexts (e.g. a,b,c) for all fields. I think it improves the readability. In passing. - changed null to <literal>NULL</literal> - changed true to <literal>true</literal> - changed false to <literal>false</literal> ////// Patch 0002 Modified the text as suggested. ====== Kind Regards, Peter Smith. Fujitsu Australia
-
Re: DOCS - inactive_since field readability
Amit Kapila <amit.kapila16@gmail.com> — 2025-02-14T05:06:45Z
On Fri, Feb 14, 2025 at 4:04 AM Peter Smith <smithpb2250@gmail.com> wrote: > > On Tue, Feb 11, 2025 at 10:10 PM Amit Kapila <amit.kapila16@gmail.com> wrote: > > > ... > > The change in 0001 looks odd after seeing it in HTML format. We should > > either add one empty line between two paragraphs otherwise it doesn't > > appear good. Did you see multi-paragraphs in any other column > > definitions? > > > > Patch 0001 > > The pg_replication_slots system view is unusual in that there can be > entirely different descriptions of the same field depending on the > context, such as: > a- for logical slots > b- for physical slots > c- for primary servers versus standby servers > > IIUC your 0001 feedback says that a blank line might be ok, but just > doing it for 'active_since' and nothing else makes it look odd. > No, I meant to say that the description didn't looked any better to me even after your 0001 patch. The second paragraph started immediately in the next line which doesn't make it look any better. If we really want to make it look better then one more additional line is required. However, I don't want to go in that direction unless we have some history of writing the docs similarly. I suggest let's go with your 0002 patch as that makes the description concise and clear. -- With Regards, Amit Kapila.
-
Re: DOCS - inactive_since field readability
Peter Smith <smithpb2250@gmail.com> — 2025-02-16T20:35:46Z
On Fri, Feb 14, 2025 at 4:06 PM Amit Kapila <amit.kapila16@gmail.com> wrote: > ... > > No, I meant to say that the description didn't looked any better to me > even after your 0001 patch. The second paragraph started immediately > in the next line which doesn't make it look any better. If we really > want to make it look better then one more additional line is required. > However, I don't want to go in that direction unless we have some > history of writing the docs similarly. I suggest let's go with your > 0002 patch as that makes the description concise and clear. > OK. My blank lines patch has been abandoned. Here is just the 'inactive_since' description patch (now called 0001). ====== Kind Regards, Peter Smith. Fujitsu Australia
-
Re: DOCS - inactive_since field readability
Amit Kapila <amit.kapila16@gmail.com> — 2025-02-17T09:30:09Z
On Mon, Feb 17, 2025 at 2:06 AM Peter Smith <smithpb2250@gmail.com> wrote: > > On Fri, Feb 14, 2025 at 4:06 PM Amit Kapila <amit.kapila16@gmail.com> wrote: > > > ... > > > > No, I meant to say that the description didn't looked any better to me > > even after your 0001 patch. The second paragraph started immediately > > in the next line which doesn't make it look any better. If we really > > want to make it look better then one more additional line is required. > > However, I don't want to go in that direction unless we have some > > history of writing the docs similarly. I suggest let's go with your > > 0002 patch as that makes the description concise and clear. > > > > OK. My blank lines patch has been abandoned. Here is just the > 'inactive_since' description patch (now called 0001). > Looks good to me. I'll push this tomorrow unless there are any further comments/suggestions. -- With Regards, Amit Kapila.