| 1 |
<!-- doc/src/sgml/archive-modules.sgml --> |
| 2 |
|
| 3 |
<chapter id="archive-modules"> |
| 4 |
<title>Archive Modules</title> |
| 5 |
<indexterm zone="archive-modules"> |
| 6 |
<primary>Archive Modules</primary> |
| 7 |
</indexterm> |
| 8 |
|
| 9 |
<para> |
| 10 |
PostgreSQL provides infrastructure to create custom modules for continuous |
| 11 |
archiving (see <xref linkend="continuous-archiving"/>). While archiving via |
| 12 |
a shell command (i.e., <xref linkend="guc-archive-command"/>) is much |
| 13 |
simpler, a custom archive module will often be considerably more robust and |
| 14 |
performant. |
| 15 |
</para> |
| 16 |
|
| 17 |
<para> |
| 18 |
When a custom <xref linkend="guc-archive-library"/> is configured, PostgreSQL |
| 19 |
will submit completed WAL files to the module, and the server will avoid |
| 20 |
recycling or removing these WAL files until the module indicates that the files |
| 21 |
were successfully archived. It is ultimately up to the module to decide what |
| 22 |
to do with each WAL file, but many recommendations are listed at |
| 23 |
<xref linkend="backup-archiving-wal"/>. |
| 24 |
</para> |
| 25 |
|
| 26 |
<para> |
| 27 |
Archiving modules must at least consist of an initialization function (see |
| 28 |
<xref linkend="archive-module-init"/>) and the required callbacks (see |
| 29 |
<xref linkend="archive-module-callbacks"/>). However, archive modules are |
| 30 |
also permitted to do much more (e.g., declare GUCs and register background |
| 31 |
workers). |
| 32 |
</para> |
| 33 |
|
| 34 |
<para> |
| 35 |
The <filename>contrib/basic_archive</filename> module contains a working |
| 36 |
example, which demonstrates some useful techniques. |
| 37 |
</para> |
| 38 |
|
| 39 |
<sect1 id="archive-module-init"> |
| 40 |
<title>Initialization Functions</title> |
| 41 |
<indexterm zone="archive-module-init"> |
| 42 |
<primary>_PG_archive_module_init</primary> |
| 43 |
</indexterm> |
| 44 |
<para> |
| 45 |
An archive library is loaded by dynamically loading a shared library with the |
| 46 |
<xref linkend="guc-archive-library"/>'s name as the library base name. The |
| 47 |
normal library search path is used to locate the library. To provide the |
| 48 |
required archive module callbacks and to indicate that the library is |
| 49 |
actually an archive module, it needs to provide a function named |
| 50 |
<function>_PG_archive_module_init</function>. The result of the function |
| 51 |
must be a pointer to a struct of type |
| 52 |
<structname>ArchiveModuleCallbacks</structname>, which contains everything |
| 53 |
that the core code needs to know to make use of the archive module. The |
| 54 |
return value needs to be of server lifetime, which is typically achieved by |
| 55 |
defining it as a <literal>static const</literal> variable in global scope. |
| 56 |
|
| 57 |
<programlisting> |
| 58 |
typedef struct ArchiveModuleCallbacks |
| 59 |
{ |
| 60 |
ArchiveStartupCB startup_cb; |
| 61 |
ArchiveCheckConfiguredCB check_configured_cb; |
| 62 |
ArchiveFileCB archive_file_cb; |
| 63 |
ArchiveShutdownCB shutdown_cb; |
| 64 |
} ArchiveModuleCallbacks; |
| 65 |
typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit) (void); |
| 66 |
</programlisting> |
| 67 |
|
| 68 |
Only the <function>archive_file_cb</function> callback is required. The |
| 69 |
others are optional. |
| 70 |
</para> |
| 71 |
</sect1> |
| 72 |
|
| 73 |
<sect1 id="archive-module-callbacks"> |
| 74 |
<title>Archive Module Callbacks</title> |
| 75 |
<para> |
| 76 |
The archive callbacks define the actual archiving behavior of the module. |
| 77 |
The server will call them as required to process each individual WAL file. |
| 78 |
</para> |
| 79 |
|
| 80 |
<sect2 id="archive-module-startup"> |
| 81 |
<title>Startup Callback</title> |
| 82 |
<para> |
| 83 |
The <function>startup_cb</function> callback is called shortly after the |
| 84 |
module is loaded. This callback can be used to perform any additional |
| 85 |
initialization required. If the archive module has any state, it can use |
| 86 |
<structfield>state->private_data</structfield> to store it. |
| 87 |
|
| 88 |
<programlisting> |
| 89 |
typedef void (*ArchiveStartupCB) (ArchiveModuleState *state); |
| 90 |
</programlisting> |
| 91 |
</para> |
| 92 |
</sect2> |
| 93 |
|
| 94 |
<sect2 id="archive-module-check"> |
| 95 |
<title>Check Callback</title> |
| 96 |
<para> |
| 97 |
The <function>check_configured_cb</function> callback is called to determine |
| 98 |
whether the module is fully configured and ready to accept WAL files (e.g., |
| 99 |
its configuration parameters are set to valid values). If no |
| 100 |
<function>check_configured_cb</function> is defined, the server always |
| 101 |
assumes the module is configured. |
| 102 |
|
| 103 |
<programlisting> |
| 104 |
typedef bool (*ArchiveCheckConfiguredCB) (ArchiveModuleState *state); |
| 105 |
</programlisting> |
| 106 |
|
| 107 |
If <literal>true</literal> is returned, the server will proceed with |
| 108 |
archiving the file by calling the <function>archive_file_cb</function> |
| 109 |
callback. If <literal>false</literal> is returned, archiving will not |
| 110 |
proceed, and the archiver will emit the following message to the server log: |
| 111 |
<screen> |
| 112 |
WARNING: archive_mode enabled, yet archiving is not configured |
| 113 |
</screen> |
| 114 |
In the latter case, the server will periodically call this function, and |
| 115 |
archiving will proceed only when it returns <literal>true</literal>. |
| 116 |
</para> |
| 117 |
|
| 118 |
<note> |
| 119 |
<para> |
| 120 |
When returning <literal>false</literal>, it may be useful to append some |
| 121 |
additional information to the generic warning message. To do that, provide |
| 122 |
a message to the <function>arch_module_check_errdetail</function> macro |
| 123 |
before returning <literal>false</literal>. Like |
| 124 |
<function>errdetail()</function>, this macro accepts a format string |
| 125 |
followed by an optional list of arguments. The resulting string will be |
| 126 |
emitted as the <literal>DETAIL</literal> line of the warning message. |
| 127 |
</para> |
| 128 |
</note> |
| 129 |
</sect2> |
| 130 |
|
| 131 |
<sect2 id="archive-module-archive"> |
| 132 |
<title>Archive Callback</title> |
| 133 |
<para> |
| 134 |
The <function>archive_file_cb</function> callback is called to archive a |
| 135 |
single WAL file. |
| 136 |
|
| 137 |
<programlisting> |
| 138 |
typedef bool (*ArchiveFileCB) (ArchiveModuleState *state, const char *file, const char *path); |
| 139 |
</programlisting> |
| 140 |
|
| 141 |
If <literal>true</literal> is returned, the server proceeds as if the file |
| 142 |
was successfully archived, which may include recycling or removing the |
| 143 |
original WAL file. If <literal>false</literal> is returned or an error is thrown, the server will |
| 144 |
keep the original WAL file and retry archiving later. |
| 145 |
<replaceable>file</replaceable> will contain just the file name of the WAL |
| 146 |
file to archive, while <replaceable>path</replaceable> contains the full |
| 147 |
path of the WAL file (including the file name). |
| 148 |
</para> |
| 149 |
|
| 150 |
<note> |
| 151 |
<para> |
| 152 |
The <function>archive_file_cb</function> callback is called in a |
| 153 |
short-lived memory context that will be reset between invocations. If you |
| 154 |
need longer-lived storage, create a memory context in the module's |
| 155 |
<function>startup_cb</function> callback. |
| 156 |
</para> |
| 157 |
</note> |
| 158 |
</sect2> |
| 159 |
|
| 160 |
<sect2 id="archive-module-shutdown"> |
| 161 |
<title>Shutdown Callback</title> |
| 162 |
<para> |
| 163 |
The <function>shutdown_cb</function> callback is called when the archiver |
| 164 |
process exits (e.g., after an error) or the value of |
| 165 |
<xref linkend="guc-archive-library"/> changes. If no |
| 166 |
<function>shutdown_cb</function> is defined, no special action is taken in |
| 167 |
these situations. If the archive module has any state, this callback should |
| 168 |
free it to avoid leaks. |
| 169 |
|
| 170 |
<programlisting> |
| 171 |
typedef void (*ArchiveShutdownCB) (ArchiveModuleState *state); |
| 172 |
</programlisting> |
| 173 |
</para> |
| 174 |
</sect2> |
| 175 |
</sect1> |
| 176 |
</chapter> |