aboutsummaryrefslogtreecommitdiff
path: root/doc/src
diff options
context:
space:
mode:
authorNathan Bossart <nathan@postgresql.org>2024-04-02 22:28:11 -0500
committerNathan Bossart <nathan@postgresql.org>2024-04-02 22:28:11 -0500
commitc627d944e6c2620fb3b28f2e4b27e19212f84045 (patch)
tree6f7c99617576ec8332ad0287bc9a37f83f8fe8af /doc/src
parent5bec1d6bc5e3ee44a229228a2749567eb2ab7beb (diff)
downloadpostgresql-c627d944e6c2620fb3b28f2e4b27e19212f84045.tar.gz
postgresql-c627d944e6c2620fb3b28f2e4b27e19212f84045.zip
Add built-in ERROR handling for archive callbacks.
Presently, the archiver process restarts when an archive callback ERRORs. To avoid this, archive module authors can use sigsetjmp(), manage a memory context, etc., but that requires a lot of extra code that will likely look roughly the same between modules. This commit adds basic archive callback ERROR handling to pgarch.c so that module authors won't ordinarily need to worry about this. While this built-in handler attempts to clean up anything that an archive module could conceivably have left behind, it is possible that some modules are doing unexpected things that require additional cleanup. Module authors should be sure to do any extra required cleanup in a PG_CATCH block within the archiving callback. The archiving callback is now called in a short-lived memory context that the archiver process resets between invocations. If a module requires longer-lived storage, it must maintain its own memory context. Thanks to these changes, the basic_archive module can be greatly simplified. Suggested-by: Andres Freund Reviewed-by: Andres Freund, Yong Li Discussion: https://postgr.es/m/20230217215624.GA3131134%40nathanxps13
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/sgml/archive-modules.sgml11
1 files changed, 10 insertions, 1 deletions
diff --git a/doc/src/sgml/archive-modules.sgml b/doc/src/sgml/archive-modules.sgml
index cf7438a7593..10ec96eae96 100644
--- a/doc/src/sgml/archive-modules.sgml
+++ b/doc/src/sgml/archive-modules.sgml
@@ -140,12 +140,21 @@ typedef bool (*ArchiveFileCB) (ArchiveModuleState *state, const char *file, cons
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
+ original WAL file. If <literal>false</literal> is returned or an error is thrown, the server will
keep the original WAL file and retry archiving later.
<replaceable>file</replaceable> will contain just the file name of the WAL
file to archive, while <replaceable>path</replaceable> contains the full
path of the WAL file (including the file name).
</para>
+
+ <note>
+ <para>
+ The <function>archive_file_cb</function> callback is called in a
+ short-lived memory context that will be reset between invocations. If you
+ need longer-lived storage, create a memory context in the module's
+ <function>startup_cb</function> callback.
+ </para>
+ </note>
</sect2>
<sect2 id="archive-module-shutdown">