On 3/9/22 13:46, Stephen Frost wrote:
I don't think it is as reasonable to say, effectively, that you learn
what the irreducibly essential steps of an online base backup are by
reading the source of pg_basebackup, and then intuiting which of the
details you find there are the essential ones and which are outgrowths
of its particular design choices.
Documenting absolutely everything needed to write a good backup tool for
PG strikes me as unlikely to end up actually being useful. Those who
write backup tools for PG are reading the source for PG and likely
wouldn't find such documentation helpful as not everything needed would
be included even if we did try to document everything, making such an
effort a waste of time. The idea that we could document everything
needed and that someone could then write a simple shell script or even a
simple perl script (as pgbackrest started out as ...) from that
documentation that did everything necessary is a fiction that we need to
accept as such and move on from.
I would argue that the "Making a Non-Exclusive Low-Level Backup" and
"Backing Up the Data Directory" sections do contain the minimal
information you need to create a valid backup. I (and others) work hard
to keep these sections up to date.
Arguably it is a bit confusing that "Backing Up the Data Directory" is a
separate section, but that's because we have two backup methods and it
needs to be kept separate. But since it is linked in the appropriate
part of "Making a Non-Exclusive Low-Level Backup" I don't think it is
too big a deal.
If you see something missing then let's add it. But I agree with Stephen
that it is not a good idea to include a simplistic pseudo-solution to a
problem that is anything but simple.
Regards,
-David
