agora inbox for [email protected]help / color / mirror / Atom feed
[PATCH 3/6] Add backlinks to progress reporting documentation 13+ messages / 2 participants [nested] [flat]
* [PATCH 3/6] Add backlinks to progress reporting documentation @ 2021-02-05 22:11 Matthias van de Meent <[email protected]> 0 siblings, 0 replies; 13+ messages in thread From: Matthias van de Meent @ 2021-02-05 22:11 UTC (permalink / raw) Previously, for most progress-reported features, the only place the feature was mentioned is in the progress reporting document itself. This makes the progress reporting more discoverable from the reported commands. --- doc/src/sgml/ref/analyze.sgml | 7 +++++++ doc/src/sgml/ref/cluster.sgml | 6 ++++++ doc/src/sgml/ref/copy.sgml | 14 ++++++++++++++ doc/src/sgml/ref/create_index.sgml | 8 ++++++++ doc/src/sgml/ref/pg_basebackup.sgml | 1 + doc/src/sgml/ref/reindex.sgml | 7 +++++++ doc/src/sgml/ref/vacuum.sgml | 11 +++++++++++ 7 files changed, 54 insertions(+) diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml index 7d816c87c6..9db9070b62 100644 --- a/doc/src/sgml/ref/analyze.sgml +++ b/doc/src/sgml/ref/analyze.sgml @@ -273,6 +273,12 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea will not record new statistics for that table. Any existing statistics will be retained. </para> + + <para> + Each backend running the <command>ANALYZE</command> command will report their + progress to the <structname>pg_stat_progress_analyze</structname> view. + See <xref linkend="analyze-progress-reporting"/> for details. + </para> </refsect1> <refsect1> @@ -291,6 +297,7 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea <member><xref linkend="app-vacuumdb"/></member> <member><xref linkend="runtime-config-resource-vacuum-cost"/></member> <member><xref linkend="autovacuum"/></member> + <member><xref linkend="analyze-progress-reporting"/></member> </simplelist> </refsect1> </refentry> diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml index 5dd21a0189..5c2270f71b 100644 --- a/doc/src/sgml/ref/cluster.sgml +++ b/doc/src/sgml/ref/cluster.sgml @@ -192,6 +192,11 @@ CLUSTER [VERBOSE] are periodically reclustered. </para> + <para> + Each backend running the <command>CLUSTER</command> command will report their + progress to the <structname>pg_stat_progress_cluster</structname> view. + See <xref linkend="cluster-progress-reporting"/> for details. + </para> </refsect1> <refsect1> @@ -242,6 +247,7 @@ CLUSTER <replaceable class="parameter">index_name</replaceable> ON <replaceable <simplelist type="inline"> <member><xref linkend="app-clusterdb"/></member> + <member><xref linkend="cluster-progress-reporting"/></member> </simplelist> </refsect1> </refentry> diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml index 0fca6583af..af3ce72561 100644 --- a/doc/src/sgml/ref/copy.sgml +++ b/doc/src/sgml/ref/copy.sgml @@ -82,6 +82,12 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable specified, data is transmitted via the connection between the client and the server. </para> + + <para> + Each backend running the <command>COPY</command> command will report their + progress to the <structname>pg_stat_progress_copy</structname> view. + See <xref linkend="copy-progress-reporting"/> for details. + </para> </refsect1> <refsect1> @@ -1052,4 +1058,12 @@ COPY [ BINARY ] <replaceable class="parameter">table_name</replaceable> [ WITH NULL AS '<replaceable class="parameter">null_string</replaceable>' ] </synopsis></para> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="copy-progress-reporting"/></member> + </simplelist> + </refsect1> </refentry> diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml index a5271a9f8f..278058f500 100644 --- a/doc/src/sgml/ref/create_index.sgml +++ b/doc/src/sgml/ref/create_index.sgml @@ -865,6 +865,13 @@ Indexes: will interpret it as <literal>USING gist</literal>, to simplify conversion of old databases to GiST. </para> + + <para> + Each backend running the <command>CREATE INDEX</command> command will + report their progress to the + <structname>pg_stat_progress_create_index</structname> view. + See <xref linkend="create-index-progress-reporting"/> for details. + </para> </refsect1> <refsect1> @@ -978,6 +985,7 @@ CREATE INDEX CONCURRENTLY sales_quantity_index ON sales_table (quantity); <member><xref linkend="sql-alterindex"/></member> <member><xref linkend="sql-dropindex"/></member> <member><xref linkend="sql-reindex"/></member> + <member><xref linkend="create-index-progress-reporting"/></member> </simplelist> </refsect1> </refentry> diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml index 5754ad5aa6..14cc88a852 100644 --- a/doc/src/sgml/ref/pg_basebackup.sgml +++ b/doc/src/sgml/ref/pg_basebackup.sgml @@ -904,6 +904,7 @@ PostgreSQL documentation <simplelist type="inline"> <member><xref linkend="app-pgdump"/></member> + <member><xref linkend="basebackup-progress-reporting"/></member> </simplelist> </refsect1> diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml index 07795b5737..f69f5db403 100644 --- a/doc/src/sgml/ref/reindex.sgml +++ b/doc/src/sgml/ref/reindex.sgml @@ -493,6 +493,12 @@ Indexes: is reindexed concurrently, those indexes will be skipped. (It is possible to reindex such indexes without the <command>CONCURRENTLY</command> option.) </para> + + <para> + Each backend running the <command>REINDEX</command> command will report + their progress to the <structname>pg_stat_progress_create_index</structname> + view. See <xref linkend="create-index-progress-reporting"/> for details. + </para> </refsect2> </refsect1> @@ -551,6 +557,7 @@ REINDEX TABLE CONCURRENTLY my_broken_table; <member><xref linkend="sql-createindex"/></member> <member><xref linkend="sql-dropindex"/></member> <member><xref linkend="app-reindexdb"/></member> + <member><xref linkend="create-index-progress-reporting"/></member> </simplelist> </refsect1> </refentry> diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml index 4bb624979b..bab3d00313 100644 --- a/doc/src/sgml/ref/vacuum.sgml +++ b/doc/src/sgml/ref/vacuum.sgml @@ -393,6 +393,15 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet information about automatic and manual vacuuming, see <xref linkend="routine-vacuuming"/>. </para> + <para> + Each backend running the <command>VACUUM</command> command without the + <literal>FULL</literal> option will report their progress in the + <structname>pg_stat_progress_vacuum</structname> view. Backends running + <command>VACUUM</command> with the <literal>FULL</literal> option report + progress in the <structname>pg_stat_progress_cluster</structname> instead. + See <xref linkend="vacuum-progress-reporting"/> and + <xref linkend="cluster-progress-reporting"/> for details. + </para> </refsect1> <refsect1> @@ -422,6 +431,8 @@ VACUUM (VERBOSE, ANALYZE) onek; <member><xref linkend="app-vacuumdb"/></member> <member><xref linkend="runtime-config-resource-vacuum-cost"/></member> <member><xref linkend="autovacuum"/></member> + <member><xref linkend="vacuum-progress-reporting"/></member> + <member><xref linkend="cluster-progress-reporting"/></member> </simplelist> </refsect1> </refentry> -- 2.26.2 --------------DA8D60BF026F7ACE69A9AEE5 Content-Type: text/x-patch; charset=UTF-8; name="v7-0004-0002-review.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="v7-0004-0002-review.patch" ^ permalink raw reply [nested|flat] 13+ 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; 13+ 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] 13+ messages in thread
* [PATCH v22 4/5] restructure archive modules docs in preparation for restore modules @ 2023-02-15 22:48 Nathan Bossart <[email protected]> 0 siblings, 0 replies; 13+ messages in thread From: Nathan Bossart @ 2023-02-15 22:48 UTC (permalink / raw) --- doc/src/sgml/archive-and-restore-modules.sgml | 242 +++++++++--------- 1 file changed, 128 insertions(+), 114 deletions(-) diff --git a/doc/src/sgml/archive-and-restore-modules.sgml b/doc/src/sgml/archive-and-restore-modules.sgml index 10ec96eae9..6e368290b9 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,112 +72,119 @@ 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 or an error is thrown, the server will - keep the original WAL file and retry archiving later. - <replaceable>file</replaceable> will contain just the file name of the WAL - file to archive, while <replaceable>path</replaceable> contains the full - path of the WAL file (including the file name). - </para> - - <note> - <para> - The <function>archive_file_cb</function> callback is called in a - short-lived memory context that will be reset between invocations. If you - need longer-lived storage, create a memory context in the module's - <function>startup_cb</function> callback. + 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 or an error is + thrown, the server will keep the original WAL file and retry archiving + later. <replaceable>file</replaceable> will contain just the file name of + the WAL file to archive, while <replaceable>path</replaceable> contains the + full path of the WAL file (including the file name). </para> - </note> - </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. + <note> + <para> + The <function>archive_file_cb</function> callback is called in a + short-lived memory context that will be reset between invocations. If you + need longer-lived storage, create a memory context in the module's + <function>startup_cb</function> callback. + </para> + </note> + </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 --X1bOJ3K7DJ5YkBrT Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="v22-0005-introduce-restore_library.patch" ^ permalink raw reply [nested|flat] 13+ messages in thread
* [PATCH v23 4/5] restructure archive modules docs in preparation for restore modules @ 2023-02-15 22:48 Nathan Bossart <[email protected]> 0 siblings, 0 replies; 13+ messages in thread From: Nathan Bossart @ 2023-02-15 22:48 UTC (permalink / raw) --- doc/src/sgml/archive-and-restore-modules.sgml | 242 +++++++++--------- 1 file changed, 128 insertions(+), 114 deletions(-) diff --git a/doc/src/sgml/archive-and-restore-modules.sgml b/doc/src/sgml/archive-and-restore-modules.sgml index 10ec96eae9..6e368290b9 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,112 +72,119 @@ 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 or an error is thrown, the server will - keep the original WAL file and retry archiving later. - <replaceable>file</replaceable> will contain just the file name of the WAL - file to archive, while <replaceable>path</replaceable> contains the full - path of the WAL file (including the file name). - </para> - - <note> - <para> - The <function>archive_file_cb</function> callback is called in a - short-lived memory context that will be reset between invocations. If you - need longer-lived storage, create a memory context in the module's - <function>startup_cb</function> callback. + 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 or an error is + thrown, the server will keep the original WAL file and retry archiving + later. <replaceable>file</replaceable> will contain just the file name of + the WAL file to archive, while <replaceable>path</replaceable> contains the + full path of the WAL file (including the file name). </para> - </note> - </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. + <note> + <para> + The <function>archive_file_cb</function> callback is called in a + short-lived memory context that will be reset between invocations. If you + need longer-lived storage, create a memory context in the module's + <function>startup_cb</function> callback. + </para> + </note> + </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.39.3 (Apple Git-146) --+lMYHr7JfqZnFv8q Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="v23-0005-introduce-restore_library.patch" ^ permalink raw reply [nested|flat] 13+ 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; 13+ 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] 13+ messages in thread
* [PATCH v21 4/5] restructure archive modules docs in preparation for restore modules @ 2023-02-15 22:48 Nathan Bossart <[email protected]> 0 siblings, 0 replies; 13+ messages in thread From: Nathan Bossart @ 2023-02-15 22:48 UTC (permalink / raw) --- doc/src/sgml/archive-and-restore-modules.sgml | 242 +++++++++--------- 1 file changed, 128 insertions(+), 114 deletions(-) diff --git a/doc/src/sgml/archive-and-restore-modules.sgml b/doc/src/sgml/archive-and-restore-modules.sgml index 10ec96eae9..6e368290b9 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,112 +72,119 @@ 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 or an error is thrown, the server will - keep the original WAL file and retry archiving later. - <replaceable>file</replaceable> will contain just the file name of the WAL - file to archive, while <replaceable>path</replaceable> contains the full - path of the WAL file (including the file name). - </para> - - <note> - <para> - The <function>archive_file_cb</function> callback is called in a - short-lived memory context that will be reset between invocations. If you - need longer-lived storage, create a memory context in the module's - <function>startup_cb</function> callback. + 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 or an error is + thrown, the server will keep the original WAL file and retry archiving + later. <replaceable>file</replaceable> will contain just the file name of + the WAL file to archive, while <replaceable>path</replaceable> contains the + full path of the WAL file (including the file name). </para> - </note> - </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. + <note> + <para> + The <function>archive_file_cb</function> callback is called in a + short-lived memory context that will be reset between invocations. If you + need longer-lived storage, create a memory context in the module's + <function>startup_cb</function> callback. + </para> + </note> + </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 --PNTmBPCT7hxwcZjr Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="v21-0005-introduce-restore_library.patch" ^ permalink raw reply [nested|flat] 13+ messages in thread
* [PATCH v17 4/5] restructure archive modules docs in preparation for restore modules @ 2023-02-15 22:48 Nathan Bossart <[email protected]> 0 siblings, 0 replies; 13+ 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 --cNdxnHkX5QqsyA0e Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="v17-0005-introduce-restore_library.patch" ^ permalink raw reply [nested|flat] 13+ 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; 13+ 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] 13+ 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; 13+ 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] 13+ messages in thread
* [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; 13+ 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] 13+ 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; 13+ 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] 13+ 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; 13+ 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] 13+ 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; 13+ 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] 13+ messages in thread
end of thread, other threads:[~2023-02-15 22:48 UTC | newest] Thread overview: 13+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2021-02-05 22:11 [PATCH 3/6] Add backlinks to progress reporting documentation Matthias van de Meent <[email protected]> 2023-02-15 22:48 [PATCH v23 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 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 v22 4/5] restructure archive modules docs in preparation for restore modules Nathan Bossart <[email protected]> 2023-02-15 22:48 [PATCH v21 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 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 v17 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]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox