Clarify documentation on PITR and warm standby on the fact that the standby

restore_command should report failure on non-existent .backup and .history
files. Tidy up some related text along the way.

Patch by Markus Bertheau, with some editing by Simon Riggs and myself.

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 8131bcdf84530d52aa94a8a4300fe35da1707375..9f369f8e6d128a2b35475ce36f30546de656531a 100644 (file)
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  Backup and Restore
@@ -577,11 +577,10 @@ cp -i pg_xlog/00000001000000A900000065 /mnt/server/archivedir/00000001000000A900
    
     It is important that the archive command return zero exit status if and
     only if it succeeded.  Upon getting a zero result,
-    PostgreSQL will assume that the WAL segment file has been
-    successfully archived, and will remove or recycle it.
-    However, a nonzero status tells
-    PostgreSQL that the file was not archived; it will try
-    again periodically until it succeeds.
+    PostgreSQL will assume that the file has been
+    successfully archived, and will remove or recycle it.  However, a nonzero
+    status tells PostgreSQL that the file was not archived;
+    it will try again periodically until it succeeds.
    
 
    
@@ -1001,11 +1000,13 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
 
    
     It is important that the command return nonzero exit status on failure.
-    The command will be asked for log files that are not present
+    The command will be asked for files that are not present
     in the archive; it must return nonzero when so asked.  This is not an
-    error condition.  Be aware also that the base name of the %p
-    path will be different from %f; do not expect them to be
-    interchangeable.
+    error condition.  Not all of the requested files will be WAL segment
+    files; you should also expect requests for files with a suffix of
+    .backup or .history. Also be aware that
+    the base name of the %p path will be different from
+    %f; do not expect them to be interchangeable.
    
 
    
@@ -1576,19 +1577,21 @@ archive_command = 'local_backup_script.sh'
 
    
     The magic that makes the two loosely coupled servers work together is
-    simply a restore_command used on the standby that waits
-    for the next WAL file to become available from the primary. The
-    restore_command is specified in the
+    simply a restore_command used on the standby that,
+    when asked for the next WAL file, waits for it to become available from
+    the primary. The restore_command is specified in the
     recovery.conf file on the standby server. Normal recovery
     processing would request a file from the WAL archive, reporting failure
     if the file was unavailable.  For standby processing it is normal for
-    the next file to be unavailable, so we must be patient and wait for
-    it to appear. A waiting restore_command can be written as
-    a custom script that loops after polling for the existence of the next
-    WAL file. There must also be some way to trigger failover, which should
-    interrupt the restore_command, break the loop and return
-    a file-not-found error to the standby server. This ends recovery and
-    the standby will then come up as a normal server.
+    the next WAL file to be unavailable, so we must be patient and wait for
+    it to appear. For files ending in .backup or
+    .history there is no need to wait, and a non-zero return
+    code must be returned. A waiting restore_command can be
+    written as a custom script that loops after polling for the existence of
+    the next WAL file. There must also be some way to trigger failover, which
+    should interrupt the restore_command, break the loop and
+    return a file-not-found error to the standby server. This ends recovery
+    and the standby will then come up as a normal server.
    
 
    
@@ -1608,9 +1611,10 @@ if (!triggered)
 
    
     A working example of a waiting restore_command is provided
-    as a contrib module named pg_standby. This
-    example can be extended as needed to support specific configurations or
-    environments.
+    as a contrib module named pg_standby. It
+    should be used as a reference on how to correctly implement the logic
+    described above. It can also be extended as needed to support specific
+    configurations or environments.