Documentation does not mention that basebackup could not be used on newer major version

On Mon, 2023-09-18 at 15:29 +0000, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/16/app-pgbasebackup.html
Description:

https://www.postgresql.org/docs/current/logical-replication.html
Logical replication has excellent paragraph about usecases.

These pages does not have them.
https://www.postgresql.org/docs/current/app-pgdump.html
https://www.postgresql.org/docs/current/app-pgbasebackup.html

My main issue is that `pg_basebackup` page does not mention that this backup
is compatible only with current version of database. I can not do basebackup
on v11 and restore that on v15, for example.

I think that that is amply documented by the fact that pg_basebackup is
*not* mentioned in https://www.postgresql.org/docs/current/upgrading.html .

You can't expect us to enumerate every tool that is not suitable for
upgrading.

Yours,
Laurenz Albe

Did not know that page even exists.

No need to enumerate. It would be nice if you mention that `This tool is
not suitable for restoring data in different major version`.

On Mon, Sep 18, 2023 at 4:08 PM Laurenz Albe <laurenz.albe@cybertec.at>
wrote:

On Mon, Sep 18, 2023 at 10:08:30PM +0200, Laurenz Albe wrote:

On Mon, 2023-09-18 at 15:29 +0000, PG Doc comments form wrote:

My main issue is that `pg_basebackup` page does not mention that this backup
is compatible only with current version of database. I can not do basebackup
on v11 and restore that on v15, for example.

I think that that is amply documented by the fact that pg_basebackup is
*not* mentioned in https://www.postgresql.org/docs/current/upgrading.html .

Yeah. The issue with this one is that it does a direct physical copy
of the files. You cannot expect pg_basebackup to be able to do all
the work that pg_upgrade would do underground, like binary upgrades,
and more.

You can't expect us to enumerate every tool that is not suitable for
upgrading.

Just noting in passing. There is a lot of maintenance effort for
downward compatibility (tools like pg_dump and pg_basebackup at
version N are able to work with a backend version older, say at N-1).
Upward compabitility may work in some cases, even for dumps, still
these would likely require extra manipulation to be able to load to
a version of the backend older than the version of pg_dump used.
Being able to use pg_basebackup to work with older backend versions is
a really important property we try to keep available.
--
Michael