Reorder basebackup options, to list pg_basebackup first

Since this is the easy way of doing it, it should be listed first. All
the old information is retained for those who want the more advanced way.

Also adds a subheading for compressing logs, that seems to have been missing

Author: mhagander

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 &mdash; 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 &mdash; 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: