Message-ID: <6b9a99cd3fc0fb7657b6884552fd5b4744bb234a.camel@cybertec.at>
Subject: Re: Inaccurate statement about log shipping replication mode
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: Robert Treat <rob@xzilla.net>
Cc: Artem Gavrilov <artem.gavrilov@percona.com>, Michael Paquier
	 <michael@paquier.xyz>, pgsql-docs@lists.postgresql.org
Date: Wed, 03 Sep 2025 09:37:08 +0200
In-Reply-To: 
 <CABV9wwPDLLRp0se_2ir9zkcWoy8FOTbbrrrygDP4aO8w3gSSEw@mail.gmail.com>
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>
	 <CABV9wwPDLLRp0se_2ir9zkcWoy8FOTbbrrrygDP4aO8w3gSSEw@mail.gmail.com>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
User-Agent: Evolution 3.56.2 (3.56.2-1.fc42) 
MIME-Version: 1.0
Archived-At: 
 <https://www.postgresql.org/message-id/6b9a99cd3fc0fb7657b6884552fd5b4744bb234a.camel%40cybertec.at>
Precedence: bulk

On Tue, 2025-09-02 at 11:10 -0400, Robert Treat wrote:
> 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)."

Chapter 26.2. is "Log-Shipping Standby Servers".
The first line seems to confirm what you are saying:

    Continuous archiving can be used to create a high availability (HA)
    cluster configuration with one or more standby servers ready to
    take over operations if the primary server fails. This capability
    is widely referred to as warm standby or log shipping.

But one of the subsections is 26.2.5. "Streaming Replication", which
suggests that streaming replication is a kind of log shipping.

> 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".
>=20
> 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.
>=20
> 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.

I agree that it is a worthwhile goal to clarify the terms, and I
think that the whole chapter should be reorganized:

Sections 26.2.5. to 26.2.9. should be moved to a new chapter
26.3. "Streaming Replication" (which will renumber the present 26.3.
and 26.4.).

Perhaps "WAL shipping" would be a better term, with "WAL streaming"
as alternative.

But that would be a bigger endeavour that would require going over
bigger parts of the documentation.  If you want to do that, I'd be
happy to review it.

But I think that the factually wrong statement that my patch
tries to address should get fixed first - who knows how long the
bigger patch would take.

I am OK with Michael's suggestion to just remove the wrong line,
although it wouldn't be bad to have an explanation of what we mean
by "asynchronous" here.

Yours,
Laurenz Albe