diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 0180df5ddb7408a38a780a07a671c14bf3f2bbb5..ea639e925e44c433e8fc20fb7538b2c9a202372b 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -724,7 +724,72 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_xlog/
<title>Making a Base Backup</title>
<para>
- The procedure for making a base backup is relatively simple:
+ The easiest way to perform a base backup is to use the
+ <xref linkend="app-pgbasebackup"> tool. It can create
+ a base backup either as regular files or as a tar archive. If more
+ flexibility than <xref linkend="app-pgbasebackup"> can provide is
+ required, you can also make a base backup using the low level API
+ (see <xref linkend="backup-lowlevel-base-backup">).
+ </para>
+
+ <para>
+ It is not necessary to be concerned about the amount of time it takes
+ to make a base backup. However, if you normally run the
+ server with <varname>full_page_writes</> disabled, you might notice a drop
+ in performance while the backup runs since <varname>full_page_writes</> is
+ effectively forced on during backup mode.
+ </para>
+
+ <para>
+ To make use of the backup, you will need to keep all the WAL
+ segment files generated during and after the file system backup.
+ To aid you in doing this, the base backup process
+ creates a <firstterm>backup history file</> that is immediately
+ stored into the WAL archive area. This file is named after the first
+ WAL segment file that you need for the file system backup.
+ For example, if the starting WAL file is
+ <literal>0000000100001234000055CD</> the backup history file will be
+ named something like
+ <literal>0000000100001234000055CD.007C9330.backup</>. (The second
+ part of the file name stands for an exact position within the WAL
+ file, and can ordinarily be ignored.) Once you have safely archived
+ the file system backup and the WAL segment files used during the
+ backup (as specified in the backup history file), all archived WAL
+ segments with names numerically less are no longer needed to recover
+ the file system backup and can be deleted. However, you should
+ consider keeping several backup sets to be absolutely certain that
+ you can recover your data.
+ </para>
+
+ <para>
+ The backup history file is just a small text file. It contains the
+ label string you gave to <xref linkend="app-pgbasebackup">, as well as
+ the starting and ending times and WAL segments of the backup.
+ If you used the label to identify the associated dump file,
+ then the archived history file is enough to tell you which dump file to
+ restore.
+ </para>
+
+ <para>
+ Since you have to keep around all the archived WAL files back to your
+ last base backup, the interval between base backups should usually be
+ chosen based on how much storage you want to expend on archived WAL
+ files. You should also consider how long you are prepared to spend
+ recovering, if recovery should be necessary — the system will have to
+ replay all those WAL segments, and that could take awhile if it has
+ been a long time since the last base backup.
+ </para>
+ </sect2>
+
+ <sect2 id="backup-lowlevel-base-backup">
+ <title>Making a Base Backup Using the Low Level API</title>
+ <para>
+ The procedure for making a base backup using the low level
+ APIs contains a few more steps than
+ the <xref linkend="app-pgbasebackup"> method, but is relatively
+ simple. It is very important that these steps are executed in
+ sequence, and that the success of a step is verified before
+ proceeding to the next step.
<orderedlist>
<listitem>
<para>
@@ -813,17 +878,6 @@ SELECT pg_stop_backup();
</orderedlist>
</para>
- <para>
- You can also use the <xref linkend="app-pgbasebackup"> tool to take
- the backup, instead of manually copying the files. This tool will do
- the equivalent of <function>pg_start_backup()</>, copy and
- <function>pg_stop_backup()</> steps automatically, and transfers the
- backup over a regular <productname>PostgreSQL</productname> connection
- using the replication protocol, instead of requiring file system level
- access. <command>pg_basebackup</command> does not interfere with file system level backups
- taken using <function>pg_start_backup()</>/<function>pg_stop_backup()</>.
- </para>
-
<para>
Some file system backup tools emit warnings or errors
if the files they are trying to copy change while the copy proceeds.
@@ -842,19 +896,6 @@ SELECT pg_stop_backup();
--warning=no-file-removed</literal> to hide the related warning messages.
</para>
- <para>
- It is not necessary to be concerned about the amount of time elapsed
- between <function>pg_start_backup</> and the start of the actual backup,
- nor between the end of the backup and <function>pg_stop_backup</>; a
- few minutes' delay won't hurt anything. (However, if you normally run the
- server with <varname>full_page_writes</> disabled, you might notice a drop
- in performance between <function>pg_start_backup</> and
- <function>pg_stop_backup</>, since <varname>full_page_writes</> is
- effectively forced on during backup mode.) You must ensure that these
- steps are carried out in sequence, without any possible
- overlap, or you will invalidate the backup.
- </para>
-
<para>
Be certain that your backup dump includes all of the files under
the database cluster directory (e.g., <filename>/usr/local/pgsql/data</>).
@@ -878,46 +919,6 @@ SELECT pg_stop_backup();
(These files can confuse <application>pg_ctl</>.)
</para>
- <para>
- To make use of the backup, you will need to keep all the WAL
- segment files generated during and after the file system backup.
- To aid you in doing this, the <function>pg_stop_backup</> function
- creates a <firstterm>backup history file</> that is immediately
- stored into the WAL archive area. This file is named after the first
- WAL segment file that you need for the file system backup.
- For example, if the starting WAL file is
- <literal>0000000100001234000055CD</> the backup history file will be
- named something like
- <literal>0000000100001234000055CD.007C9330.backup</>. (The second
- part of the file name stands for an exact position within the WAL
- file, and can ordinarily be ignored.) Once you have safely archived
- the file system backup and the WAL segment files used during the
- backup (as specified in the backup history file), all archived WAL
- segments with names numerically less are no longer needed to recover
- the file system backup and can be deleted. However, you should
- consider keeping several backup sets to be absolutely certain that
- you can recover your data.
- </para>
-
- <para>
- The backup history file is just a small text file. It contains the
- label string you gave to <function>pg_start_backup</>, as well as
- the starting and ending times and WAL segments of the backup.
- If you used the label to identify the associated dump file,
- then the archived history file is enough to tell you which dump file to
- restore.
- </para>
-
- <para>
- Since you have to keep around all the archived WAL files back to your
- last base backup, the interval between base backups should usually be
- chosen based on how much storage you want to expend on archived WAL
- files. You should also consider how long you are prepared to spend
- recovering, if recovery should be necessary — the system will have to
- replay all those WAL segments, and that could take awhile if it has
- been a long time since the last base backup.
- </para>
-
<para>
It's also worth noting that the <function>pg_start_backup</> function
makes a file named <filename>backup_label</> in the database cluster
@@ -1214,7 +1215,18 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
</para>
<para>
- To prepare for standalone hot backups, set <varname>wal_level</> to
+ As with base backups, the easiest way to produce a standalone
+ hot backup is to use the <xref linkend="app-pgbasebackup">
+ tool. If you include the <literal>-X</> parameter when calling
+ it, all the transaction log required to use the backup will be
+ included in the backup automatically, and no special action is
+ required to restore the backup.
+ </para>
+
+ <para>
+ If more flexibility in copying the backup files is needed, a lower
+ level process can be used for standalone hot backups as well.
+ To prepare for low level standalone hot backups, set <varname>wal_level</> to
<literal>archive</> (or <literal>hot_standby</>), <varname>archive_mode</> to
<literal>on</>, and set up an <varname>archive_command</> that performs
archiving only when a <emphasis>switch file</> exists. For example:
@@ -1246,6 +1258,11 @@ tar -rf /var/lib/pgsql/backup.tar /var/lib/pgsql/archive/
Please remember to add error handling to your backup scripts.
</para>
+ </sect3>
+
+ <sect3 id="compressed-archive-logs">
+ <title>Compressed Archive Logs</title>
+
<para>
If archive storage size is a concern, you can use
<application>gzip</application> to compress the archive files: