mirror of
https://github.com/postgres/postgres.git
synced 2025-06-11 20:28:21 +03:00
Allow archiving via loadable modules.
Running a shell command for each file to be archived has a lot of overhead and may not offer as much error checking as you want, or the exact semantics that you want. So, offer the option to call a loadable module for each file to be archived, rather than running a shell command. Also, add a 'basic_archive' contrib module as an example implementation that archives to a local directory. Nathan Bossart, with a little bit of kibitzing by me. Discussion: http://postgr.es/m/20220202224433.GA1036711@nathanxps13
This commit is contained in:
Robert Haas
136
doc/src/sgml/archive-modules.sgml
Normal file
136
doc/src/sgml/archive-modules.sgml
Normal file
@ -0,0 +1,136 @@
|
||||
<!-- doc/src/sgml/archive-modules.sgml -->
|
||||
|
||||
<chapter id="archive-modules">
|
||||
<title>Archive Modules</title>
|
||||
<indexterm zone="archive-modules">
|
||||
<primary>Archive Modules</primary>
|
||||
</indexterm>
|
||||
|
||||
<para>
|
||||
PostgreSQL provides infrastructure to create custom modules for continuous
|
||||
archiving (see <xref linkend="continuous-archiving"/>). While archiving via
|
||||
a shell command (i.e., <xref linkend="guc-archive-command"/>) is much
|
||||
simpler, a custom archive module will often be considerably more robust and
|
||||
performant.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When a custom <xref linkend="guc-archive-library"/> is configured, PostgreSQL
|
||||
will submit completed WAL files to the module, and the server will avoid
|
||||
recyling or removing these WAL files until the module indicates that the files
|
||||
were successfully archived. It is ultimately up to the module to decide what
|
||||
to do with each WAL file, but many recommendations are listed at
|
||||
<xref linkend="backup-archiving-wal"/>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Archiving modules must at least consist of an initialization function (see
|
||||
<xref linkend="archive-module-init"/>) and the required callbacks (see
|
||||
<xref linkend="archive-module-callbacks"/>). However, archive modules are
|
||||
also permitted to do much more (e.g., declare GUCs and register background
|
||||
workers).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <filename>contrib/basic_archive</filename> module contains a working
|
||||
example, which demonstrates some useful techniques.
|
||||
</para>
|
||||
|
||||
<sect1 id="archive-module-init">
|
||||
<title>Initialization Functions</title>
|
||||
<indexterm zone="archive-module-init">
|
||||
<primary>_PG_archive_module_init</primary>
|
||||
</indexterm>
|
||||
<para>
|
||||
An archive library is loaded by dynamically loading a shared library with the
|
||||
<xref linkend="guc-archive-library"/>'s name as the library base name. The
|
||||
normal library search path is used to locate the library. To provide the
|
||||
required archive module callbacks and to indicate that the library is
|
||||
actually an archive module, it needs to provide a function named
|
||||
<function>_PG_archive_module_init</function>. This function is passed a
|
||||
struct that needs to be filled with the callback function pointers for
|
||||
individual actions.
|
||||
|
||||
<programlisting>
|
||||
typedef struct ArchiveModuleCallbacks
|
||||
{
|
||||
ArchiveCheckConfiguredCB check_configured_cb;
|
||||
ArchiveFileCB archive_file_cb;
|
||||
ArchiveShutdownCB shutdown_cb;
|
||||
} ArchiveModuleCallbacks;
|
||||
typedef void (*ArchiveModuleInit) (struct ArchiveModuleCallbacks *cb);
|
||||
</programlisting>
|
||||
|
||||
Only the <function>archive_file_cb</function> callback is required. The
|
||||
others are optional.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="archive-module-callbacks">
|
||||
<title>Archive Module Callbacks</title>
|
||||
<para>
|
||||
The archive callbacks define the actual archiving behavior of the module.
|
||||
The server will call them as required to process each individual WAL file.
|
||||
</para>
|
||||
|
||||
<sect2 id="archive-module-check">
|
||||
<title>Check Callback</title>
|
||||
<para>
|
||||
The <function>check_configured_cb</function> callback is called to determine
|
||||
whether the module is fully configured and ready to accept WAL files (e.g.,
|
||||
its configuration parameters are set to valid values). If no
|
||||
<function>check_configured_cb</function> is defined, the server always
|
||||
assumes the module is configured.
|
||||
|
||||
<programlisting>
|
||||
typedef bool (*ArchiveCheckConfiguredCB) (void);
|
||||
</programlisting>
|
||||
|
||||
If <literal>true</literal> is returned, the server will proceed with
|
||||
archiving the file by calling the <function>archive_file_cb</function>
|
||||
callback. If <literal>false</literal> is returned, archiving will not
|
||||
proceed, and the archiver will emit the following message to the server log:
|
||||
<screen>
|
||||
WARNING: archive_mode enabled, yet archiving is not configured
|
||||
</screen>
|
||||
In the latter case, the server will periodically call this function, and
|
||||
archiving will proceed only when it returns <literal>true</literal>.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="archive-module-archive">
|
||||
<title>Archive Callback</title>
|
||||
<para>
|
||||
The <function>archive_file_cb</function> callback is called to archive a
|
||||
single WAL file.
|
||||
|
||||
<programlisting>
|
||||
typedef bool (*ArchiveFileCB) (const char *file, const char *path);
|
||||
</programlisting>
|
||||
|
||||
If <literal>true</literal> is returned, the server proceeds as if the file
|
||||
was successfully archived, which may include recycling or removing the
|
||||
original WAL file. If <literal>false</literal> is returned, the server will
|
||||
keep the original WAL file and retry archiving later.
|
||||
<literal>file</literal> will contain just the file name of the WAL file to
|
||||
archive, while <literal>path</literal> contains the full path of the WAL
|
||||
file (including the file name).
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="archive-module-shutdown">
|
||||
<title>Shutdown Callback</title>
|
||||
<para>
|
||||
The <function>shutdown_cb</function> callback is called when the archiver
|
||||
process exits (e.g., after an error) or the value of
|
||||
<xref linkend="guc-archive-library"/> changes. If no
|
||||
<function>shutdown_cb</function> is defined, no special action is taken in
|
||||
these situations.
|
||||
|
||||
<programlisting>
|
||||
typedef void (*ArchiveShutdownCB) (void);
|
||||
</programlisting>
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
</chapter>
|
||||
@ -593,20 +593,23 @@ tar -cf backup.tar /usr/local/pgsql/data
|
||||
provide the database administrator with flexibility,
|
||||
<productname>PostgreSQL</productname> tries not to make any assumptions about how
|
||||
the archiving will be done. Instead, <productname>PostgreSQL</productname> lets
|
||||
the administrator specify a shell command to be executed to copy a
|
||||
completed segment file to wherever it needs to go. The command could be
|
||||
as simple as a <literal>cp</literal>, or it could invoke a complex shell
|
||||
script — it's all up to you.
|
||||
the administrator specify an archive library to be executed to copy a
|
||||
completed segment file to wherever it needs to go. This could be as simple
|
||||
as a shell command that uses <literal>cp</literal>, or it could invoke a
|
||||
complex C function — it's all up to you.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To enable WAL archiving, set the <xref linkend="guc-wal-level"/>
|
||||
configuration parameter to <literal>replica</literal> or higher,
|
||||
<xref linkend="guc-archive-mode"/> to <literal>on</literal>,
|
||||
and specify the shell command to use in the <xref
|
||||
linkend="guc-archive-command"/> configuration parameter. In practice
|
||||
and specify the library to use in the <xref
|
||||
linkend="guc-archive-library"/> configuration parameter. In practice
|
||||
these settings will always be placed in the
|
||||
<filename>postgresql.conf</filename> file.
|
||||
One simple way to archive is to set <varname>archive_library</varname> to
|
||||
an empty string and to specify a shell command in
|
||||
<xref linkend="guc-archive-command"/>.
|
||||
In <varname>archive_command</varname>,
|
||||
<literal>%p</literal> is replaced by the path name of the file to
|
||||
archive, while <literal>%f</literal> is replaced by only the file name.
|
||||
@ -631,7 +634,17 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The archive command will be executed under the ownership of the same
|
||||
Another way to archive is to use a custom archive module as the
|
||||
<varname>archive_library</varname>. Since such modules are written in
|
||||
<literal>C</literal>, 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
|
||||
<xref linkend="archive-modules"/>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The archive library will be executed under the ownership of the same
|
||||
user that the <productname>PostgreSQL</productname> 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
|
||||
@ -640,25 +653,31 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0
|
||||
</para>
|
||||
|
||||
<para>
|
||||
It is important that the archive command return zero exit status if and
|
||||
only if it succeeds. Upon getting a zero result,
|
||||
It is important that the archive function return <literal>true</literal> if
|
||||
and only if it succeeds. If <literal>true</literal> is returned,
|
||||
<productname>PostgreSQL</productname> will assume that the file has been
|
||||
successfully archived, and will remove or recycle it. However, a nonzero
|
||||
status tells <productname>PostgreSQL</productname> that the file was not archived;
|
||||
it will try again periodically until it succeeds.
|
||||
successfully archived, and will remove or recycle it. However, a return
|
||||
value of <literal>false</literal> tells
|
||||
<productname>PostgreSQL</productname> 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
|
||||
<literal>0</literal> if the command succeeds and a nonzero value if it
|
||||
fails.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When the archive command is terminated by a signal (other than
|
||||
<systemitem>SIGTERM</systemitem> 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), the archiver process aborts and gets
|
||||
restarted by the postmaster. In such cases, the failure is
|
||||
not reported in <xref linkend="pg-stat-archiver-view"/>.
|
||||
If the archive function emits an <literal>ERROR</literal> or
|
||||
<literal>FATAL</literal>, 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
|
||||
<systemitem>SIGTERM</systemitem> 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
|
||||
<xref linkend="pg-stat-archiver-view"/>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The archive command should generally be designed to refuse to overwrite
|
||||
The archive library 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
|
||||
@ -666,9 +685,9 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0
|
||||
</para>
|
||||
|
||||
<para>
|
||||
It is advisable to test your proposed archive command to ensure that it
|
||||
It is advisable to test your proposed archive library to ensure that it
|
||||
indeed does not overwrite an existing file, <emphasis>and that it returns
|
||||
nonzero status in this case</emphasis>.
|
||||
<literal>false</literal> in this case</emphasis>.
|
||||
The example command above for Unix ensures this by including a separate
|
||||
<command>test</command> step. On some Unix platforms, <command>cp</command> has
|
||||
switches such as <option>-i</option> that can be used to do the same thing
|
||||
@ -680,7 +699,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0
|
||||
|
||||
<para>
|
||||
While designing your archiving setup, consider what will happen if
|
||||
the archive command fails repeatedly because some aspect requires
|
||||
the archive 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.
|
||||
@ -695,7 +714,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The speed of the archiving command is unimportant as long as it can keep up
|
||||
The speed of the archive 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
|
||||
@ -707,11 +726,11 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In writing your archive command, you should assume that the file names to
|
||||
In writing your archive 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 (<literal>%p</literal>) but it is necessary to
|
||||
preserve the file name (<literal>%f</literal>).
|
||||
preserve the original relative path but it is necessary to preserve the file
|
||||
name.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -728,7 +747,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The archive command is only invoked on completed WAL segments. Hence,
|
||||
The archive 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
|
||||
@ -757,8 +776,9 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0
|
||||
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, <varname>wal_level</varname> can only be changed at
|
||||
server start. However, <varname>archive_command</varname> can be changed with a
|
||||
configuration file reload. If you wish to temporarily stop archiving,
|
||||
server start. However, <varname>archive_library</varname> 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 <varname>archive_command</varname> to the empty
|
||||
string (<literal>''</literal>).
|
||||
This will cause WAL files to accumulate in <filename>pg_wal/</filename> until a
|
||||
@ -938,11 +958,11 @@ SELECT * FROM pg_stop_backup(false, true);
|
||||
On a standby, <varname>archive_mode</varname> must be <literal>always</literal> in order
|
||||
for <function>pg_stop_backup</function> to wait.
|
||||
Archiving of these files happens automatically since you have
|
||||
already configured <varname>archive_command</varname>. In most cases this
|
||||
already configured <varname>archive_library</varname>. 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 command, it will keep retrying
|
||||
because of failures of the archive 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
|
||||
<function>pg_stop_backup</function>, set an appropriate
|
||||
@ -1500,9 +1520,10 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
|
||||
To prepare for low level standalone hot backups, make sure
|
||||
<varname>wal_level</varname> is set to
|
||||
<literal>replica</literal> or higher, <varname>archive_mode</varname> to
|
||||
<literal>on</literal>, and set up an <varname>archive_command</varname> that performs
|
||||
<literal>on</literal>, and set up an <varname>archive_library</varname> that performs
|
||||
archiving only when a <emphasis>switch file</emphasis> exists. For example:
|
||||
<programlisting>
|
||||
archive_library = '' # use shell command
|
||||
archive_command = 'test ! -f /var/lib/pgsql/backup_in_progress || (test ! -f /var/lib/pgsql/archive/%f && cp %p /var/lib/pgsql/archive/%f)'
|
||||
</programlisting>
|
||||
This command will perform archiving when
|
||||
|
||||
81
doc/src/sgml/basic-archive.sgml
Normal file
81
doc/src/sgml/basic-archive.sgml
Normal file
@ -0,0 +1,81 @@
|
||||
<!-- doc/src/sgml/basic-archive.sgml -->
|
||||
|
||||
<sect1 id="basic-archive" xreflabel="basic_archive">
|
||||
<title>basic_archive</title>
|
||||
|
||||
<indexterm zone="basic-archive">
|
||||
<primary>basic_archive</primary>
|
||||
</indexterm>
|
||||
|
||||
<para>
|
||||
<filename>basic_archive</filename> is an example of an archive module. This
|
||||
module copies completed WAL segment files to the specified directory. This
|
||||
may not be especially useful, but it can serve as a starting point for
|
||||
developing your own archive module. For more information about archive
|
||||
modules, see <xref linkend="archive-modules"/>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In order to function, this module must be loaded via
|
||||
<xref linkend="guc-archive-library"/>, and <xref linkend="guc-archive-mode"/>
|
||||
must be enabled.
|
||||
</para>
|
||||
|
||||
<sect2>
|
||||
<title>Configuration Parameters</title>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<varname>basic_archive.archive_directory</varname> (<type>string</type>)
|
||||
<indexterm>
|
||||
<primary><varname>basic_archive.archive_directory</varname> configuration parameter</primary>
|
||||
</indexterm>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The directory where the server should copy WAL segment files. This
|
||||
directory must already exist. The default is an empty string, which
|
||||
effectively halts WAL archiving, but if <xref linkend="guc-archive-mode"/>
|
||||
is enabled, the server will accumulate WAL segment files in the
|
||||
expectation that a value will soon be provided.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>
|
||||
These parameters must be set in <filename>postgresql.conf</filename>.
|
||||
Typical usage might be:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
# postgresql.conf
|
||||
archive_mode = 'on'
|
||||
archive_library = 'basic_archive'
|
||||
basic_archive.archive_directory = '/path/to/archive/directory'
|
||||
</programlisting>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Notes</title>
|
||||
|
||||
<para>
|
||||
Server crashes may leave temporary files with the prefix
|
||||
<filename>archtemp</filename> in the archive directory. It is recommended to
|
||||
delete such files before restarting the server after a crash. It is safe to
|
||||
remove such files while the server is running as long as they are unrelated
|
||||
to any archiving still in progress, but users should use extra caution when
|
||||
doing so.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Author</title>
|
||||
|
||||
<para>
|
||||
Nathan Bossart
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
@ -3479,7 +3479,7 @@ include_dir 'conf.d'
|
||||
Maximum size to let the WAL grow during automatic
|
||||
checkpoints. This is a soft limit; WAL size can exceed
|
||||
<varname>max_wal_size</varname> under special circumstances, such as
|
||||
heavy load, a failing <varname>archive_command</varname>, or a high
|
||||
heavy load, a failing <varname>archive_library</varname>, or a high
|
||||
<varname>wal_keep_size</varname> setting.
|
||||
If this value is specified without units, it is taken as megabytes.
|
||||
The default is 1 GB.
|
||||
@ -3528,7 +3528,7 @@ include_dir 'conf.d'
|
||||
<para>
|
||||
When <varname>archive_mode</varname> is enabled, completed WAL segments
|
||||
are sent to archive storage by setting
|
||||
<xref linkend="guc-archive-command"/>. In addition to <literal>off</literal>,
|
||||
<xref linkend="guc-archive-library"/>. In addition to <literal>off</literal>,
|
||||
to disable, there are two modes: <literal>on</literal>, and
|
||||
<literal>always</literal>. During normal operation, there is no
|
||||
difference between the two modes, but when set to <literal>always</literal>
|
||||
@ -3538,9 +3538,6 @@ include_dir 'conf.d'
|
||||
<xref linkend="continuous-archiving-in-standby"/> for details.
|
||||
</para>
|
||||
<para>
|
||||
<varname>archive_mode</varname> and <varname>archive_command</varname> are
|
||||
separate variables so that <varname>archive_command</varname> can be
|
||||
changed without leaving archiving mode.
|
||||
This parameter can only be set at server start.
|
||||
<varname>archive_mode</varname> cannot be enabled when
|
||||
<varname>wal_level</varname> is set to <literal>minimal</literal>.
|
||||
@ -3548,6 +3545,28 @@ include_dir 'conf.d'
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry id="guc-archive-library" xreflabel="archive_library">
|
||||
<term><varname>archive_library</varname> (<type>string</type>)
|
||||
<indexterm>
|
||||
<primary><varname>archive_library</varname> configuration parameter</primary>
|
||||
</indexterm>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The library to use for archiving completed WAL file segments. If set to
|
||||
an empty string (the default), archiving via shell is enabled, and
|
||||
<xref linkend="guc-archive-command"/> is used. Otherwise, the specified
|
||||
shared library is used for archiving. For more information, see
|
||||
<xref linkend="backup-archiving-wal"/> and
|
||||
<xref linkend="archive-modules"/>.
|
||||
</para>
|
||||
<para>
|
||||
This parameter can only be set in the
|
||||
<filename>postgresql.conf</filename> file or on the server command line.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry id="guc-archive-command" xreflabel="archive_command">
|
||||
<term><varname>archive_command</varname> (<type>string</type>)
|
||||
<indexterm>
|
||||
@ -3570,9 +3589,11 @@ include_dir 'conf.d'
|
||||
<para>
|
||||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||||
file or on the server command line. It is ignored unless
|
||||
<varname>archive_mode</varname> was enabled at server start.
|
||||
<varname>archive_mode</varname> was enabled at server start and
|
||||
<varname>archive_library</varname> specifies to archive via shell command.
|
||||
If <varname>archive_command</varname> is an empty string (the default) while
|
||||
<varname>archive_mode</varname> is enabled, WAL archiving is temporarily
|
||||
<varname>archive_mode</varname> is enabled and <varname>archive_library</varname>
|
||||
specifies archiving via shell, WAL archiving is temporarily
|
||||
disabled, but the server continues to accumulate WAL segment files in
|
||||
the expectation that a command will soon be provided. Setting
|
||||
<varname>archive_command</varname> to a command that does nothing but
|
||||
@ -3592,7 +3613,7 @@ include_dir 'conf.d'
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The <xref linkend="guc-archive-command"/> is only invoked for
|
||||
The <xref linkend="guc-archive-library"/> is only invoked for
|
||||
completed WAL segments. Hence, if your server generates 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
|
||||
|
||||
@ -99,6 +99,7 @@ CREATE EXTENSION <replaceable>module_name</replaceable>;
|
||||
&amcheck;
|
||||
&auth-delay;
|
||||
&auto-explain;
|
||||
&basic-archive;
|
||||
&bloom;
|
||||
&btree-gin;
|
||||
&btree-gist;
|
||||
|
||||
@ -99,6 +99,7 @@
|
||||
<!ENTITY custom-scan SYSTEM "custom-scan.sgml">
|
||||
<!ENTITY logicaldecoding SYSTEM "logicaldecoding.sgml">
|
||||
<!ENTITY replication-origins SYSTEM "replication-origins.sgml">
|
||||
<!ENTITY archive-modules SYSTEM "archive-modules.sgml">
|
||||
<!ENTITY protocol SYSTEM "protocol.sgml">
|
||||
<!ENTITY sources SYSTEM "sources.sgml">
|
||||
<!ENTITY storage SYSTEM "storage.sgml">
|
||||
@ -112,6 +113,7 @@
|
||||
<!ENTITY amcheck SYSTEM "amcheck.sgml">
|
||||
<!ENTITY auth-delay SYSTEM "auth-delay.sgml">
|
||||
<!ENTITY auto-explain SYSTEM "auto-explain.sgml">
|
||||
<!ENTITY basic-archive SYSTEM "basic-archive.sgml">
|
||||
<!ENTITY bloom SYSTEM "bloom.sgml">
|
||||
<!ENTITY btree-gin SYSTEM "btree-gin.sgml">
|
||||
<!ENTITY btree-gist SYSTEM "btree-gist.sgml">
|
||||
|
||||
@ -935,7 +935,7 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
|
||||
In lieu of using replication slots, it is possible to prevent the removal
|
||||
of old WAL segments using <xref linkend="guc-wal-keep-size"/>, or by
|
||||
storing the segments in an archive using
|
||||
<xref linkend="guc-archive-command"/>.
|
||||
<xref linkend="guc-archive-library"/>.
|
||||
However, these methods often result in retaining more WAL segments than
|
||||
required, whereas replication slots retain only the number of segments
|
||||
known to be needed. On the other hand, replication slots can retain so
|
||||
@ -1386,10 +1386,10 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)'
|
||||
to <literal>always</literal>, and the standby will call the archive
|
||||
command for every WAL segment it receives, whether it's by restoring
|
||||
from the archive or by streaming replication. The shared archive can
|
||||
be handled similarly, but the <varname>archive_command</varname> must
|
||||
be handled similarly, but the <varname>archive_library</varname> must
|
||||
test if the file being archived exists already, and if the existing file
|
||||
has identical contents. This requires more care in the
|
||||
<varname>archive_command</varname>, as it must
|
||||
<varname>archive_library</varname>, as it must
|
||||
be careful to not overwrite an existing file with different contents,
|
||||
but return success if the exactly same file is archived twice. And
|
||||
all that must be done free of race conditions, if two servers attempt
|
||||
|
||||
@ -233,6 +233,7 @@ break is not needed in a wider output rendering.
|
||||
&bgworker;
|
||||
&logicaldecoding;
|
||||
&replication-origins;
|
||||
&archive-modules;
|
||||
|
||||
</part>
|
||||
|
||||
|
||||
@ -102,8 +102,8 @@ PostgreSQL documentation
|
||||
<para>
|
||||
All WAL records required for the backup must contain sufficient full-page writes,
|
||||
which requires you to enable <varname>full_page_writes</varname> on the primary and
|
||||
not to use a tool like <application>pg_compresslog</application> as
|
||||
<varname>archive_command</varname> to remove full-page writes from WAL files.
|
||||
not to use a tool in your <varname>archive_library</varname> to remove
|
||||
full-page writes from WAL files.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
@ -40,7 +40,7 @@ PostgreSQL documentation
|
||||
<para>
|
||||
<application>pg_receivewal</application> streams the write-ahead
|
||||
log in real time as it's being generated on the server, and does not wait
|
||||
for segments to complete like <xref linkend="guc-archive-command"/> does.
|
||||
for segments to complete like <xref linkend="guc-archive-library"/> does.
|
||||
For this reason, it is not necessary to set
|
||||
<xref linkend="guc-archive-timeout"/> when using
|
||||
<application>pg_receivewal</application>.
|
||||
@ -487,11 +487,11 @@ PostgreSQL documentation
|
||||
|
||||
<para>
|
||||
When using <application>pg_receivewal</application> instead of
|
||||
<xref linkend="guc-archive-command"/> as the main WAL backup method, it is
|
||||
<xref linkend="guc-archive-library"/> as the main WAL backup method, it is
|
||||
strongly recommended to use replication slots. Otherwise, the server is
|
||||
free to recycle or remove write-ahead log files before they are backed up,
|
||||
because it does not have any information, either
|
||||
from <xref linkend="guc-archive-command"/> or the replication slots, about
|
||||
from <xref linkend="guc-archive-library"/> or the replication slots, about
|
||||
how far the WAL stream has been archived. Note, however, that a
|
||||
replication slot will fill up the server's disk space if the receiver does
|
||||
not keep up with fetching the WAL data.
|
||||
|
||||
@ -636,7 +636,7 @@
|
||||
WAL files plus one additional WAL file are
|
||||
kept at all times. Also, if WAL archiving is used, old segments cannot be
|
||||
removed or recycled until they are archived. If WAL archiving cannot keep up
|
||||
with the pace that WAL is generated, or if <varname>archive_command</varname>
|
||||
with the pace that WAL is generated, or if <varname>archive_library</varname>
|
||||
fails repeatedly, old WAL files will accumulate in <filename>pg_wal</filename>
|
||||
until the situation is resolved. A slow or failed standby server that
|
||||
uses a replication slot will have the same effect (see
|
||||
|
||||
Reference in New Issue
Block a user