public inbox for [email protected]
help / color / mirror / Atom feed[PATCH v20 4/5] restructure archive modules docs in preparation for restore modules
16+ messages / 3 participants
[nested] [flat]
* [PATCH v16 4/5] restructure archive modules docs in preparation for restore modules
@ 2023-02-15 22:48 Nathan Bossart <[email protected]>
0 siblings, 0 replies; 16+ messages in thread
From: Nathan Bossart @ 2023-02-15 22:48 UTC (permalink / raw)
---
doc/src/sgml/archive-and-restore-modules.sgml | 206 ++++++++++--------
1 file changed, 110 insertions(+), 96 deletions(-)
diff --git a/doc/src/sgml/archive-and-restore-modules.sgml b/doc/src/sgml/archive-and-restore-modules.sgml
index 7064307d9e..7ed50a3b52 100644
--- a/doc/src/sgml/archive-and-restore-modules.sgml
+++ b/doc/src/sgml/archive-and-restore-modules.sgml
@@ -1,9 +1,9 @@
-<!-- doc/src/sgml/archive-modules.sgml -->
+<!-- doc/src/sgml/archive-and-restore-modules.sgml -->
-<chapter id="archive-modules">
- <title>Archive Modules</title>
- <indexterm zone="archive-modules">
- <primary>Archive Modules</primary>
+<chapter id="archive-and-restore-modules">
+ <title>Archive and Restore Modules</title>
+ <indexterm zone="archive-and-restore-modules">
+ <primary>Archive and Restore Modules</primary>
</indexterm>
<para>
@@ -14,45 +14,52 @@
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
- recycling 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>
+ <sect1 id="archive-modules">
+ <title>Archive Modules</title>
+ <indexterm zone="archive-modules">
+ <primary>Archive Modules</primary>
</indexterm>
+
+ <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 recycling 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>
- 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>. The result of the function
- must be a pointer to a struct of type
- <structname>ArchiveModuleCallbacks</structname>, which contains everything
- that the core code needs to know to make use of the archive module. The
- return value needs to be of server lifetime, which is typically achieved by
- defining it as a <literal>static const</literal> variable in global scope.
+ 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>
+
+ <sect2 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>. The result of the function
+ must be a pointer to a struct of type
+ <structname>ArchiveModuleCallbacks</structname>, which contains everything
+ that the core code needs to know to make use of the archive module. The
+ return value needs to be of server lifetime, which is typically achieved by
+ defining it as a <literal>static const</literal> variable in global scope.
<programlisting>
typedef struct ArchiveModuleCallbacks
@@ -65,91 +72,98 @@ typedef struct ArchiveModuleCallbacks
typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit) (void);
</programlisting>
- Only the <function>archive_file_cb</function> callback is required. The
- others are optional.
- </para>
- </sect1>
+ Only the <function>archive_file_cb</function> callback is required. The
+ others are optional.
+ </para>
+ </sect2>
- <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-callbacks">
+ <title>Archive Module Callbacks</title>
- <sect2 id="archive-module-startup">
- <title>Startup Callback</title>
<para>
- The <function>startup_cb</function> callback is called shortly after the
- module is loaded. This callback can be used to perform any additional
- initialization required. If the archive module has any state, it can use
- <structfield>state->private_data</structfield> to store it.
+ 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>
+
+ <sect3 id="archive-module-startup">
+ <title>Startup Callback</title>
+
+ <para>
+ The <function>startup_cb</function> callback is called shortly after the
+ module is loaded. This callback can be used to perform any additional
+ initialization required. If the archive module has any state, it can use
+ <structfield>state->private_data</structfield> to store it.
<programlisting>
typedef void (*ArchiveStartupCB) (ArchiveModuleState *state);
</programlisting>
- </para>
- </sect2>
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state);
</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:
+ 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>
+ In the latter case, the server will periodically call this function, and
+ archiving will proceed only when it returns <literal>true</literal>.
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state, 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.
- <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>
- </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. If the archive module has any state, this callback should
- free it to avoid leaks.
+ 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.
+ <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>
+ </sect3>
+
+ <sect3 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. If the archive module has any state, this callback
+ should free it to avoid leaks.
<programlisting>
typedef void (*ArchiveShutdownCB) (ArchiveModuleState *state);
</programlisting>
- </para>
+ </para>
+ </sect3>
</sect2>
</sect1>
</chapter>
--
2.25.1
--SLDf9lqlvOQaIe6s
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
filename="v16-0005-introduce-restore_library.patch"
^ permalink raw reply [nested|flat] 16+ messages in thread
* [PATCH v12 5/6] restructure archive modules docs in preparation for restore modules
@ 2023-02-15 22:48 Nathan Bossart <[email protected]>
0 siblings, 0 replies; 16+ messages in thread
From: Nathan Bossart @ 2023-02-15 22:48 UTC (permalink / raw)
---
doc/src/sgml/archive-and-restore-modules.sgml | 207 ++++++++++--------
1 file changed, 111 insertions(+), 96 deletions(-)
diff --git a/doc/src/sgml/archive-and-restore-modules.sgml b/doc/src/sgml/archive-and-restore-modules.sgml
index 7cf44e82e2..f30ee591e7 100644
--- a/doc/src/sgml/archive-and-restore-modules.sgml
+++ b/doc/src/sgml/archive-and-restore-modules.sgml
@@ -1,9 +1,9 @@
-<!-- doc/src/sgml/archive-modules.sgml -->
+<!-- doc/src/sgml/archive-and-restore-modules.sgml -->
-<chapter id="archive-modules">
- <title>Archive Modules</title>
- <indexterm zone="archive-modules">
- <primary>Archive Modules</primary>
+<chapter id="archive-and-restore-modules">
+ <title>Archive and Restore Modules</title>
+ <indexterm zone="archive-and-restore-modules">
+ <primary>Archive and Restore Modules</primary>
</indexterm>
<para>
@@ -14,45 +14,53 @@
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
- recycling 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>
+ <sect1 id="archive-modules">
+ <title>Archive Modules</title>
+ <indexterm zone="archive-modules">
+ <primary>Archive Modules</primary>
</indexterm>
+
+ <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 recycling 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>
- 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>. The result of the function
- must be a pointer to a struct of type
- <structname>ArchiveModuleCallbacks</structname>, which contains everything
- that the core code needs to know how to make use of the archive module. The
- return value needs to be of server lifetime, which is typically achieved by
- defining it as a <literal>static const</literal> variable in global scope.
+ 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>
+
+ <sect2 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>. The result of the function
+ must be a pointer to a struct of type
+ <structname>ArchiveModuleCallbacks</structname>, which contains everything
+ that the core code needs to know how to make use of the archive module.
+ The return value needs to be of server lifetime, which is typically
+ achieved by defining it as a <literal>static const</literal> variable in
+ global scope.
<programlisting>
typedef struct ArchiveModuleCallbacks
@@ -65,91 +73,98 @@ typedef struct ArchiveModuleCallbacks
typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit) (void);
</programlisting>
- Only the <function>archive_file_cb</function> callback is required. The
- others are optional.
- </para>
- </sect1>
+ Only the <function>archive_file_cb</function> callback is required. The
+ others are optional.
+ </para>
+ </sect2>
- <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-callbacks">
+ <title>Archive Module Callbacks</title>
- <sect2 id="archive-module-startup">
- <title>Startup Callback</title>
<para>
- The <function>startup_cb</function> callback is called shortly after the
- module is loaded. This callback can be used to perform any additional
- initialization required. If the archive module has a state, it can use
- <structfield>state->private_data</structfield> to store it.
+ 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>
+
+ <sect3 id="archive-module-startup">
+ <title>Startup Callback</title>
+
+ <para>
+ The <function>startup_cb</function> callback is called shortly after the
+ module is loaded. This callback can be used to perform any additional
+ initialization required. If the archive module has state, it can use
+ <structfield>state->private_data</structfield> to store it.
<programlisting>
typedef void (*ArchiveStartupCB) (ArchiveModuleState *state);
</programlisting>
- </para>
- </sect2>
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state);
</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:
+ 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>
+ In the latter case, the server will periodically call this function, and
+ archiving will proceed only when it returns <literal>true</literal>.
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state, 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.
- <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>
- </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. If the archive module has a state, this callback should
- free it to avoid leaks.
+ 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.
+ <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>
+ </sect3>
+
+ <sect3 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. If the archive module has state, this callback should
+ free it to avoid leaks.
<programlisting>
typedef void (*ArchiveShutdownCB) (ArchiveModuleState *state);
</programlisting>
- </para>
+ </para>
+ </sect3>
</sect2>
</sect1>
</chapter>
--
2.25.1
--YiEDa0DAkWCtVeE4
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
filename="v12-0006-introduce-restore_library.patch"
^ permalink raw reply [nested|flat] 16+ messages in thread
* [PATCH v19 4/5] restructure archive modules docs in preparation for restore modules
@ 2023-02-15 22:48 Nathan Bossart <[email protected]>
0 siblings, 0 replies; 16+ messages in thread
From: Nathan Bossart @ 2023-02-15 22:48 UTC (permalink / raw)
---
doc/src/sgml/archive-and-restore-modules.sgml | 226 ++++++++++--------
1 file changed, 120 insertions(+), 106 deletions(-)
diff --git a/doc/src/sgml/archive-and-restore-modules.sgml b/doc/src/sgml/archive-and-restore-modules.sgml
index cf7438a759..a52d15082d 100644
--- a/doc/src/sgml/archive-and-restore-modules.sgml
+++ b/doc/src/sgml/archive-and-restore-modules.sgml
@@ -1,9 +1,9 @@
-<!-- doc/src/sgml/archive-modules.sgml -->
+<!-- doc/src/sgml/archive-and-restore-modules.sgml -->
-<chapter id="archive-modules">
- <title>Archive Modules</title>
- <indexterm zone="archive-modules">
- <primary>Archive Modules</primary>
+<chapter id="archive-and-restore-modules">
+ <title>Archive and Restore Modules</title>
+ <indexterm zone="archive-and-restore-modules">
+ <primary>Archive and Restore Modules</primary>
</indexterm>
<para>
@@ -14,45 +14,52 @@
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
- recycling 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>
+ <sect1 id="archive-modules">
+ <title>Archive Modules</title>
+ <indexterm zone="archive-modules">
+ <primary>Archive Modules</primary>
</indexterm>
+
+ <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 recycling 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>
- 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>. The result of the function
- must be a pointer to a struct of type
- <structname>ArchiveModuleCallbacks</structname>, which contains everything
- that the core code needs to know to make use of the archive module. The
- return value needs to be of server lifetime, which is typically achieved by
- defining it as a <literal>static const</literal> variable in global scope.
+ 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>
+
+ <sect2 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>. The result of the function
+ must be a pointer to a struct of type
+ <structname>ArchiveModuleCallbacks</structname>, which contains everything
+ that the core code needs to know to make use of the archive module. The
+ return value needs to be of server lifetime, which is typically achieved by
+ defining it as a <literal>static const</literal> variable in global scope.
<programlisting>
typedef struct ArchiveModuleCallbacks
@@ -65,103 +72,110 @@ typedef struct ArchiveModuleCallbacks
typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit) (void);
</programlisting>
- Only the <function>archive_file_cb</function> callback is required. The
- others are optional.
- </para>
- </sect1>
+ Only the <function>archive_file_cb</function> callback is required. The
+ others are optional.
+ </para>
+ </sect2>
- <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-callbacks">
+ <title>Archive Module Callbacks</title>
- <sect2 id="archive-module-startup">
- <title>Startup Callback</title>
<para>
- The <function>startup_cb</function> callback is called shortly after the
- module is loaded. This callback can be used to perform any additional
- initialization required. If the archive module has any state, it can use
- <structfield>state->private_data</structfield> to store it.
+ 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>
+
+ <sect3 id="archive-module-startup">
+ <title>Startup Callback</title>
+
+ <para>
+ The <function>startup_cb</function> callback is called shortly after the
+ module is loaded. This callback can be used to perform any additional
+ initialization required. If the archive module has any state, it can use
+ <structfield>state->private_data</structfield> to store it.
<programlisting>
typedef void (*ArchiveStartupCB) (ArchiveModuleState *state);
</programlisting>
- </para>
- </sect2>
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state);
</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:
+ 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>
-
- <note>
- <para>
- When returning <literal>false</literal>, it may be useful to append some
- additional information to the generic warning message. To do that, provide
- a message to the <function>arch_module_check_errdetail</function> macro
- before returning <literal>false</literal>. Like
- <function>errdetail()</function>, this macro accepts a format string
- followed by an optional list of arguments. The resulting string will be
- emitted as the <literal>DETAIL</literal> line of the warning message.
+ In the latter case, the server will periodically call this function, and
+ archiving will proceed only when it returns <literal>true</literal>.
</para>
- </note>
- </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.
+ <note>
+ <para>
+ When returning <literal>false</literal>, it may be useful to append some
+ additional information to the generic warning message. To do that,
+ provide a message to the <function>arch_module_check_errdetail</function>
+ macro before returning <literal>false</literal>. Like
+ <function>errdetail()</function>, this macro accepts a format string
+ followed by an optional list of arguments. The resulting string will be
+ emitted as the <literal>DETAIL</literal> line of the warning message.
+ </para>
+ </note>
+ </sect3>
+
+ <sect3 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) (ArchiveModuleState *state, 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.
- <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>
- </sect2>
+ 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.
+ <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>
+ </sect3>
- <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. If the archive module has any state, this callback should
- free it to avoid leaks.
+ <sect3 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. If the archive module has any state, this callback
+ should free it to avoid leaks.
<programlisting>
typedef void (*ArchiveShutdownCB) (ArchiveModuleState *state);
</programlisting>
- </para>
+ </para>
+ </sect3>
</sect2>
</sect1>
</chapter>
--
2.25.1
--oyUTqETQ0mS9luUI
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
filename="v19-0005-introduce-restore_library.patch"
^ permalink raw reply [nested|flat] 16+ messages in thread
* [PATCH v19 4/5] restructure archive modules docs in preparation for restore modules
@ 2023-02-15 22:48 Nathan Bossart <[email protected]>
0 siblings, 0 replies; 16+ messages in thread
From: Nathan Bossart @ 2023-02-15 22:48 UTC (permalink / raw)
---
doc/src/sgml/archive-and-restore-modules.sgml | 226 ++++++++++--------
1 file changed, 120 insertions(+), 106 deletions(-)
diff --git a/doc/src/sgml/archive-and-restore-modules.sgml b/doc/src/sgml/archive-and-restore-modules.sgml
index cf7438a759..a52d15082d 100644
--- a/doc/src/sgml/archive-and-restore-modules.sgml
+++ b/doc/src/sgml/archive-and-restore-modules.sgml
@@ -1,9 +1,9 @@
-<!-- doc/src/sgml/archive-modules.sgml -->
+<!-- doc/src/sgml/archive-and-restore-modules.sgml -->
-<chapter id="archive-modules">
- <title>Archive Modules</title>
- <indexterm zone="archive-modules">
- <primary>Archive Modules</primary>
+<chapter id="archive-and-restore-modules">
+ <title>Archive and Restore Modules</title>
+ <indexterm zone="archive-and-restore-modules">
+ <primary>Archive and Restore Modules</primary>
</indexterm>
<para>
@@ -14,45 +14,52 @@
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
- recycling 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>
+ <sect1 id="archive-modules">
+ <title>Archive Modules</title>
+ <indexterm zone="archive-modules">
+ <primary>Archive Modules</primary>
</indexterm>
+
+ <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 recycling 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>
- 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>. The result of the function
- must be a pointer to a struct of type
- <structname>ArchiveModuleCallbacks</structname>, which contains everything
- that the core code needs to know to make use of the archive module. The
- return value needs to be of server lifetime, which is typically achieved by
- defining it as a <literal>static const</literal> variable in global scope.
+ 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>
+
+ <sect2 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>. The result of the function
+ must be a pointer to a struct of type
+ <structname>ArchiveModuleCallbacks</structname>, which contains everything
+ that the core code needs to know to make use of the archive module. The
+ return value needs to be of server lifetime, which is typically achieved by
+ defining it as a <literal>static const</literal> variable in global scope.
<programlisting>
typedef struct ArchiveModuleCallbacks
@@ -65,103 +72,110 @@ typedef struct ArchiveModuleCallbacks
typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit) (void);
</programlisting>
- Only the <function>archive_file_cb</function> callback is required. The
- others are optional.
- </para>
- </sect1>
+ Only the <function>archive_file_cb</function> callback is required. The
+ others are optional.
+ </para>
+ </sect2>
- <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-callbacks">
+ <title>Archive Module Callbacks</title>
- <sect2 id="archive-module-startup">
- <title>Startup Callback</title>
<para>
- The <function>startup_cb</function> callback is called shortly after the
- module is loaded. This callback can be used to perform any additional
- initialization required. If the archive module has any state, it can use
- <structfield>state->private_data</structfield> to store it.
+ 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>
+
+ <sect3 id="archive-module-startup">
+ <title>Startup Callback</title>
+
+ <para>
+ The <function>startup_cb</function> callback is called shortly after the
+ module is loaded. This callback can be used to perform any additional
+ initialization required. If the archive module has any state, it can use
+ <structfield>state->private_data</structfield> to store it.
<programlisting>
typedef void (*ArchiveStartupCB) (ArchiveModuleState *state);
</programlisting>
- </para>
- </sect2>
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state);
</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:
+ 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>
-
- <note>
- <para>
- When returning <literal>false</literal>, it may be useful to append some
- additional information to the generic warning message. To do that, provide
- a message to the <function>arch_module_check_errdetail</function> macro
- before returning <literal>false</literal>. Like
- <function>errdetail()</function>, this macro accepts a format string
- followed by an optional list of arguments. The resulting string will be
- emitted as the <literal>DETAIL</literal> line of the warning message.
+ In the latter case, the server will periodically call this function, and
+ archiving will proceed only when it returns <literal>true</literal>.
</para>
- </note>
- </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.
+ <note>
+ <para>
+ When returning <literal>false</literal>, it may be useful to append some
+ additional information to the generic warning message. To do that,
+ provide a message to the <function>arch_module_check_errdetail</function>
+ macro before returning <literal>false</literal>. Like
+ <function>errdetail()</function>, this macro accepts a format string
+ followed by an optional list of arguments. The resulting string will be
+ emitted as the <literal>DETAIL</literal> line of the warning message.
+ </para>
+ </note>
+ </sect3>
+
+ <sect3 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) (ArchiveModuleState *state, 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.
- <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>
- </sect2>
+ 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.
+ <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>
+ </sect3>
- <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. If the archive module has any state, this callback should
- free it to avoid leaks.
+ <sect3 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. If the archive module has any state, this callback
+ should free it to avoid leaks.
<programlisting>
typedef void (*ArchiveShutdownCB) (ArchiveModuleState *state);
</programlisting>
- </para>
+ </para>
+ </sect3>
</sect2>
</sect1>
</chapter>
--
2.25.1
--oyUTqETQ0mS9luUI
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
filename="v19-0005-introduce-restore_library.patch"
^ permalink raw reply [nested|flat] 16+ messages in thread
* [PATCH v14 6/7] restructure archive modules docs in preparation for restore modules
@ 2023-02-15 22:48 Nathan Bossart <[email protected]>
0 siblings, 0 replies; 16+ messages in thread
From: Nathan Bossart @ 2023-02-15 22:48 UTC (permalink / raw)
---
doc/src/sgml/archive-and-restore-modules.sgml | 207 ++++++++++--------
1 file changed, 111 insertions(+), 96 deletions(-)
diff --git a/doc/src/sgml/archive-and-restore-modules.sgml b/doc/src/sgml/archive-and-restore-modules.sgml
index 7cf44e82e2..f30ee591e7 100644
--- a/doc/src/sgml/archive-and-restore-modules.sgml
+++ b/doc/src/sgml/archive-and-restore-modules.sgml
@@ -1,9 +1,9 @@
-<!-- doc/src/sgml/archive-modules.sgml -->
+<!-- doc/src/sgml/archive-and-restore-modules.sgml -->
-<chapter id="archive-modules">
- <title>Archive Modules</title>
- <indexterm zone="archive-modules">
- <primary>Archive Modules</primary>
+<chapter id="archive-and-restore-modules">
+ <title>Archive and Restore Modules</title>
+ <indexterm zone="archive-and-restore-modules">
+ <primary>Archive and Restore Modules</primary>
</indexterm>
<para>
@@ -14,45 +14,53 @@
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
- recycling 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>
+ <sect1 id="archive-modules">
+ <title>Archive Modules</title>
+ <indexterm zone="archive-modules">
+ <primary>Archive Modules</primary>
</indexterm>
+
+ <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 recycling 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>
- 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>. The result of the function
- must be a pointer to a struct of type
- <structname>ArchiveModuleCallbacks</structname>, which contains everything
- that the core code needs to know how to make use of the archive module. The
- return value needs to be of server lifetime, which is typically achieved by
- defining it as a <literal>static const</literal> variable in global scope.
+ 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>
+
+ <sect2 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>. The result of the function
+ must be a pointer to a struct of type
+ <structname>ArchiveModuleCallbacks</structname>, which contains everything
+ that the core code needs to know how to make use of the archive module.
+ The return value needs to be of server lifetime, which is typically
+ achieved by defining it as a <literal>static const</literal> variable in
+ global scope.
<programlisting>
typedef struct ArchiveModuleCallbacks
@@ -65,91 +73,98 @@ typedef struct ArchiveModuleCallbacks
typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit) (void);
</programlisting>
- Only the <function>archive_file_cb</function> callback is required. The
- others are optional.
- </para>
- </sect1>
+ Only the <function>archive_file_cb</function> callback is required. The
+ others are optional.
+ </para>
+ </sect2>
- <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-callbacks">
+ <title>Archive Module Callbacks</title>
- <sect2 id="archive-module-startup">
- <title>Startup Callback</title>
<para>
- The <function>startup_cb</function> callback is called shortly after the
- module is loaded. This callback can be used to perform any additional
- initialization required. If the archive module has a state, it can use
- <structfield>state->private_data</structfield> to store it.
+ 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>
+
+ <sect3 id="archive-module-startup">
+ <title>Startup Callback</title>
+
+ <para>
+ The <function>startup_cb</function> callback is called shortly after the
+ module is loaded. This callback can be used to perform any additional
+ initialization required. If the archive module has state, it can use
+ <structfield>state->private_data</structfield> to store it.
<programlisting>
typedef void (*ArchiveStartupCB) (ArchiveModuleState *state);
</programlisting>
- </para>
- </sect2>
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state);
</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:
+ 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>
+ In the latter case, the server will periodically call this function, and
+ archiving will proceed only when it returns <literal>true</literal>.
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state, 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.
- <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>
- </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. If the archive module has a state, this callback should
- free it to avoid leaks.
+ 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.
+ <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>
+ </sect3>
+
+ <sect3 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. If the archive module has state, this callback should
+ free it to avoid leaks.
<programlisting>
typedef void (*ArchiveShutdownCB) (ArchiveModuleState *state);
</programlisting>
- </para>
+ </para>
+ </sect3>
</sect2>
</sect1>
</chapter>
--
2.25.1
--IS0zKkzwUGydFO0o
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
filename="v14-0007-introduce-restore_library.patch"
^ permalink raw reply [nested|flat] 16+ messages in thread
* [PATCH v18 4/5] restructure archive modules docs in preparation for restore modules
@ 2023-02-15 22:48 Nathan Bossart <[email protected]>
0 siblings, 0 replies; 16+ messages in thread
From: Nathan Bossart @ 2023-02-15 22:48 UTC (permalink / raw)
---
doc/src/sgml/archive-and-restore-modules.sgml | 226 ++++++++++--------
1 file changed, 120 insertions(+), 106 deletions(-)
diff --git a/doc/src/sgml/archive-and-restore-modules.sgml b/doc/src/sgml/archive-and-restore-modules.sgml
index cf7438a759..a52d15082d 100644
--- a/doc/src/sgml/archive-and-restore-modules.sgml
+++ b/doc/src/sgml/archive-and-restore-modules.sgml
@@ -1,9 +1,9 @@
-<!-- doc/src/sgml/archive-modules.sgml -->
+<!-- doc/src/sgml/archive-and-restore-modules.sgml -->
-<chapter id="archive-modules">
- <title>Archive Modules</title>
- <indexterm zone="archive-modules">
- <primary>Archive Modules</primary>
+<chapter id="archive-and-restore-modules">
+ <title>Archive and Restore Modules</title>
+ <indexterm zone="archive-and-restore-modules">
+ <primary>Archive and Restore Modules</primary>
</indexterm>
<para>
@@ -14,45 +14,52 @@
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
- recycling 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>
+ <sect1 id="archive-modules">
+ <title>Archive Modules</title>
+ <indexterm zone="archive-modules">
+ <primary>Archive Modules</primary>
</indexterm>
+
+ <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 recycling 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>
- 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>. The result of the function
- must be a pointer to a struct of type
- <structname>ArchiveModuleCallbacks</structname>, which contains everything
- that the core code needs to know to make use of the archive module. The
- return value needs to be of server lifetime, which is typically achieved by
- defining it as a <literal>static const</literal> variable in global scope.
+ 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>
+
+ <sect2 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>. The result of the function
+ must be a pointer to a struct of type
+ <structname>ArchiveModuleCallbacks</structname>, which contains everything
+ that the core code needs to know to make use of the archive module. The
+ return value needs to be of server lifetime, which is typically achieved by
+ defining it as a <literal>static const</literal> variable in global scope.
<programlisting>
typedef struct ArchiveModuleCallbacks
@@ -65,103 +72,110 @@ typedef struct ArchiveModuleCallbacks
typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit) (void);
</programlisting>
- Only the <function>archive_file_cb</function> callback is required. The
- others are optional.
- </para>
- </sect1>
+ Only the <function>archive_file_cb</function> callback is required. The
+ others are optional.
+ </para>
+ </sect2>
- <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-callbacks">
+ <title>Archive Module Callbacks</title>
- <sect2 id="archive-module-startup">
- <title>Startup Callback</title>
<para>
- The <function>startup_cb</function> callback is called shortly after the
- module is loaded. This callback can be used to perform any additional
- initialization required. If the archive module has any state, it can use
- <structfield>state->private_data</structfield> to store it.
+ 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>
+
+ <sect3 id="archive-module-startup">
+ <title>Startup Callback</title>
+
+ <para>
+ The <function>startup_cb</function> callback is called shortly after the
+ module is loaded. This callback can be used to perform any additional
+ initialization required. If the archive module has any state, it can use
+ <structfield>state->private_data</structfield> to store it.
<programlisting>
typedef void (*ArchiveStartupCB) (ArchiveModuleState *state);
</programlisting>
- </para>
- </sect2>
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state);
</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:
+ 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>
-
- <note>
- <para>
- When returning <literal>false</literal>, it may be useful to append some
- additional information to the generic warning message. To do that, provide
- a message to the <function>arch_module_check_errdetail</function> macro
- before returning <literal>false</literal>. Like
- <function>errdetail()</function>, this macro accepts a format string
- followed by an optional list of arguments. The resulting string will be
- emitted as the <literal>DETAIL</literal> line of the warning message.
+ In the latter case, the server will periodically call this function, and
+ archiving will proceed only when it returns <literal>true</literal>.
</para>
- </note>
- </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.
+ <note>
+ <para>
+ When returning <literal>false</literal>, it may be useful to append some
+ additional information to the generic warning message. To do that,
+ provide a message to the <function>arch_module_check_errdetail</function>
+ macro before returning <literal>false</literal>. Like
+ <function>errdetail()</function>, this macro accepts a format string
+ followed by an optional list of arguments. The resulting string will be
+ emitted as the <literal>DETAIL</literal> line of the warning message.
+ </para>
+ </note>
+ </sect3>
+
+ <sect3 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) (ArchiveModuleState *state, 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.
- <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>
- </sect2>
+ 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.
+ <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>
+ </sect3>
- <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. If the archive module has any state, this callback should
- free it to avoid leaks.
+ <sect3 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. If the archive module has any state, this callback
+ should free it to avoid leaks.
<programlisting>
typedef void (*ArchiveShutdownCB) (ArchiveModuleState *state);
</programlisting>
- </para>
+ </para>
+ </sect3>
</sect2>
</sect1>
</chapter>
--
2.25.1
--IJpNTDwzlM2Ie8A6
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
filename="v18-0005-introduce-restore_library.patch"
^ permalink raw reply [nested|flat] 16+ messages in thread
* [PATCH v18 4/5] restructure archive modules docs in preparation for restore modules
@ 2023-02-15 22:48 Nathan Bossart <[email protected]>
0 siblings, 0 replies; 16+ messages in thread
From: Nathan Bossart @ 2023-02-15 22:48 UTC (permalink / raw)
---
doc/src/sgml/archive-and-restore-modules.sgml | 226 ++++++++++--------
1 file changed, 120 insertions(+), 106 deletions(-)
diff --git a/doc/src/sgml/archive-and-restore-modules.sgml b/doc/src/sgml/archive-and-restore-modules.sgml
index cf7438a759..a52d15082d 100644
--- a/doc/src/sgml/archive-and-restore-modules.sgml
+++ b/doc/src/sgml/archive-and-restore-modules.sgml
@@ -1,9 +1,9 @@
-<!-- doc/src/sgml/archive-modules.sgml -->
+<!-- doc/src/sgml/archive-and-restore-modules.sgml -->
-<chapter id="archive-modules">
- <title>Archive Modules</title>
- <indexterm zone="archive-modules">
- <primary>Archive Modules</primary>
+<chapter id="archive-and-restore-modules">
+ <title>Archive and Restore Modules</title>
+ <indexterm zone="archive-and-restore-modules">
+ <primary>Archive and Restore Modules</primary>
</indexterm>
<para>
@@ -14,45 +14,52 @@
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
- recycling 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>
+ <sect1 id="archive-modules">
+ <title>Archive Modules</title>
+ <indexterm zone="archive-modules">
+ <primary>Archive Modules</primary>
</indexterm>
+
+ <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 recycling 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>
- 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>. The result of the function
- must be a pointer to a struct of type
- <structname>ArchiveModuleCallbacks</structname>, which contains everything
- that the core code needs to know to make use of the archive module. The
- return value needs to be of server lifetime, which is typically achieved by
- defining it as a <literal>static const</literal> variable in global scope.
+ 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>
+
+ <sect2 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>. The result of the function
+ must be a pointer to a struct of type
+ <structname>ArchiveModuleCallbacks</structname>, which contains everything
+ that the core code needs to know to make use of the archive module. The
+ return value needs to be of server lifetime, which is typically achieved by
+ defining it as a <literal>static const</literal> variable in global scope.
<programlisting>
typedef struct ArchiveModuleCallbacks
@@ -65,103 +72,110 @@ typedef struct ArchiveModuleCallbacks
typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit) (void);
</programlisting>
- Only the <function>archive_file_cb</function> callback is required. The
- others are optional.
- </para>
- </sect1>
+ Only the <function>archive_file_cb</function> callback is required. The
+ others are optional.
+ </para>
+ </sect2>
- <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-callbacks">
+ <title>Archive Module Callbacks</title>
- <sect2 id="archive-module-startup">
- <title>Startup Callback</title>
<para>
- The <function>startup_cb</function> callback is called shortly after the
- module is loaded. This callback can be used to perform any additional
- initialization required. If the archive module has any state, it can use
- <structfield>state->private_data</structfield> to store it.
+ 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>
+
+ <sect3 id="archive-module-startup">
+ <title>Startup Callback</title>
+
+ <para>
+ The <function>startup_cb</function> callback is called shortly after the
+ module is loaded. This callback can be used to perform any additional
+ initialization required. If the archive module has any state, it can use
+ <structfield>state->private_data</structfield> to store it.
<programlisting>
typedef void (*ArchiveStartupCB) (ArchiveModuleState *state);
</programlisting>
- </para>
- </sect2>
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state);
</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:
+ 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>
-
- <note>
- <para>
- When returning <literal>false</literal>, it may be useful to append some
- additional information to the generic warning message. To do that, provide
- a message to the <function>arch_module_check_errdetail</function> macro
- before returning <literal>false</literal>. Like
- <function>errdetail()</function>, this macro accepts a format string
- followed by an optional list of arguments. The resulting string will be
- emitted as the <literal>DETAIL</literal> line of the warning message.
+ In the latter case, the server will periodically call this function, and
+ archiving will proceed only when it returns <literal>true</literal>.
</para>
- </note>
- </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.
+ <note>
+ <para>
+ When returning <literal>false</literal>, it may be useful to append some
+ additional information to the generic warning message. To do that,
+ provide a message to the <function>arch_module_check_errdetail</function>
+ macro before returning <literal>false</literal>. Like
+ <function>errdetail()</function>, this macro accepts a format string
+ followed by an optional list of arguments. The resulting string will be
+ emitted as the <literal>DETAIL</literal> line of the warning message.
+ </para>
+ </note>
+ </sect3>
+
+ <sect3 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) (ArchiveModuleState *state, 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.
- <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>
- </sect2>
+ 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.
+ <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>
+ </sect3>
- <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. If the archive module has any state, this callback should
- free it to avoid leaks.
+ <sect3 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. If the archive module has any state, this callback
+ should free it to avoid leaks.
<programlisting>
typedef void (*ArchiveShutdownCB) (ArchiveModuleState *state);
</programlisting>
- </para>
+ </para>
+ </sect3>
</sect2>
</sect1>
</chapter>
--
2.25.1
--IJpNTDwzlM2Ie8A6
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
filename="v18-0005-introduce-restore_library.patch"
^ permalink raw reply [nested|flat] 16+ messages in thread
* [PATCH v20 4/5] restructure archive modules docs in preparation for restore modules
@ 2023-02-15 22:48 Nathan Bossart <[email protected]>
0 siblings, 0 replies; 16+ messages in thread
From: Nathan Bossart @ 2023-02-15 22:48 UTC (permalink / raw)
---
doc/src/sgml/archive-and-restore-modules.sgml | 226 ++++++++++--------
1 file changed, 120 insertions(+), 106 deletions(-)
diff --git a/doc/src/sgml/archive-and-restore-modules.sgml b/doc/src/sgml/archive-and-restore-modules.sgml
index cf7438a759..a52d15082d 100644
--- a/doc/src/sgml/archive-and-restore-modules.sgml
+++ b/doc/src/sgml/archive-and-restore-modules.sgml
@@ -1,9 +1,9 @@
-<!-- doc/src/sgml/archive-modules.sgml -->
+<!-- doc/src/sgml/archive-and-restore-modules.sgml -->
-<chapter id="archive-modules">
- <title>Archive Modules</title>
- <indexterm zone="archive-modules">
- <primary>Archive Modules</primary>
+<chapter id="archive-and-restore-modules">
+ <title>Archive and Restore Modules</title>
+ <indexterm zone="archive-and-restore-modules">
+ <primary>Archive and Restore Modules</primary>
</indexterm>
<para>
@@ -14,45 +14,52 @@
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
- recycling 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>
+ <sect1 id="archive-modules">
+ <title>Archive Modules</title>
+ <indexterm zone="archive-modules">
+ <primary>Archive Modules</primary>
</indexterm>
+
+ <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 recycling 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>
- 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>. The result of the function
- must be a pointer to a struct of type
- <structname>ArchiveModuleCallbacks</structname>, which contains everything
- that the core code needs to know to make use of the archive module. The
- return value needs to be of server lifetime, which is typically achieved by
- defining it as a <literal>static const</literal> variable in global scope.
+ 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>
+
+ <sect2 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>. The result of the function
+ must be a pointer to a struct of type
+ <structname>ArchiveModuleCallbacks</structname>, which contains everything
+ that the core code needs to know to make use of the archive module. The
+ return value needs to be of server lifetime, which is typically achieved by
+ defining it as a <literal>static const</literal> variable in global scope.
<programlisting>
typedef struct ArchiveModuleCallbacks
@@ -65,103 +72,110 @@ typedef struct ArchiveModuleCallbacks
typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit) (void);
</programlisting>
- Only the <function>archive_file_cb</function> callback is required. The
- others are optional.
- </para>
- </sect1>
+ Only the <function>archive_file_cb</function> callback is required. The
+ others are optional.
+ </para>
+ </sect2>
- <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-callbacks">
+ <title>Archive Module Callbacks</title>
- <sect2 id="archive-module-startup">
- <title>Startup Callback</title>
<para>
- The <function>startup_cb</function> callback is called shortly after the
- module is loaded. This callback can be used to perform any additional
- initialization required. If the archive module has any state, it can use
- <structfield>state->private_data</structfield> to store it.
+ 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>
+
+ <sect3 id="archive-module-startup">
+ <title>Startup Callback</title>
+
+ <para>
+ The <function>startup_cb</function> callback is called shortly after the
+ module is loaded. This callback can be used to perform any additional
+ initialization required. If the archive module has any state, it can use
+ <structfield>state->private_data</structfield> to store it.
<programlisting>
typedef void (*ArchiveStartupCB) (ArchiveModuleState *state);
</programlisting>
- </para>
- </sect2>
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state);
</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:
+ 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>
-
- <note>
- <para>
- When returning <literal>false</literal>, it may be useful to append some
- additional information to the generic warning message. To do that, provide
- a message to the <function>arch_module_check_errdetail</function> macro
- before returning <literal>false</literal>. Like
- <function>errdetail()</function>, this macro accepts a format string
- followed by an optional list of arguments. The resulting string will be
- emitted as the <literal>DETAIL</literal> line of the warning message.
+ In the latter case, the server will periodically call this function, and
+ archiving will proceed only when it returns <literal>true</literal>.
</para>
- </note>
- </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.
+ <note>
+ <para>
+ When returning <literal>false</literal>, it may be useful to append some
+ additional information to the generic warning message. To do that,
+ provide a message to the <function>arch_module_check_errdetail</function>
+ macro before returning <literal>false</literal>. Like
+ <function>errdetail()</function>, this macro accepts a format string
+ followed by an optional list of arguments. The resulting string will be
+ emitted as the <literal>DETAIL</literal> line of the warning message.
+ </para>
+ </note>
+ </sect3>
+
+ <sect3 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) (ArchiveModuleState *state, 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.
- <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>
- </sect2>
+ 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.
+ <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>
+ </sect3>
- <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. If the archive module has any state, this callback should
- free it to avoid leaks.
+ <sect3 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. If the archive module has any state, this callback
+ should free it to avoid leaks.
<programlisting>
typedef void (*ArchiveShutdownCB) (ArchiveModuleState *state);
</programlisting>
- </para>
+ </para>
+ </sect3>
</sect2>
</sect1>
</chapter>
--
2.25.1
--3V7upXqbjpZ4EhLz
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
filename="v20-0005-introduce-restore_library.patch"
^ permalink raw reply [nested|flat] 16+ messages in thread
* [PATCH v15 6/7] restructure archive modules docs in preparation for restore modules
@ 2023-02-15 22:48 Nathan Bossart <[email protected]>
0 siblings, 0 replies; 16+ messages in thread
From: Nathan Bossart @ 2023-02-15 22:48 UTC (permalink / raw)
---
doc/src/sgml/archive-and-restore-modules.sgml | 206 ++++++++++--------
1 file changed, 110 insertions(+), 96 deletions(-)
diff --git a/doc/src/sgml/archive-and-restore-modules.sgml b/doc/src/sgml/archive-and-restore-modules.sgml
index 7064307d9e..7ed50a3b52 100644
--- a/doc/src/sgml/archive-and-restore-modules.sgml
+++ b/doc/src/sgml/archive-and-restore-modules.sgml
@@ -1,9 +1,9 @@
-<!-- doc/src/sgml/archive-modules.sgml -->
+<!-- doc/src/sgml/archive-and-restore-modules.sgml -->
-<chapter id="archive-modules">
- <title>Archive Modules</title>
- <indexterm zone="archive-modules">
- <primary>Archive Modules</primary>
+<chapter id="archive-and-restore-modules">
+ <title>Archive and Restore Modules</title>
+ <indexterm zone="archive-and-restore-modules">
+ <primary>Archive and Restore Modules</primary>
</indexterm>
<para>
@@ -14,45 +14,52 @@
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
- recycling 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>
+ <sect1 id="archive-modules">
+ <title>Archive Modules</title>
+ <indexterm zone="archive-modules">
+ <primary>Archive Modules</primary>
</indexterm>
+
+ <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 recycling 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>
- 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>. The result of the function
- must be a pointer to a struct of type
- <structname>ArchiveModuleCallbacks</structname>, which contains everything
- that the core code needs to know to make use of the archive module. The
- return value needs to be of server lifetime, which is typically achieved by
- defining it as a <literal>static const</literal> variable in global scope.
+ 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>
+
+ <sect2 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>. The result of the function
+ must be a pointer to a struct of type
+ <structname>ArchiveModuleCallbacks</structname>, which contains everything
+ that the core code needs to know to make use of the archive module. The
+ return value needs to be of server lifetime, which is typically achieved by
+ defining it as a <literal>static const</literal> variable in global scope.
<programlisting>
typedef struct ArchiveModuleCallbacks
@@ -65,91 +72,98 @@ typedef struct ArchiveModuleCallbacks
typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit) (void);
</programlisting>
- Only the <function>archive_file_cb</function> callback is required. The
- others are optional.
- </para>
- </sect1>
+ Only the <function>archive_file_cb</function> callback is required. The
+ others are optional.
+ </para>
+ </sect2>
- <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-callbacks">
+ <title>Archive Module Callbacks</title>
- <sect2 id="archive-module-startup">
- <title>Startup Callback</title>
<para>
- The <function>startup_cb</function> callback is called shortly after the
- module is loaded. This callback can be used to perform any additional
- initialization required. If the archive module has any state, it can use
- <structfield>state->private_data</structfield> to store it.
+ 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>
+
+ <sect3 id="archive-module-startup">
+ <title>Startup Callback</title>
+
+ <para>
+ The <function>startup_cb</function> callback is called shortly after the
+ module is loaded. This callback can be used to perform any additional
+ initialization required. If the archive module has any state, it can use
+ <structfield>state->private_data</structfield> to store it.
<programlisting>
typedef void (*ArchiveStartupCB) (ArchiveModuleState *state);
</programlisting>
- </para>
- </sect2>
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state);
</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:
+ 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>
+ In the latter case, the server will periodically call this function, and
+ archiving will proceed only when it returns <literal>true</literal>.
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state, 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.
- <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>
- </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. If the archive module has any state, this callback should
- free it to avoid leaks.
+ 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.
+ <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>
+ </sect3>
+
+ <sect3 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. If the archive module has any state, this callback
+ should free it to avoid leaks.
<programlisting>
typedef void (*ArchiveShutdownCB) (ArchiveModuleState *state);
</programlisting>
- </para>
+ </para>
+ </sect3>
</sect2>
</sect1>
</chapter>
--
2.25.1
--k+w/mQv8wyuph6w0
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
filename="v15-0007-introduce-restore_library.patch"
^ permalink raw reply [nested|flat] 16+ messages in thread
* [PATCH v13 6/7] restructure archive modules docs in preparation for restore modules
@ 2023-02-15 22:48 Nathan Bossart <[email protected]>
0 siblings, 0 replies; 16+ messages in thread
From: Nathan Bossart @ 2023-02-15 22:48 UTC (permalink / raw)
---
doc/src/sgml/archive-and-restore-modules.sgml | 207 ++++++++++--------
1 file changed, 111 insertions(+), 96 deletions(-)
diff --git a/doc/src/sgml/archive-and-restore-modules.sgml b/doc/src/sgml/archive-and-restore-modules.sgml
index 7cf44e82e2..f30ee591e7 100644
--- a/doc/src/sgml/archive-and-restore-modules.sgml
+++ b/doc/src/sgml/archive-and-restore-modules.sgml
@@ -1,9 +1,9 @@
-<!-- doc/src/sgml/archive-modules.sgml -->
+<!-- doc/src/sgml/archive-and-restore-modules.sgml -->
-<chapter id="archive-modules">
- <title>Archive Modules</title>
- <indexterm zone="archive-modules">
- <primary>Archive Modules</primary>
+<chapter id="archive-and-restore-modules">
+ <title>Archive and Restore Modules</title>
+ <indexterm zone="archive-and-restore-modules">
+ <primary>Archive and Restore Modules</primary>
</indexterm>
<para>
@@ -14,45 +14,53 @@
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
- recycling 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>
+ <sect1 id="archive-modules">
+ <title>Archive Modules</title>
+ <indexterm zone="archive-modules">
+ <primary>Archive Modules</primary>
</indexterm>
+
+ <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 recycling 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>
- 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>. The result of the function
- must be a pointer to a struct of type
- <structname>ArchiveModuleCallbacks</structname>, which contains everything
- that the core code needs to know how to make use of the archive module. The
- return value needs to be of server lifetime, which is typically achieved by
- defining it as a <literal>static const</literal> variable in global scope.
+ 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>
+
+ <sect2 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>. The result of the function
+ must be a pointer to a struct of type
+ <structname>ArchiveModuleCallbacks</structname>, which contains everything
+ that the core code needs to know how to make use of the archive module.
+ The return value needs to be of server lifetime, which is typically
+ achieved by defining it as a <literal>static const</literal> variable in
+ global scope.
<programlisting>
typedef struct ArchiveModuleCallbacks
@@ -65,91 +73,98 @@ typedef struct ArchiveModuleCallbacks
typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit) (void);
</programlisting>
- Only the <function>archive_file_cb</function> callback is required. The
- others are optional.
- </para>
- </sect1>
+ Only the <function>archive_file_cb</function> callback is required. The
+ others are optional.
+ </para>
+ </sect2>
- <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-callbacks">
+ <title>Archive Module Callbacks</title>
- <sect2 id="archive-module-startup">
- <title>Startup Callback</title>
<para>
- The <function>startup_cb</function> callback is called shortly after the
- module is loaded. This callback can be used to perform any additional
- initialization required. If the archive module has a state, it can use
- <structfield>state->private_data</structfield> to store it.
+ 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>
+
+ <sect3 id="archive-module-startup">
+ <title>Startup Callback</title>
+
+ <para>
+ The <function>startup_cb</function> callback is called shortly after the
+ module is loaded. This callback can be used to perform any additional
+ initialization required. If the archive module has state, it can use
+ <structfield>state->private_data</structfield> to store it.
<programlisting>
typedef void (*ArchiveStartupCB) (ArchiveModuleState *state);
</programlisting>
- </para>
- </sect2>
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state);
</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:
+ 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>
+ In the latter case, the server will periodically call this function, and
+ archiving will proceed only when it returns <literal>true</literal>.
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state, 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.
- <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>
- </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. If the archive module has a state, this callback should
- free it to avoid leaks.
+ 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.
+ <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>
+ </sect3>
+
+ <sect3 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. If the archive module has state, this callback should
+ free it to avoid leaks.
<programlisting>
typedef void (*ArchiveShutdownCB) (ArchiveModuleState *state);
</programlisting>
- </para>
+ </para>
+ </sect3>
</sect2>
</sect1>
</chapter>
--
2.25.1
--5vNYLRcllDrimb99
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
filename="v13-0007-introduce-restore_library.patch"
^ permalink raw reply [nested|flat] 16+ messages in thread
* [PATCH v20 4/5] restructure archive modules docs in preparation for restore modules
@ 2023-02-15 22:48 Nathan Bossart <[email protected]>
0 siblings, 0 replies; 16+ messages in thread
From: Nathan Bossart @ 2023-02-15 22:48 UTC (permalink / raw)
---
doc/src/sgml/archive-and-restore-modules.sgml | 226 ++++++++++--------
1 file changed, 120 insertions(+), 106 deletions(-)
diff --git a/doc/src/sgml/archive-and-restore-modules.sgml b/doc/src/sgml/archive-and-restore-modules.sgml
index cf7438a759..a52d15082d 100644
--- a/doc/src/sgml/archive-and-restore-modules.sgml
+++ b/doc/src/sgml/archive-and-restore-modules.sgml
@@ -1,9 +1,9 @@
-<!-- doc/src/sgml/archive-modules.sgml -->
+<!-- doc/src/sgml/archive-and-restore-modules.sgml -->
-<chapter id="archive-modules">
- <title>Archive Modules</title>
- <indexterm zone="archive-modules">
- <primary>Archive Modules</primary>
+<chapter id="archive-and-restore-modules">
+ <title>Archive and Restore Modules</title>
+ <indexterm zone="archive-and-restore-modules">
+ <primary>Archive and Restore Modules</primary>
</indexterm>
<para>
@@ -14,45 +14,52 @@
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
- recycling 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>
+ <sect1 id="archive-modules">
+ <title>Archive Modules</title>
+ <indexterm zone="archive-modules">
+ <primary>Archive Modules</primary>
</indexterm>
+
+ <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 recycling 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>
- 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>. The result of the function
- must be a pointer to a struct of type
- <structname>ArchiveModuleCallbacks</structname>, which contains everything
- that the core code needs to know to make use of the archive module. The
- return value needs to be of server lifetime, which is typically achieved by
- defining it as a <literal>static const</literal> variable in global scope.
+ 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>
+
+ <sect2 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>. The result of the function
+ must be a pointer to a struct of type
+ <structname>ArchiveModuleCallbacks</structname>, which contains everything
+ that the core code needs to know to make use of the archive module. The
+ return value needs to be of server lifetime, which is typically achieved by
+ defining it as a <literal>static const</literal> variable in global scope.
<programlisting>
typedef struct ArchiveModuleCallbacks
@@ -65,103 +72,110 @@ typedef struct ArchiveModuleCallbacks
typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit) (void);
</programlisting>
- Only the <function>archive_file_cb</function> callback is required. The
- others are optional.
- </para>
- </sect1>
+ Only the <function>archive_file_cb</function> callback is required. The
+ others are optional.
+ </para>
+ </sect2>
- <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-callbacks">
+ <title>Archive Module Callbacks</title>
- <sect2 id="archive-module-startup">
- <title>Startup Callback</title>
<para>
- The <function>startup_cb</function> callback is called shortly after the
- module is loaded. This callback can be used to perform any additional
- initialization required. If the archive module has any state, it can use
- <structfield>state->private_data</structfield> to store it.
+ 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>
+
+ <sect3 id="archive-module-startup">
+ <title>Startup Callback</title>
+
+ <para>
+ The <function>startup_cb</function> callback is called shortly after the
+ module is loaded. This callback can be used to perform any additional
+ initialization required. If the archive module has any state, it can use
+ <structfield>state->private_data</structfield> to store it.
<programlisting>
typedef void (*ArchiveStartupCB) (ArchiveModuleState *state);
</programlisting>
- </para>
- </sect2>
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state);
</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:
+ 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>
-
- <note>
- <para>
- When returning <literal>false</literal>, it may be useful to append some
- additional information to the generic warning message. To do that, provide
- a message to the <function>arch_module_check_errdetail</function> macro
- before returning <literal>false</literal>. Like
- <function>errdetail()</function>, this macro accepts a format string
- followed by an optional list of arguments. The resulting string will be
- emitted as the <literal>DETAIL</literal> line of the warning message.
+ In the latter case, the server will periodically call this function, and
+ archiving will proceed only when it returns <literal>true</literal>.
</para>
- </note>
- </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.
+ <note>
+ <para>
+ When returning <literal>false</literal>, it may be useful to append some
+ additional information to the generic warning message. To do that,
+ provide a message to the <function>arch_module_check_errdetail</function>
+ macro before returning <literal>false</literal>. Like
+ <function>errdetail()</function>, this macro accepts a format string
+ followed by an optional list of arguments. The resulting string will be
+ emitted as the <literal>DETAIL</literal> line of the warning message.
+ </para>
+ </note>
+ </sect3>
+
+ <sect3 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) (ArchiveModuleState *state, 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.
- <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>
- </sect2>
+ 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.
+ <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>
+ </sect3>
- <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. If the archive module has any state, this callback should
- free it to avoid leaks.
+ <sect3 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. If the archive module has any state, this callback
+ should free it to avoid leaks.
<programlisting>
typedef void (*ArchiveShutdownCB) (ArchiveModuleState *state);
</programlisting>
- </para>
+ </para>
+ </sect3>
</sect2>
</sect1>
</chapter>
--
2.25.1
--3V7upXqbjpZ4EhLz
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
filename="v20-0005-introduce-restore_library.patch"
^ permalink raw reply [nested|flat] 16+ messages in thread
* [PATCH v19 4/5] restructure archive modules docs in preparation for restore modules
@ 2023-02-15 22:48 Nathan Bossart <[email protected]>
0 siblings, 0 replies; 16+ messages in thread
From: Nathan Bossart @ 2023-02-15 22:48 UTC (permalink / raw)
---
doc/src/sgml/archive-and-restore-modules.sgml | 226 ++++++++++--------
1 file changed, 120 insertions(+), 106 deletions(-)
diff --git a/doc/src/sgml/archive-and-restore-modules.sgml b/doc/src/sgml/archive-and-restore-modules.sgml
index cf7438a759..a52d15082d 100644
--- a/doc/src/sgml/archive-and-restore-modules.sgml
+++ b/doc/src/sgml/archive-and-restore-modules.sgml
@@ -1,9 +1,9 @@
-<!-- doc/src/sgml/archive-modules.sgml -->
+<!-- doc/src/sgml/archive-and-restore-modules.sgml -->
-<chapter id="archive-modules">
- <title>Archive Modules</title>
- <indexterm zone="archive-modules">
- <primary>Archive Modules</primary>
+<chapter id="archive-and-restore-modules">
+ <title>Archive and Restore Modules</title>
+ <indexterm zone="archive-and-restore-modules">
+ <primary>Archive and Restore Modules</primary>
</indexterm>
<para>
@@ -14,45 +14,52 @@
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
- recycling 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>
+ <sect1 id="archive-modules">
+ <title>Archive Modules</title>
+ <indexterm zone="archive-modules">
+ <primary>Archive Modules</primary>
</indexterm>
+
+ <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 recycling 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>
- 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>. The result of the function
- must be a pointer to a struct of type
- <structname>ArchiveModuleCallbacks</structname>, which contains everything
- that the core code needs to know to make use of the archive module. The
- return value needs to be of server lifetime, which is typically achieved by
- defining it as a <literal>static const</literal> variable in global scope.
+ 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>
+
+ <sect2 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>. The result of the function
+ must be a pointer to a struct of type
+ <structname>ArchiveModuleCallbacks</structname>, which contains everything
+ that the core code needs to know to make use of the archive module. The
+ return value needs to be of server lifetime, which is typically achieved by
+ defining it as a <literal>static const</literal> variable in global scope.
<programlisting>
typedef struct ArchiveModuleCallbacks
@@ -65,103 +72,110 @@ typedef struct ArchiveModuleCallbacks
typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit) (void);
</programlisting>
- Only the <function>archive_file_cb</function> callback is required. The
- others are optional.
- </para>
- </sect1>
+ Only the <function>archive_file_cb</function> callback is required. The
+ others are optional.
+ </para>
+ </sect2>
- <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-callbacks">
+ <title>Archive Module Callbacks</title>
- <sect2 id="archive-module-startup">
- <title>Startup Callback</title>
<para>
- The <function>startup_cb</function> callback is called shortly after the
- module is loaded. This callback can be used to perform any additional
- initialization required. If the archive module has any state, it can use
- <structfield>state->private_data</structfield> to store it.
+ 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>
+
+ <sect3 id="archive-module-startup">
+ <title>Startup Callback</title>
+
+ <para>
+ The <function>startup_cb</function> callback is called shortly after the
+ module is loaded. This callback can be used to perform any additional
+ initialization required. If the archive module has any state, it can use
+ <structfield>state->private_data</structfield> to store it.
<programlisting>
typedef void (*ArchiveStartupCB) (ArchiveModuleState *state);
</programlisting>
- </para>
- </sect2>
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state);
</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:
+ 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>
-
- <note>
- <para>
- When returning <literal>false</literal>, it may be useful to append some
- additional information to the generic warning message. To do that, provide
- a message to the <function>arch_module_check_errdetail</function> macro
- before returning <literal>false</literal>. Like
- <function>errdetail()</function>, this macro accepts a format string
- followed by an optional list of arguments. The resulting string will be
- emitted as the <literal>DETAIL</literal> line of the warning message.
+ In the latter case, the server will periodically call this function, and
+ archiving will proceed only when it returns <literal>true</literal>.
</para>
- </note>
- </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.
+ <note>
+ <para>
+ When returning <literal>false</literal>, it may be useful to append some
+ additional information to the generic warning message. To do that,
+ provide a message to the <function>arch_module_check_errdetail</function>
+ macro before returning <literal>false</literal>. Like
+ <function>errdetail()</function>, this macro accepts a format string
+ followed by an optional list of arguments. The resulting string will be
+ emitted as the <literal>DETAIL</literal> line of the warning message.
+ </para>
+ </note>
+ </sect3>
+
+ <sect3 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) (ArchiveModuleState *state, 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.
- <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>
- </sect2>
+ 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.
+ <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>
+ </sect3>
- <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. If the archive module has any state, this callback should
- free it to avoid leaks.
+ <sect3 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. If the archive module has any state, this callback
+ should free it to avoid leaks.
<programlisting>
typedef void (*ArchiveShutdownCB) (ArchiveModuleState *state);
</programlisting>
- </para>
+ </para>
+ </sect3>
</sect2>
</sect1>
</chapter>
--
2.25.1
--oyUTqETQ0mS9luUI
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
filename="v19-0005-introduce-restore_library.patch"
^ permalink raw reply [nested|flat] 16+ messages in thread
* [PATCH v18 4/5] restructure archive modules docs in preparation for restore modules
@ 2023-02-15 22:48 Nathan Bossart <[email protected]>
0 siblings, 0 replies; 16+ messages in thread
From: Nathan Bossart @ 2023-02-15 22:48 UTC (permalink / raw)
---
doc/src/sgml/archive-and-restore-modules.sgml | 226 ++++++++++--------
1 file changed, 120 insertions(+), 106 deletions(-)
diff --git a/doc/src/sgml/archive-and-restore-modules.sgml b/doc/src/sgml/archive-and-restore-modules.sgml
index cf7438a759..a52d15082d 100644
--- a/doc/src/sgml/archive-and-restore-modules.sgml
+++ b/doc/src/sgml/archive-and-restore-modules.sgml
@@ -1,9 +1,9 @@
-<!-- doc/src/sgml/archive-modules.sgml -->
+<!-- doc/src/sgml/archive-and-restore-modules.sgml -->
-<chapter id="archive-modules">
- <title>Archive Modules</title>
- <indexterm zone="archive-modules">
- <primary>Archive Modules</primary>
+<chapter id="archive-and-restore-modules">
+ <title>Archive and Restore Modules</title>
+ <indexterm zone="archive-and-restore-modules">
+ <primary>Archive and Restore Modules</primary>
</indexterm>
<para>
@@ -14,45 +14,52 @@
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
- recycling 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>
+ <sect1 id="archive-modules">
+ <title>Archive Modules</title>
+ <indexterm zone="archive-modules">
+ <primary>Archive Modules</primary>
</indexterm>
+
+ <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 recycling 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>
- 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>. The result of the function
- must be a pointer to a struct of type
- <structname>ArchiveModuleCallbacks</structname>, which contains everything
- that the core code needs to know to make use of the archive module. The
- return value needs to be of server lifetime, which is typically achieved by
- defining it as a <literal>static const</literal> variable in global scope.
+ 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>
+
+ <sect2 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>. The result of the function
+ must be a pointer to a struct of type
+ <structname>ArchiveModuleCallbacks</structname>, which contains everything
+ that the core code needs to know to make use of the archive module. The
+ return value needs to be of server lifetime, which is typically achieved by
+ defining it as a <literal>static const</literal> variable in global scope.
<programlisting>
typedef struct ArchiveModuleCallbacks
@@ -65,103 +72,110 @@ typedef struct ArchiveModuleCallbacks
typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit) (void);
</programlisting>
- Only the <function>archive_file_cb</function> callback is required. The
- others are optional.
- </para>
- </sect1>
+ Only the <function>archive_file_cb</function> callback is required. The
+ others are optional.
+ </para>
+ </sect2>
- <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-callbacks">
+ <title>Archive Module Callbacks</title>
- <sect2 id="archive-module-startup">
- <title>Startup Callback</title>
<para>
- The <function>startup_cb</function> callback is called shortly after the
- module is loaded. This callback can be used to perform any additional
- initialization required. If the archive module has any state, it can use
- <structfield>state->private_data</structfield> to store it.
+ 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>
+
+ <sect3 id="archive-module-startup">
+ <title>Startup Callback</title>
+
+ <para>
+ The <function>startup_cb</function> callback is called shortly after the
+ module is loaded. This callback can be used to perform any additional
+ initialization required. If the archive module has any state, it can use
+ <structfield>state->private_data</structfield> to store it.
<programlisting>
typedef void (*ArchiveStartupCB) (ArchiveModuleState *state);
</programlisting>
- </para>
- </sect2>
+ </para>
+ </sect3>
- <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.
+ <sect3 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) (ArchiveModuleState *state);
</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:
+ 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>
-
- <note>
- <para>
- When returning <literal>false</literal>, it may be useful to append some
- additional information to the generic warning message. To do that, provide
- a message to the <function>arch_module_check_errdetail</function> macro
- before returning <literal>false</literal>. Like
- <function>errdetail()</function>, this macro accepts a format string
- followed by an optional list of arguments. The resulting string will be
- emitted as the <literal>DETAIL</literal> line of the warning message.
+ In the latter case, the server will periodically call this function, and
+ archiving will proceed only when it returns <literal>true</literal>.
</para>
- </note>
- </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.
+ <note>
+ <para>
+ When returning <literal>false</literal>, it may be useful to append some
+ additional information to the generic warning message. To do that,
+ provide a message to the <function>arch_module_check_errdetail</function>
+ macro before returning <literal>false</literal>. Like
+ <function>errdetail()</function>, this macro accepts a format string
+ followed by an optional list of arguments. The resulting string will be
+ emitted as the <literal>DETAIL</literal> line of the warning message.
+ </para>
+ </note>
+ </sect3>
+
+ <sect3 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) (ArchiveModuleState *state, 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.
- <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>
- </sect2>
+ 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.
+ <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>
+ </sect3>
- <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. If the archive module has any state, this callback should
- free it to avoid leaks.
+ <sect3 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. If the archive module has any state, this callback
+ should free it to avoid leaks.
<programlisting>
typedef void (*ArchiveShutdownCB) (ArchiveModuleState *state);
</programlisting>
- </para>
+ </para>
+ </sect3>
</sect2>
</sect1>
</chapter>
--
2.25.1
--IJpNTDwzlM2Ie8A6
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
filename="v18-0005-introduce-restore_library.patch"
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: BF member drongo doesn't like 035_standby_logical_decoding.pl
@ 2025-01-24 19:44 Andres Freund <[email protected]>
2025-01-27 07:13 ` Re: BF member drongo doesn't like 035_standby_logical_decoding.pl Bertrand Drouvot <[email protected]>
0 siblings, 1 reply; 16+ messages in thread
From: Andres Freund @ 2025-01-24 19:44 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: [email protected]; Andrew Dunstan <[email protected]>; Bertrand Drouvot <[email protected]>
Hi,
On 2025-01-24 14:23:26 -0500, Andres Freund wrote:
> On 2025-01-24 11:42:15 -0500, Tom Lane wrote:
> There's a failure before this one:
> [05:23:54.643](0.013s) not ok 23 - activeslot slot invalidation is logged with vacuum on pg_class
>
>
> > This has been happening for some time, in all three branches where
> > that test script exists. The oldest failure that looks like that in
> > the v16 branch is
> >
> > https://buildfarm.postgresql.org/cgi-bin/show_log.pl?nm=drongo&dt=2024-09-06%2004%3A19%3A35
>
> Hm.
>
> 2024-09-06 05:23:29.031 UTC [1612:14] 035_standby_logical_decoding.pl LOG: logical decoding found consistent point at 0/4000180
> 2024-09-06 05:23:29.031 UTC [1612:15] 035_standby_logical_decoding.pl DETAIL: There are no running transactions.
> 2024-09-06 05:23:29.031 UTC [1612:16] 035_standby_logical_decoding.pl STATEMENT: START_REPLICATION SLOT "row_removal_activeslot" LOGICAL 0/0 ("include-xids" '0', "skip-empty-xacts" '1')
> ...
> 2024-09-06 05:23:49.601 UTC [3984:7] LOG: invalidating obsolete replication slot "row_removal_inactiveslot"
> 2024-09-06 05:23:49.601 UTC [3984:8] DETAIL: The slot conflicted with xid horizon 747.
> 2024-09-06 05:23:49.601 UTC [3984:9] CONTEXT: WAL redo at 0/4020210 for Heap2/PRUNE: snapshotConflictHorizon: 747, nredirected: 0, ndead: 1, nunused: 0, redirected: [], dead: [48], unused: []; blkref #0: rel 1663/16384/2610, blk 0
> ...
> 2024-09-06 05:28:21.043 UTC [5648:6] LOG: restartpoint complete: wrote 17 buffers (13.3%); 0 WAL file(s) added, 0 removed, 0 recycled; write=3.191 s, sync=0.001 s, total=3.192 s; sync files=0, longest=0.000 s, average=0.000 s; distance=249 kB, estimate=29516 kB; lsn=0/403E6B8, redo lsn=0/403E680
> 2024-09-06 05:28:21.043 UTC [5648:7] LOG: recovery restart point at 0/403E680
> ...
> 2024-09-06 05:54:38.414 UTC [3984:10] LOG: invalid record length at 0/403E768: expected at least 24, got 0
>
> There is no further message from 1612 and no intervening message by 3984
> (startup) between invalidating row_removal_inactiveslot and reaching the end
> of the WAL.
>
> The regress_log does have:
>
> Waiting for replication conn standby's replay_lsn to pass 0/403E648 on primary
> done
>
>
> I.e. this looks to not be a failure of the test to find the right message or
> the stats about the terminatio nnot being flushed, but that
> row_removal_activeslot isn't getting terminated. And due to the replay_lsn
> check on the primary, we know that replication must have progressed past the
> point of the conflict. So the problem doesn't appear to be that we're waiting
> for termination, but that somehow we determined that termination is not
> necessary.
>
> Unfortunately with the logs available I can't really pinpoint why. I think we
> need to
> a) increase the postgres log level for the standby
> b) add some explicit debug logging to report the contents of
> pg_replication_slots
>
> I hope the issue is that somehow we didn't need to terminate, rather than
> missing the need to terminate and just continuing on with replay. But I can't
> think of a scenario in which there wouldn't be a need to terminate...
<thinks>
Hm, maybe I'm missing something, but isn't it possible for the active slot to
actually progress decoding past the conflict point? It's an active slot, with
the consumer running in the background, so all that needs to happen for that
is that logical decoding progresses past the conflict point. That requires
there be some reference to a newer xid to be in the WAL, but there's nothing
preventing that afaict?
In fact, I now saw this comment:
# Note that pg_current_snapshot() is used to get the horizon. It does
# not generate a Transaction/COMMIT WAL record, decreasing the risk of
# seeing a xl_running_xacts that would advance an active replication slot's
# catalog_xmin. Advancing the active replication slot's catalog_xmin
# would break some tests that expect the active slot to conflict with
# the catalog xmin horizon.
Which seems precisely what's happening here?
If that's the issue, I think we need to find a way to block logical decoding
from making forward progress during the test.
The easiest way would be to stop pg_recvlogical and emit a bunch of changes,
so that the backend is stalled sending out data. But that'd require a hard to
predict amount of data to be emitted, which isn't great.
But perhaps we could do something smarter, by starting a session on the
primary that acquires an access exclusive lock on a relation that logical
decoding will need to access? The tricky bit likely would be that it'd
somehow need to *not* prevent VACUUM on the primary.
If we could trigger VACUUM in a transaction on the primary this would be
easy, but we can't.
Greetings,
Andres
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: BF member drongo doesn't like 035_standby_logical_decoding.pl
2025-01-24 19:44 Re: BF member drongo doesn't like 035_standby_logical_decoding.pl Andres Freund <[email protected]>
@ 2025-01-27 07:13 ` Bertrand Drouvot <[email protected]>
2025-02-10 14:47 ` Re: BF member drongo doesn't like 035_standby_logical_decoding.pl Bertrand Drouvot <[email protected]>
0 siblings, 1 reply; 16+ messages in thread
From: Bertrand Drouvot @ 2025-01-27 07:13 UTC (permalink / raw)
To: Andres Freund <[email protected]>; +Cc: Tom Lane <[email protected]>; [email protected]; Andrew Dunstan <[email protected]>
Hi,
On Fri, Jan 24, 2025 at 02:44:21PM -0500, Andres Freund wrote:
> Hm, maybe I'm missing something, but isn't it possible for the active slot to
> actually progress decoding past the conflict point? It's an active slot, with
> the consumer running in the background, so all that needs to happen for that
> is that logical decoding progresses past the conflict point. That requires
> there be some reference to a newer xid to be in the WAL, but there's nothing
> preventing that afaict?
>
>
> In fact, I now saw this comment:
>
> # Note that pg_current_snapshot() is used to get the horizon. It does
> # not generate a Transaction/COMMIT WAL record, decreasing the risk of
> # seeing a xl_running_xacts that would advance an active replication slot's
> # catalog_xmin. Advancing the active replication slot's catalog_xmin
> # would break some tests that expect the active slot to conflict with
> # the catalog xmin horizon.
Yeah, that comes from 46d8587b504 (where we tried to reduce as much as possible
the risk of seeing an unwanted xl_running_xacts being generated).
> Which seems precisely what's happening here?
Much probably yes.
> If that's the issue, I think we need to find a way to block logical decoding
> from making forward progress during the test.
>
> The easiest way would be to stop pg_recvlogical and emit a bunch of changes,
> so that the backend is stalled sending out data. But that'd require a hard to
> predict amount of data to be emitted, which isn't great.
What about using an injection point instead to block pg_recvlogical until
we want it to resume?
> But perhaps we could do something smarter, by starting a session on the
> primary that acquires an access exclusive lock on a relation that logical
> decoding will need to access? The tricky bit likely would be that it'd
> somehow need to *not* prevent VACUUM on the primary.
Hm, I'm not sure how we could do that.
> If we could trigger VACUUM in a transaction on the primary this would be
> easy, but we can't.
Another idea that I had ([1]) was to make use of injection points
around places where RUNNING_XACTS is emitted. IIRC I tried to work on this but
that was not simple as it sounds as we need the startup process not to be blocked
.
[1]: https://www.postgresql.org/message-id/ZmadPZlEecJNbhvI%40ip-10-97-1-34.eu-west-3.compute.internal
Regards,
--
Bertrand Drouvot
PostgreSQL Contributors Team
RDS Open Source Databases
Amazon Web Services: https://aws.amazon.com
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: BF member drongo doesn't like 035_standby_logical_decoding.pl
2025-01-24 19:44 Re: BF member drongo doesn't like 035_standby_logical_decoding.pl Andres Freund <[email protected]>
2025-01-27 07:13 ` Re: BF member drongo doesn't like 035_standby_logical_decoding.pl Bertrand Drouvot <[email protected]>
@ 2025-02-10 14:47 ` Bertrand Drouvot <[email protected]>
0 siblings, 0 replies; 16+ messages in thread
From: Bertrand Drouvot @ 2025-02-10 14:47 UTC (permalink / raw)
To: Andres Freund <[email protected]>; +Cc: Tom Lane <[email protected]>; [email protected]; Andrew Dunstan <[email protected]>
Hi,
On Mon, Jan 27, 2025 at 07:13:01AM +0000, Bertrand Drouvot wrote:
> On Fri, Jan 24, 2025 at 02:44:21PM -0500, Andres Freund wrote:
> > If we could trigger VACUUM in a transaction on the primary this would be
> > easy, but we can't.
>
> Another idea that I had ([1]) was to make use of injection points
> around places where RUNNING_XACTS is emitted. IIRC I tried to work on this but
> that was not simple as it sounds as we need the startup process not to be blocked
> .
I just proposed a patch to make use of an injection point to prevent the catalog_xmin
of a logical slot to advance past the conflict point ([1]). That does not fix the
issue on v16 though.
[1]: https://www.postgresql.org/message-id/flat/Z6oQXc8LmiTLfwLA%40ip-10-97-1-34.eu-west-3.compute.intern...
Regards,
--
Bertrand Drouvot
PostgreSQL Contributors Team
RDS Open Source Databases
Amazon Web Services: https://aws.amazon.com
^ permalink raw reply [nested|flat] 16+ messages in thread
end of thread, other threads:[~2025-02-10 14:47 UTC | newest]
Thread overview: 16+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2023-02-15 22:48 [PATCH v16 4/5] restructure archive modules docs in preparation for restore modules Nathan Bossart <[email protected]>
2023-02-15 22:48 [PATCH v12 5/6] restructure archive modules docs in preparation for restore modules Nathan Bossart <[email protected]>
2023-02-15 22:48 [PATCH v19 4/5] restructure archive modules docs in preparation for restore modules Nathan Bossart <[email protected]>
2023-02-15 22:48 [PATCH v19 4/5] restructure archive modules docs in preparation for restore modules Nathan Bossart <[email protected]>
2023-02-15 22:48 [PATCH v14 6/7] restructure archive modules docs in preparation for restore modules Nathan Bossart <[email protected]>
2023-02-15 22:48 [PATCH v18 4/5] restructure archive modules docs in preparation for restore modules Nathan Bossart <[email protected]>
2023-02-15 22:48 [PATCH v18 4/5] restructure archive modules docs in preparation for restore modules Nathan Bossart <[email protected]>
2023-02-15 22:48 [PATCH v20 4/5] restructure archive modules docs in preparation for restore modules Nathan Bossart <[email protected]>
2023-02-15 22:48 [PATCH v15 6/7] restructure archive modules docs in preparation for restore modules Nathan Bossart <[email protected]>
2023-02-15 22:48 [PATCH v13 6/7] restructure archive modules docs in preparation for restore modules Nathan Bossart <[email protected]>
2023-02-15 22:48 [PATCH v20 4/5] restructure archive modules docs in preparation for restore modules Nathan Bossart <[email protected]>
2023-02-15 22:48 [PATCH v19 4/5] restructure archive modules docs in preparation for restore modules Nathan Bossart <[email protected]>
2023-02-15 22:48 [PATCH v18 4/5] restructure archive modules docs in preparation for restore modules Nathan Bossart <[email protected]>
2025-01-24 19:44 Re: BF member drongo doesn't like 035_standby_logical_decoding.pl Andres Freund <[email protected]>
2025-01-27 07:13 ` Re: BF member drongo doesn't like 035_standby_logical_decoding.pl Bertrand Drouvot <[email protected]>
2025-02-10 14:47 ` Re: BF member drongo doesn't like 035_standby_logical_decoding.pl Bertrand Drouvot <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox