Re: Updated backup APIs for non-exclusive backups

On Wed, Apr 6, 2016 at 6:42 AM, Noah Misch <noah(at)leadboat(dot)com> wrote:

> On Tue, Apr 05, 2016 at 08:15:16PM +0200, Magnus Hagander wrote:
> > I've pushed this version, and also added the item from the Brussels
> > developer meeting to actually rewrite the main backup docs to the open
> > items so they are definitely not forgotten for 9.6.
>
> Here's that PostgreSQL 9.6 open item:
>
> * Update of backup documentation (assigned to Bruce at [
> https://wiki.postgresql.org/wiki/FOSDEM/PGDay_2016_Developer_Meeting
> Brussels Developer Meeting], but others are surely allowed to work on it as
> well)
> ** Made required by 7117685461af50f50c03f43e6a622284c8d54694 since the
> current documentation is now incorrect
>
> Unless Bruce endorsed this development strategy, I think it unfair for
> commit
> 7117685 to impose a deadline on his backup.sgml project. Did commit
> 7117685
>

I agree that's a horrible wording. What it meant to imply was a deadline
for *me* to help take that off Bruce's shoulders before then while also
opening the doors for others to work on it should they want. Re-reading it
now I can see that's not at all what it says. I'll reword (or rather,
remove most of that, since it's been discussed separately and doesn't
actually need to go on the open items list which is a list and not a
discussion)

(And yes, I chatted with Bruce about doing that weeks ago, so he knows well
about it - just that's not what the entry says).

> indeed make the documentation "incorrect?" Coverage in the Backup and
> Restore
> chapter would be a good thing, but I don't think that gap alone makes
> 7117685,
> with its reference-only documentation, incorrect. Did 7117685 impair
> documentation in any other respect?

Probably incomplete is a better word there as well.

> Incidentally, I'm not clear on the extent of Bruce's plans to change backup
> documentation. Relevant meeting note fragment:
>
> Magnus: We need a new robust API fornon-exclusive backups
> Simon: Keep but deprecate the existing API.
> Need to find a better way to ensure users have the required xlog in
> backups
> Craig: Our docs are in the wrong order. pg_basebackup should be first,
> ahead of manual methods.
> Action point: Re-arrange backup docs page (Bruce)
>
> The chapter already does describe pg_basebackup before describing
> pg_start_backup; what else did the plan entail?
>
>
Recommending people to primarily use tried and tested ways of doing backups
(including a reference to a list, probably on the wiki, of known external
tools that "do things the right way", such as backrest or barman) rather
than focusing on examples that aren't necessarily even correct, and
certainly not complete.

Mentioning the actual problems of exclusive base backups. (And obviously
talk about how using pg_start_backup/pg_stop_backup now makes it possible
to do "low level" backups without the risks of exclusive backups -- which
is the "incomplete" part from my note.

More clearly outlining backup vs dump, and possibly (I can't actually
remember if we decided the second step) put base backups before pg_dump
since the topic is backups.

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/