pg.ddx.io pgsql-hackers@postgresql.org mailing list archive
help / color / mirror / Atom feedminor replication slot docs edits
4+ messages / 3 participants
[nested] [flat]
Commits from this thread:
2024-01-18 27d04ed531 Rework text in replication slots documentation
* minor replication slot docs edits
@ 2024-01-15 15:37 Alvaro Herrera <alvherre@alvh.no-ip.org>
0 siblings, 1 reply; 4+ messages in thread
From: Alvaro Herrera @ 2024-01-15 15:37 UTC (permalink / raw)
To: Pg Hackers <pgsql-hackers@lists.postgresql.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
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: minor replication slot docs edits
@ 2024-01-16 06:08 Bharath Rupireddy <bharath.rupireddyforpostgres@gmail.com>
parent: Alvaro Herrera <alvherre@alvh.no-ip.org>
0 siblings, 1 reply; 4+ messages in thread
From: Bharath Rupireddy @ 2024-01-16 06:08 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: Pg Hackers <pgsql-hackers@lists.postgresql.org>
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
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: minor replication slot docs edits
@ 2024-01-18 10:49 Alvaro Herrera <alvherre@alvh.no-ip.org>
parent: Bharath Rupireddy <bharath.rupireddyforpostgres@gmail.com>
0 siblings, 1 reply; 4+ messages in thread
From: Alvaro Herrera @ 2024-01-18 10:49 UTC (permalink / raw)
To: Bharath Rupireddy <bharath.rupireddyforpostgres@gmail.com>; +Cc: Pg Hackers <pgsql-hackers@lists.postgresql.org>
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/
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: minor replication slot docs edits
@ 2024-01-18 22:56 Peter Smith <smithpb2250@gmail.com>
parent: Alvaro Herrera <alvherre@alvh.no-ip.org>
0 siblings, 0 replies; 4+ messages in thread
From: Peter Smith @ 2024-01-18 22:56 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: Bharath Rupireddy <bharath.rupireddyforpostgres@gmail.com>; Pg Hackers <pgsql-hackers@lists.postgresql.org>
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
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2024-01-18 22:56 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2024-01-15 15:37 minor replication slot docs edits Alvaro Herrera <alvherre@alvh.no-ip.org>
2024-01-16 06:08 ` Bharath Rupireddy <bharath.rupireddyforpostgres@gmail.com>
2024-01-18 10:49 ` Alvaro Herrera <alvherre@alvh.no-ip.org>
2024-01-18 22:56 ` Peter Smith <smithpb2250@gmail.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox