Re: Update low-level backup documentation to match actual behavior

Hi Michael,

Thanks for reviewing! Sorry for the late response, those eclipses don't
just chase themselves...

On 8/20/17 10:22 PM, Michael Paquier wrote:
> On Fri, Aug 18, 2017 at 3:35 AM, David Steele <david(at)pgmasters(dot)net> wrote:
>
> + Prior to PostgreSQL 9.6, this
> Markup <productname>?

Fixed.

> + Note well that if the server crashes during the backup it may not be
> + possible to restart until the <literal>backup_label</> file has been
> + manually deleted from the PGDATA directory.
> Missing a markup <envvar> here for PGDATA.

Fixed.

> s/Note well/Note as well/, no?

This was a literal translation of nota bene but I've changed it to
simply "Note" as that seems common in the docs.

> - This function, when called on a primary, terminates the backup mode and
> + This function terminates backup mode and
> performs an automatic switch to the next WAL segment. The reason for the
> switch is to arrange for the last WAL segment written during the backup
> - interval to be ready to archive. When called on a standby, this function
> - only terminates backup mode. A subsequent WAL segment switch will be
> - needed in order to ensure that all WAL files needed to restore the backup
> - can be archived; if the primary does not have sufficient write activity
> - to trigger one, <function>pg_switch_wal</function> should be executed on
> - the primary.
> + interval to be ready to archive.
> pg_stop_backup() still waits for the last WAL segment to be archived
> on the primary. Perhaps we'd want to mention that?

That's detailed in the next paragraph, ISTM.

> Documentation does not state yet that the use of low-level APIs for
> exclusive backups are not supported on standbys.

The first paragraph of the exclusive section states, "this type of
backup can only be taken on a primary".

> Now in the docs:
> If the backup process monitors and ensures that all WAL segment files
> required for the backup are successfully archived then the second
> parameter (which defaults to true) can be set to false to have
> I would recommend adding some details here and mention
> "wait_for_archive" instead of "second parameter".

Done.

> I am wondering as
> well if this paragraph should be put in red with a warning or
> something like that. This is really, really important to ensure
> consistent backups!

Maybe, but this logic could easily apply to a lot of sections in the
backup docs. I'm not sure where it would end.

Thanks!
--
-David
david(at)pgmasters(dot)net