Re: Inaccurate statement about log shipping replication mode

On Wed, Sep 03, 2025 at 09:37:08AM +0200, Laurenz Albe wrote:
> 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.).

I would not disagree with that, the situation in the docs can be
confusing for one, as we mix file-based WAL files moved around and
streaming with the replication protocol.

One interesting portion is about replication slots, where we rely on
XLogGetReplicationSlotMinimumLSN() to decide the retention threshold,
Physical slots are updated in WAL senders via
PhysicalConfirmReceivedLocation, meaning that the replication protocol
is required.  Mixing that with the file-shipping part is a mistake.

Just moving the contents to a new "Streaming" section sounds like an
improvement, but the "log-shipping" part would still suck.  So this
stands for cleanup as well, providing a better split.  Perhaps we
should embrace the term "file-based WAL shipping" or "file-based log
shipping" and use that, giving a structure of:
* WAL shipping methods, log-shipping methods or just "Log Shipping"
** File-based WAL shipping
** Streaming

Warm standbys can use both methods.  The part about planning,
operation and preparing may be worth splitting outside the "method"
portion..  The "continuous" archiving on standbys is not about
streaming, but about the file-based method, so it would need to be
inside the file-based subsection.  We could replace "Log" with just
"WAL", as well, if we're looking at more standardization of the whole
area, while on it.

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

Perhaps that stands for improvement and more standarization.  This
term originates from 5e550acbc4d1 in 2006.  The industry has changed a
lot since and there may be standard terms which are much more adapted
for the "modern" user, even if there's a lot of Postgres-ism in the
architecture and how things are done.  There have been some proposals,
but nobody really stood up to commit something.

> 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.

Yeah, this statement is confusing as-is because there is no
dependency with the timing of a transaction commit, records may be
shipped before or after depending on how your system balances your IO
and/or CPU.  I am not sure if this is worth applying on its own, TBH,
because this stuff needs much more rework than a simple sentence.  If
somebody takes the time to write a patch, I'd be OK to step in this
time for review and doing some reorganization of the whole section,
even if that would mean a HEAD-only change.  I had the attached staged
at some point, for reference.

Adding David Steele in CC, I recall that he may have done a proposal
around all that for the docs, and he's involved in backrest.
--
Michael