Subject: [PATCH] Clarify semantics of restore_command exit status

From: Andreas Seltenreich <[email-masked]>
Date: Wed, 23 Mar 2016 18:04:43 +0100

Hi,

the documentation is not clear about which of the non-zero exit codes of
a restore_command are considered FATAL and which are considered a
temporary failure.  I had to look at the source to find the answer.
Proposed fix below.

regards,
Andreas

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 9092cf8..6fa7d40 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -1114,9 +1114,9 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
     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.
+    part of a database server shutdown) or an exit status greater than 125
+    (such as command not found by the shell), then recovery will abort and the
+    server will not start up.
    </para>
 
    <para>
diff --git a/doc/src/sgml/recovery-config.sgml b/doc/src/sgml/recovery-config.sgml
index 26af221..66d5e62 100644
--- a/doc/src/sgml/recovery-config.sgml
+++ b/doc/src/sgml/recovery-config.sgml
@@ -73,8 +73,9 @@ 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.
+        database server shutdown) or an exit status greater than 125 (such as
+        command not found by the shell), then recovery will abort and the
+        server will not start up.
        </para>
       </listitem>
      </varlistentry>

-- 
Sent via pgsql-docs mailing list ([email-masked])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

---

From: Peter Eisentraut <[email-masked]>
Date: Fri, 15 Apr 2016 21:12:22 -0400

> temporary failure.  I had to look at the source to find the answer.

I think this goes a bit too much into implementation details.  As long
as the shell command sticks to the normal exit code range and uses
signals properly, it all works.  If we do feel we need to go into more
detail, does this only apply to restore_command, or also to other places
where we call shell commands?