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@pgmasters.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@pgmasters.net