doc: Refine documentation about recovery command exist status

petere · petere · commit 95e3d50539af · 2013-12-02T22:31:41.000-05:00
Add more documentation about how different exit codes and signals are
handled in each case.

Reviewed-by: Peter Geoghegan &lt;pg@heroku.com&gt;
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
@@ -1084,9 +1084,17 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
 
    <para>
     It is important that the command return nonzero exit status on failure.
-    The command <emphasis>will</> be called requesting files that are not present
-    in the archive; it must return nonzero when so asked.  This is not an
-    error condition.  Not all of the requested files will be WAL segment
+    The command <emphasis>will</> be called requesting files that are not
+    present in the archive; it must return nonzero when so asked.  This is not
+    an error condition.  An exception is that if the command was terminated by
+    a signal (other than <systemitem>SIGTERM</systemitem>, which is used as
+    part of a database server shutdown) or an error by the shell (such as
+    command not found), then recovery will abort and the server will not start
+    up.
+   </para>
+
+   <para>
+    Not all of the requested files will be WAL segment
     files; you should also expect requests for files with a suffix of
     <literal>.backup</> or <literal>.history</>. Also be aware that
     the base name of the <literal>%p</> path will be different from
diff --git a/doc/src/sgml/recovery-config.sgml b/doc/src/sgml/recovery-config.sgml
@@ -70,6 +70,10 @@
 restore_command = 'cp /mnt/server/archivedir/%f "%p"'
 restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
 </programlisting>
+        An exception is that if the command was terminated by a signal (other
+        than <systemitem>SIGTERM</systemitem>, which is used as part of a
+        database server shutdown) or an error by the shell (such as command
+        not found), then recovery will abort and the server will not start up.
        </para>
       </listitem>
      </varlistentry>
@@ -106,8 +110,10 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
         command.
        </para>
        <para>
-        If the command returns a non-zero exit status then a WARNING log
-        message will be written.
+        If the command returns a nonzero exit status then a warning log
+        message will be written.  An exception is that if the command was
+        terminated by a signal or an error by the shell (such as command not
+        found), a fatal error will be raised.
        </para>
       </listitem>
      </varlistentry>
@@ -127,10 +133,11 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
         last valid restart point, like in <xref linkend="archive-cleanup-command">.
        </para>
        <para>
-        If the command returns a non-zero exit status then a WARNING log
+        If the command returns a nonzero exit status then a warning log
         message will be written and the database will proceed to start up
         anyway.  An exception is that if the command was terminated by a
-        signal, the database will not proceed with startup.
+        signal or an error by the shell (such as command not found), the
+        database will not proceed with startup.
        </para>
       </listitem>
      </varlistentry>
