pg.ddx.io  pgsql-hackers@postgresql.org mailing list archive  
help / color / mirror / Atom feed
minor 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>
  2024-01-16 06:08 ` Re: minor replication slot docs edits Bharath Rupireddy <bharath.rupireddyforpostgres@gmail.com>
  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-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   ` Re: minor replication slot docs edits 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-15 15:37 minor replication slot docs edits Alvaro Herrera <alvherre@alvh.no-ip.org>
  2024-01-16 06:08 ` Re: minor replication slot docs edits Bharath Rupireddy <bharath.rupireddyforpostgres@gmail.com>
@ 2024-01-18 10:49   ` Alvaro Herrera <alvherre@alvh.no-ip.org>
  2024-01-18 22:56     ` Re: minor replication slot docs edits Peter Smith <smithpb2250@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-15 15:37 minor replication slot docs edits Alvaro Herrera <alvherre@alvh.no-ip.org>
  2024-01-16 06:08 ` Re: minor replication slot docs edits Bharath Rupireddy <bharath.rupireddyforpostgres@gmail.com>
  2024-01-18 10:49   ` Re: minor replication slot docs edits Alvaro Herrera <alvherre@alvh.no-ip.org>
@ 2024-01-18 22:56     ` Peter Smith <smithpb2250@gmail.com>
  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