[Alvaro Herrera <alvherre@alvh.no-ip.org>]

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"

Attachments:

0001-Rework-paragraphs-in-replication-slots-docs.patch (text/x-diff, 2.5K) download
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