linkend="guc-archive-library"/> configuration parameter. In practice
these settings will always be placed in the
postgresql.conf file.
- One simple way to archive is to set archive_library to
- an empty string and to specify a shell command in
- .
+
+
In archive_command,
%p is replaced by the path name of the file to
archive, while %f is replaced by only the file name.
- Another way to archive is to use a custom archive module as the
- archive_library. Since such modules are written in
- C, creating your own may require considerably more effort
- than writing a shell command. However, archive modules can be more
- performant than archiving via shell, and they will have access to many
- useful server resources. For more information about archive modules, see
- .
-
-
- The archive library will be executed under the ownership of the same
+ The archive command will be executed under the ownership of the same
user that the
PostgreSQL server is running as. Since
the series of WAL files being archived contains effectively everything
in your database, you will want to be sure that the archived data is
- It is important that the archive function return true if
- and only if it succeeds. If true is returned,
+ It is important that the archive command return zero exit status if and
+ only if it succeeds. Upon getting a zero result,
PostgreSQL will assume that the file has been
- successfully archived, and will remove or recycle it. However, a return
- value of false tells
-
PostgreSQL that the file was not archived; it
- will try again periodically until it succeeds. If you are archiving via a
- shell command, the appropriate return values can be achieved by returning
- 0 if the command succeeds and a nonzero value if it
- fails.
+ 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.
+
+
+ Another way to archive is to use a custom archive module as the
+ archive_library. Since such modules are written in
+ C, creating your own may require considerably more effort
+ than writing a shell command. However, archive modules can be more
+ performant than archiving via shell, and they will have access to many
+ useful server resources. For more information about archive modules, see
+ .
- If the archive function emits an ERROR or
- FATAL, the archiver process aborts and gets restarted by
- the postmaster. If you are archiving via shell command,
- FATAL is emitted if the command is terminated by a signal
- (other than SIGTERM
- that is used as part of a server shutdown)
- or an error by the shell with an exit status greater than 125 (such as
- command not found). In such cases, the failure is not reported in
- .
+ When the archive command is terminated by a signal (other than
+ SIGTERM that is used as part of a server
+ shutdown) or an error by the shell with an exit status greater than
+ 125 (such as command not found), or if the archive function emits an
+ ERROR or FATAL, the archiver process
+ aborts and gets restarted by the postmaster. In such cases, the failure is
+ not reported in .
- The archive library should generally be designed to refuse to overwrite
+ Archive commands and libraries should generally be designed to refuse to overwrite
any pre-existing archive file. This is an important safety feature to
preserve the integrity of your archive in case of administrator error
(such as sending the output of two different servers to the same archive
re-archive a WAL file that was previously archived. For example, if the
system crashes before the server makes a durable record of archival
success, the server will attempt to archive the file again after
- restarting (provided archiving is still enabled). When an archive library
- encounters a pre-existing file, it should return true
+ restarting (provided archiving is still enabled). When an archive command or library
+ encounters a pre-existing file, it should return a zero status or true, respectively,
if the WAL file has identical contents to the pre-existing archive and the
pre-existing archive is fully persisted to storage. If a pre-existing
file contains different contents than the WAL file being archived, the
- archive library must return
- false.
+ archive command or library must return a nonzero status or
+ false, respectively.
While designing your archiving setup, consider what will happen if
- the archive library fails repeatedly because some aspect requires
+ the archive command or library fails repeatedly because some aspect requires
operator intervention or the archive runs out of space. For example, this
could occur if you write to tape without an autochanger; when the tape
fills, nothing further can be archived until the tape is swapped.
- The speed of the archive library is unimportant as long as it can keep up
+ The speed of the archive command or library is unimportant as long as it can keep up
with the average rate at which your server generates WAL data. Normal
operation continues even if the archiving process falls a little behind.
If archiving falls significantly behind, this will increase the amount of
- In writing your archive library, you should assume that the file names to
+ In writing your archive command or library, you should assume that the file names to
be archived can be up to 64 characters long and can contain any
combination of ASCII letters, digits, and dots. It is not necessary to
- preserve the original relative path but it is necessary to preserve the file
- name.
+ preserve the original relative path (%p) but it is necessary to
+ preserve the file name (%f).
- The archive function is only invoked on completed WAL segments. Hence,
+ The archive command or function is only invoked on completed WAL segments. Hence,
if your server generates only little WAL traffic (or has slack periods
where it does so), there could be a long delay between the completion
of a transaction and its safe recording in archive storage. To put
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, wal_level can only be changed at
- server start. However, archive_library can be changed with a
+ server start. However, archive_command and archive_library can be changed with a
configuration file reload. If you are archiving via shell and wish to
temporarily stop archiving,
one way to do it is to set archive_command to the empty
On a standby, archive_mode must be always in order
for pg_backup_stop to wait.
Archiving of these files happens automatically since you have
- already configured archive_library or
+ already configured archive_command or archive_library or
archive_command.
In most cases this happens quickly, but you are advised to monitor your
archive system to ensure there are no delays.
If the archive process has fallen behind because of failures of the
- archive library or archive command, it will keep retrying
+ archive command or library, it will keep retrying
until the archive succeeds and the backup is complete.
If you wish to place a time limit on the execution of
pg_backup_stop, set an appropriate
projects / postgresql.git / commitdiff