Feedback-ID: ia2694551:Fastmail
Date: Mon, 15 Jan 2024 16:37:49 +0100
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
To: Pg Hackers <pgsql-hackers@lists.postgresql.org>
Subject: minor replication slot docs edits
Message-ID: <202401151537.ryhysqfncs6d@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="shb23uhsdnji4c2q"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
Archived-At: 
 <https://www.postgresql.org/message-id/202401151537.ryhysqfncs6d%40alvherre.pgsql>
Precedence: bulk


--shb23uhsdnji4c2q
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit

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"

--shb23uhsdnji4c2q
Content-Type: text/x-diff; charset=utf-8
Content-Disposition: attachment;
	filename="0001-Rework-paragraphs-in-replication-slots-docs.patch"

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


--shb23uhsdnji4c2q--