Return codes for archive and restore commands

From: PG Doc comments form <noreply(at)postgresql(dot)org>
To: pgsql-docs(at)lists(dot)postgresql(dot)org
Cc: splarv(at)ya(dot)ru
Subject: Return codes for archive and restore commands
Date: 2018-11-28 11:00:31
Message-ID: 154340283171.1324.10549444217937216132@wrigleys.postgresql.org
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/11/archive-recovery-settings.html
Description:

For instance for the restore command in the documentation said:

It is important for the command to return a zero exit status only if it
succeeds. The command will be asked for file names that are not present in
the archive; it must return nonzero when so asked. Examples:
...
An exception is that if the command was terminated by a signal (other than
SIGTERM, 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.
end cite

This is not correct. I think that how the behavior of PostgreSQL depends on
return codes of restore and archive commands must be more exactly explained,
this is important for those how write scripts and applications for this
commands. For instance, if the aws command line interface (awscli) used as
restore command, aws on some commands return 255 code (for instance in case
of network fault) and this leads to unexpected result with PostgreSQL.

For the archive command:
<=128 There are not errors in the PostgreSQL log (messages with severity
equal or higher than ERROR). Firstly 3 messages of type LOG about fault,
then WARNING about this and pause for 1 minute, then repeated.
>=129 FATAL error in the PostgeSQL log. The message about stoping an archive
process, but not the database. Repeated after roughly 16 seconds.

For restore command:
<=125 There are not errors in the PostgreSQL log, repeated after several
seconds. Good to return network failure or in case of absent file.
>=126 FATAL error in the PostgreSQL log, stop a startup process, shutdown
the database. Good for a fatal error, for instance misconfiguration.

In this case PostgreSQL tries confirm rules for return codes of a unix
shell. A unix shell return 126 in the case of "command not executable", 127
in the case "command not found", 128+# of signal in the case if application
interrupted by uncatched signal.

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Jürgen Purtz 2018-11-28 17:34:26 Re: First SVG graphic
Previous Message Bruce Momjian 2018-11-27 01:54:43 Re: Section 26.2.1. Planning wording