Add additional PITR documentation.

Simon Riggs

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 77004beea4e757322070f8773ee8dd3fd9d3508f..ab0ef35e08fd0cae0f6703e90cd44ec7fefa6934 100644 (file)
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  Backup and Restore
@@ -641,10 +641,22 @@ archive_command = 'test ! -f .../%f && cp %p .../%f'
    
     Also, you can force a segment switch manually with
     pg_switch_xlog, if you want to ensure that a
-    just-finished transaction is archived immediately.  Other utility
+    just-finished transaction is archived as soon as possible.  Other utility
     functions related to WAL management are listed in 
     linkend="functions-admin-backup-table">.
    
+
+   
+    When archive_mode is off some SQL commands
+    are optimized to avoid WAL logging, as described in 
+    linkend="populate-pitr">. If archiving were turned on during execution
+    of one of these statements, WAL would not contain enough information
+    for archive recovery.  (Crash recovery is unaffected.)  For
+    this reason, archive_mode can only be changed at server
+    start.  (archive_command can be changed with a
+    configuration file reload, and setting it to '' does
+    prevent archiving.)
+   
   
 
   
@@ -973,14 +985,24 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
    
     Normally, recovery will proceed through all available WAL segments,
     thereby restoring the database to the current point in time (or as
-    close as we can get given the available WAL segments).  But if you want
-    to recover to some previous point in time (say, right before the junior
-    DBA dropped your main transaction table), just specify the required
-    stopping point in recovery.conf.  You can specify the stop
-    point, known as the recovery target, either by date/time or
-    by completion of a specific transaction ID.  As of this writing only
-    the date/time option is very usable, since there are no tools to help
-    you identify with any accuracy which transaction ID to use.
+    close as we can get given the available WAL segments).  So a normal
+    recovery will end with a "file not found" message, the exact text
+    of the error message depending upon your choice of 
+    restore_command.  You may also see an error message
+    at the start of recovery for a file named something like
+    00000001.history.  This is also normal and does not
+    indicate a problem in simple recovery situations. See 
+     for discussion.
+   
+
+   
+    If you want to recover to some previous point in time (say, right before
+    the junior DBA dropped your main transaction table), just specify the 
+    required stopping point in recovery.conf.  You can specify 
+    the stop point, known as the recovery target, either by 
+    date/time or by completion of a specific transaction ID.  As of this 
+    writing only the date/time option is very usable, since there are no tools 
+    to help you identify with any accuracy which transaction ID to use.
    
 
    
@@ -1214,6 +1236,92 @@ restore_command = 'copy /mnt/server/archivedir/%f "%p"'  # Windows
    
   
 
+  
+   Tips and Examples
+
+   
+    Some examples of configuring Continuous Archiving are given here.
+   
+
+    
+     Recovery Settings
+
+     
+      It is possible to use the existing backup facilities to produce
+      standalone hot backups. These are backups that cannot be used for
+      point-in-time recovery, yet are much faster to backup and restore
+      than pg_dump.
+     
+
+     
+      To configure standalone backups you should use a switch file. If the
+      file exists then archives are made, otherwise archiving is ignored.
+
+archive_command = 'test -f /var/lib/pgsql/backup_in_progress && cp -i %p /var/lib/pgsql/archive/%f </dev/null'
+
+      Backup can then be taken using a script like the following:
+
+touch /var/lib/pgsql/backup_in_progress
+psql -c "select pg_start_backup('hot_backup');"
+tar -cvf /var/lib/pgsql/backup.tar /var/lib/pgsql/data/
+psql -c "select pg_stop_backup();"
+sleep 20
+rm /var/lib/pgsql/backup_in_progress
+tar -rvf /var/lib/pgsql/backup.tar /var/lib/pgsql/archive/
+
+      The switch file /var/lib/pgsql/backup_in_progress is
+      created first, allowing archiving to start prior to the backup.
+      After the backup the switch file is removed. Archived WAL files are
+      then added to the backup so that both base backup and all required
+      WAL files are part of the same tar file.
+     
+    
+
+    
+     <varname>archive_command</varname> scripts
+
+     
+      Many people choose to use scripts to define their 
+      archive_command, so that their
+      postgresql.conf looks very simple:
+
+archive_command = 'local_backup_script.sh'
+
+      This allows all complexity to be managed within the script, which
+      can be written in a popular scripting language such as
+      bash or perl.  Statements echoed to
+      stderr will appear in the database server log, allowing
+      complex configurations to be easily diagnosed if they fail.
+     
+     
+      Example of how scripts might be used include:
+      
+       
+        
+         Copying data to a secure off-site data storage provider
+        
+       
+       
+        
+         Batching WAL files so they are transferred every three hours, rather than
+         one at a time as they fill
+        
+       
+       
+        
+         Interfacing with other backup and recovery software
+        
+       
+       
+        
+         Interfacing with monitoring software to report errors directly
+        
+       
+      
+     
+    
+  
+
   
    Caveats
 
@@ -1435,7 +1543,7 @@ restore_command = 'copy /mnt/server/archivedir/%f "%p"'  # Windows
     Pseudocode for a suitable restore_command is:
 
 triggered = false;
-while (!NextWALFileReady() && !triggered)
+while (!NextWALFileReady() &amp;& !triggered)
 {
     sleep(100000L);         /* wait for ~0.1 sec */
     if (CheckForExternalTrigger())