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