MIME-Version: 1.0
References: <175578964049.806.14564779365418625473@wrigleys.postgresql.org>
 <568ff8638e011b2726d06a4b95124ec51ee1e5af.camel@cybertec.at>
 <a67687e233188a43a80b55c4ab8e1115bf2bd947.camel@cybertec.at>
 <aLTYpFWPT8v5JJh1@paquier.xyz>
 <CAFPkQKyGw+dnWZQM6QsqXWY_czqvvwMvF9Qfb4x916ZzHiRHeA@mail.gmail.com>
 <93913aeb398b264ca0dc781095d36d6ad2d3be71.camel@cybertec.at>
 <CAFPkQKzuVjgEs=O40yw1LhBqRmKD4K+_6fHCGR9+j80f0wgoow@mail.gmail.com>
 <60948f2ce0f59a8406208e8feabe667f170e8676.camel@cybertec.at>
In-Reply-To: <60948f2ce0f59a8406208e8feabe667f170e8676.camel@cybertec.at>
From: Robert Treat <rob@xzilla.net>
Date: Tue, 2 Sep 2025 11:10:42 -0400
Message-ID: 
 <CABV9wwPDLLRp0se_2ir9zkcWoy8FOTbbrrrygDP4aO8w3gSSEw@mail.gmail.com>
Subject: Re: Inaccurate statement about log shipping replication mode
To: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: Artem Gavrilov <artem.gavrilov@percona.com>,
 Michael Paquier <michael@paquier.xyz>,
	pgsql-docs@lists.postgresql.org
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Archived-At: 
 <https://www.postgresql.org/message-id/CABV9wwPDLLRp0se_2ir9zkcWoy8FOTbbrrrygDP4aO8w3gSSEw%40mail.gmail.com>
Precedence: bulk

On Tue, Sep 2, 2025 at 8:48=E2=80=AFAM Laurenz Albe <laurenz.albe@cybertec.=
at> wrote:
>
> On Tue, 2025-09-02 at 11:22 +0200, Artem Gavrilov wrote:
> > My original problem was with the first sentence "It should be noted
> > that log shipping is asynchronous". I think your original suggestion
> > "It should be noted that by default, log shipping is asynchronous"
> > sounds good as it highlights from the beginning that there is some
> > variety.
>
> Hm, yes, we could add "by default".
>

I think the issue here is that this section is supposed to focus on
continuous archiving / file based WAL shipping, which is asynchronous.
All of the complexity that is being discussed in this thread is really
about WAL streaming, which IMO should not be discussed here. Per the
docs, "Record-based log shipping is more granular and streams WAL
changes incrementally over a network connection (see Section 26.2.5)."

I actually think the thing that is wrong (or at least confusing) in
the docs is this line "Directly moving WAL records from one database
server to another is typically described as log shipping." because it
is too loose with its definition. I don't recall postgres people
referring to streaming replication as "wal shipping", that term is
pretty exclusively used for continuous archiving. If you look in the
aforementioned 26.2.5. Streaming Replication, the term "shipping" is
only ever used in conjunction with the phrase "file-based log
shipping".

So with that said, I would suggest fixing this by changing the first
sentence of paragraph 4 to "It should be noted that file based log
shipping is asynchronous", as this also emphasizes that this section
is focused on file based wal shipping.

A larger fix would likely involve reworking this section to start with
defining log shipping and how it is used in Postgres, and then
continuing with the file based specific info (something like moving
the third paragraph to the beginning and then editing things for
clarity / readability). I could work up a patch for that if people
were interested.

Robert Treat
https://xzilla.net