Re: Document what is essential and undocumented in pg_basebackup

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