Re: Document what is essential and undocumented in pg_basebackup

From: David Steele <david(at)pgmasters(dot)net>
To: Stephen Frost <sfrost(at)snowman(dot)net>, Chapman Flack <chap(at)anastigmatix(dot)net>
Cc: PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>, Magnus Hagander <magnus(at)hagander(dot)net>
Subject: Re: Document what is essential and undocumented in pg_basebackup
Date: 2022-03-09 20:39:37
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

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.


In response to

Browse pgsql-hackers by date

  From Date Subject
Next Message David Steele 2022-03-09 20:43:54 Re: Commitfest 2022-03 One Week in. 3 Commits 213 Patches Remaining
Previous Message Justin Pryzby 2022-03-09 20:37:31 Re: Adding CI to our tree