Обсуждение: minor replication slot docs edits
Pursuant to a comment I made a few months ago[1], I propose the attached changes to replication slots documentation. In essence, I want to explain that replication slots are good, and the max_size GUC, before moving on to explain that the other methods are worse. Thanks [1] https://postgr.es/m/20230413111838.e7yxke2dtwrxw3qy@alvherre.pgsql -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/ "Entristecido, Wutra (canción de Las Barreras) echa a Freyr a rodar y a nosotros al mar"
Вложения
On Mon, Jan 15, 2024 at 9:08 PM Alvaro Herrera <alvherre@alvh.no-ip.org> wrote: > > Pursuant to a comment I made a few months ago[1], I propose the attached > changes to replication slots documentation. In essence, I want to > explain that replication slots are good, and the max_size GUC, before > moving on to explain that the other methods are worse. > > [1] https://postgr.es/m/20230413111838.e7yxke2dtwrxw3qy@alvherre.pgsql Thanks for the patch. The wording looks good to me. However, I have some comments on the placement of the note: 1. How about bundling this in a <note> </note> or <caution> </caution>? + <para> + Beware that replication slots can retain so many WAL segments that they + fill up the space allocated for <literal>pg_wal</literal>. + <xref linkend="guc-max-slot-wal-keep-size"/> can be used to limit the size + of WAL files retained by replication slots. + </para> 2. I think the better place for this note is at the end after the "Similarly, <xref linkend="guc-hot-standby-feedback"/> on its own, without" paragraph. It will then be like we introduce what replication slot is and why it is better over other mechanisms to retain WAL and then caution the users of it retaining WAL. -- Bharath Rupireddy PostgreSQL Contributors Team RDS Open Source Databases Amazon Web Services: https://aws.amazon.com
On 2024-Jan-16, Bharath Rupireddy wrote: > Thanks for the patch. The wording looks good to me. However, I have > some comments on the placement of the note: > > 1. How about bundling this in a <note> </note> or <caution> </caution>? Yeah, I considered this too, but I discarded the idea because my impression of <caution> and <note> was that they attract too much attention off the main text; it should be the other way around. But that's not really something for this patch to solve, and we use <caution> boxes in many other places and nobody complains about this. So I made it a <caution>. > 2. I think the better place for this note is at the end after the > "Similarly, <xref linkend="guc-hot-standby-feedback"/> on its own, > without" paragraph. It will then be like we introduce what replication > slot is and why it is better over other mechanisms to retain WAL and > then caution the users of it retaining WAL. Makes sense. I have pushed it. I made one other terminology change from "primary" to "primary server", but only in that subsection. We use "primary" as a standalone term extensively in other sections of this chapter, and I don't like it very much, but I didn't want to make this more invasive. Another thing I noticed is that we could change all (or most of) the <varname> tags to <xref linkend="guc-..."/>, but it's also a much larger change. Having (some of?) these variable names be links would be useful IMO. -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/
On Thu, Jan 18, 2024 at 9:49 PM Alvaro Herrera <alvherre@alvh.no-ip.org> wrote: ... > > Another thing I noticed is that we could change all (or most of) the > <varname> tags to <xref linkend="guc-..."/>, but it's also a much larger > change. Having (some of?) these variable names be links would be useful > IMO. > +1 to do this. IMO these should all be coded like <link linkend="guc-XXX"><varname>XXX</varname></link>, because the resulting rendering looks much better with the GUC name using a varname font instead of just plain text that <xref> gives. I am happy to take on the task if nobody else wants to. ====== Kind Regards, Peter Smith. Fujitsu Australia