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

Robert,

Thanks for reviewing!

On 8/18/17 2:45 PM, Robert Haas wrote:
> - the next WAL segment. The reason for the switch is to arrange for
> + the next WAL segment when run on a primary. On a standby you can call
> + <function>pg_switch_wal</function> on the primary to perform a manual
> + switch.
> + The reason for the switch is to arrange for
>
> Tacking on "when run on a primary" onto the end of the existing
> sentence is a little ambiguous: does that clause apply only to the
> last part, or to the whole sentence? I suggest something like: This
> terminates the backup mode. On a primary, it also performs an
> automatic switch to the next WAL segment. On a standby, it is not
> possible to automatically switch WAL segments, so you may wish to
> consider running <function>pg_switch_wal</function> on the primary to
> perform a manual switch.

Looks good.

>
> - <title>Making an exclusive low level backup</title>
> + <title>Making an exclusive low level backup on a primary</title>
>
> I'd omit this hunk.

OK, but I was trying to make it very clear that this backup method only
works on a primary. If you think the text is in the first paragraph is
enough then I'm willing to go with that, though.

> - more than one concurrent backup to run, and there can be some issues on
> + more than one concurrent backup to run, must be run on a
> primary, and there
> + can be some issues on
>
> Maybe this would be clearer: This type of backup can only be taken on
> a primary, does not allow more than one ...

Looks good.

> - This function, when called on a primary, terminates the backup mode and
> + This function terminates the 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.
>
> Why do you want to delete all that text? It seems like good text to me.

Since the exclusive method only works on a primary...

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