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

- 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.

- backup files. If <varname>archive_mode</> is enabled,
+ backup files. On a primary, if <varname>archive_mode</> is
enabled and the
+ <literal>wait_for_archive</> parameter is <literal>true</>,
<function>pg_stop_backup</> does not return until the last segment has
been archived.
+ On a standby, <varname>archive_mode</> must be <literal>always</> in order
+ for <function>pg_stop_backup</> to wait.

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.

- 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 ...

- 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.

- The function also creates a backup history file in the write-ahead log
+ When executed on a primary, the function also creates a backup history file
+ in the write-ahead log

Looks good.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company