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

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 0180df5ddb7408a38a780a07a671c14bf3f2bbb5..ea639e925e44c433e8fc20fb7538b2c9a202372b 100644 (file)
--- 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/
    Making a Base Backup
 
    
-    The procedure for making a base backup is relatively simple:
+    The easiest way to perform a base backup is to use the
+     tool. It can create
+    a base backup either as regular files or as a tar archive. If more
+    flexibility than  can provide is
+    required, you can also make a base backup using the low level API
+    (see ).
+   
+
+   
+    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 full_page_writes disabled, you might notice a drop
+    in performance while the backup runs since full_page_writes is
+    effectively forced on during backup mode.
+   
+
+   
+    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 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
+    0000000100001234000055CD the backup history file will be
+    named something like
+    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.
+   
+
+   
+    The backup history file is just a small text file. It contains the
+    label string you gave to , 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.
+   
+
+   
+    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.
+   
+  
+
+  
+   Making a Base Backup Using the Low Level API
+   
+    The procedure for making a base backup using the low level
+    APIs contains a few more steps than
+    the  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.
   
    
     
@@ -813,17 +878,6 @@ SELECT pg_stop_backup();
   
    
 
-   
-    You can also use the  tool to take
-    the backup, instead of manually copying the files. This tool will do
-    the equivalent of pg_start_backup(), copy and
-    pg_stop_backup() steps automatically, and transfers the
-    backup over a regular PostgreSQL connection
-    using the replication protocol, instead of requiring file system level
-    access. pg_basebackup does not interfere with file system level backups
-    taken using pg_start_backup()/pg_stop_backup().
-   
-
    
     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 to hide the related warning messages.
    
 
-   
-    It is not necessary to be concerned about the amount of time elapsed
-    between pg_start_backup and the start of the actual backup,
-    nor between the end of the backup and pg_stop_backup; a
-    few minutes' delay won't hurt anything.  (However, if you normally run the
-    server with full_page_writes disabled, you might notice a drop
-    in performance between pg_start_backup and
-    pg_stop_backup, since 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.
-   
-
    
     Be certain that your backup dump includes all of the files under
     the database cluster directory (e.g., /usr/local/pgsql/data).
@@ -878,46 +919,6 @@ SELECT pg_stop_backup();
     (These files can confuse pg_ctl.)
    
 
-   
-    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 pg_stop_backup function
-    creates a 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
-    0000000100001234000055CD the backup history file will be
-    named something like
-    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.
-   
-
-   
-    The backup history file is just a small text file. It contains the
-    label string you gave to 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.
-   
-
-   
-    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.
-   
-
    
     It's also worth noting that the pg_start_backup function
     makes a file named backup_label in the database cluster
@@ -1214,7 +1215,18 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
      
 
      
-      To prepare for standalone hot backups, set wal_level to
+      As with base backups, the easiest way to produce a standalone
+      hot backup is to use the 
+      tool. If you include the -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.
+     
+
+     
+      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 wal_level to
       archive (or hot_standby), archive_mode to
       on, and set up an archive_command that performs
       archiving only when a 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.
      
 
+    
+
+    
+     Compressed Archive Logs
+
      
       If archive storage size is a concern, you can use
       gzip to compress the archive files: