Обсуждение: Documentation does not mention that basebackup could not be used on newer major version

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.

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

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