minor replication slot docs edits
Pursuant to a comment I made a few months ago[1]/messages/by-id/20230413111838.e7yxke2dtwrxw3qy@alvherre.pgsql, 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]: /messages/by-id/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"
Attachments:
0001-Rework-paragraphs-in-replication-slots-docs.patchtext/x-diff; charset=utf-8Download
From c003a2c6ae8d1c177fbd4c1f77b428c5ad24e705 Mon Sep 17 00:00:00 2001
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
Date: Fri, 19 May 2023 20:15:52 +0200
Subject: [PATCH] Rework paragraphs in replication slots docs
Discussion: https://postgr.es/m/20230413111838.e7yxke2dtwrxw3qy@alvherre.pgsql
---
doc/src/sgml/high-availability.sgml | 18 ++++++++++--------
1 file changed, 10 insertions(+), 8 deletions(-)
diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index 9dd52ff275..887366bdec 100644
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -930,25 +930,27 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
<link linkend="hot-standby-conflict">recovery conflict</link> even when the
standby is disconnected.
</para>
+ <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>
<para>
In lieu of using replication slots, it is possible to prevent the removal
of old WAL segments using <xref linkend="guc-wal-keep-size"/>, or by
storing the segments in an archive using
<xref linkend="guc-archive-command"/> or <xref linkend="guc-archive-library"/>.
- However, these methods often result in retaining more WAL segments than
+ A disadvantage of these methods is that they
+ often result in retaining more WAL segments than
required, whereas replication slots retain only the number of segments
- known to be needed. On the other hand, 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"/> limits the size of WAL files
- retained by replication slots.
+ known to be needed.
</para>
<para>
Similarly, <xref linkend="guc-hot-standby-feedback"/> on its own, without
also using a replication slot, provides protection against relevant rows
being removed by vacuum, but provides no protection during any time period
- when the standby is not connected. Replication slots overcome these
- disadvantages.
+ when the standby is not connected.
</para>
<sect3 id="streaming-replication-slots-manipulation">
<title>Querying and Manipulating Replication Slots</title>
--
2.39.2
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] /messages/by-id/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