Rename contrib module basic_archive to basic_wal_module

This rename is in preparation for the introduction of recovery modules,
where basic_wal_module will be used as a base template for the set of
callbacks introduced.  The former name did not really reflect all that.

Author: Nathan Bossart
Discussion: https://postgr.es/m/20221227192449.GA3672473@nathanxps13

diff --git a/contrib/Makefile b/contrib/Makefile
index bbf220407b0bfc79f1b64b5eca07fae5b86b186e..98acaf8690b6b2624f92b75690d2bd7f229cc296 100644 (file)
--- a/contrib/Makefile
+++ b/contrib/Makefile
@@ -9,7 +9,7 @@ SUBDIRS = \
        amcheck     \
        auth_delay  \
        auto_explain    \
-       basic_archive   \
+       basic_wal_module    \
        basebackup_to_shell \
        bloom       \
        btree_gin   \

diff --git a/contrib/basic_archive/basic_archive.conf b/contrib/basic_archive/basic_archive.conf
deleted file mode 100644 (file)
index 7c82a4b..0000000
--- a/contrib/basic_archive/basic_archive.conf
+++ /dev/null
@@ -1,4 +0,0 @@
-archive_mode = on
-archive_library = 'basic_archive'
-basic_archive.archive_directory = '.'
-wal_level = replica

diff --git a/contrib/basic_archive/meson.build b/contrib/basic_archive/meson.build
deleted file mode 100644 (file)
index bc1380e..0000000
--- a/contrib/basic_archive/meson.build
+++ /dev/null
@@ -1,34 +0,0 @@
-# Copyright (c) 2022-2023, PostgreSQL Global Development Group
-
-basic_archive_sources = files(
-  'basic_archive.c',
-)
-
-if host_system == 'windows'
-  basic_archive_sources += rc_lib_gen.process(win32ver_rc, extra_args: [
-    '--NAME', 'basic_archive',
-    '--FILEDESC', 'basic_archive - basic archive module',])
-endif
-
-basic_archive = shared_module('basic_archive',
-  basic_archive_sources,
-  kwargs: contrib_mod_args,
-)
-contrib_targets += basic_archive
-
-tests += {
-  'name': 'basic_archive',
-  'sd': meson.current_source_dir(),
-  'bd': meson.current_build_dir(),
-  'regress': {
-    'sql': [
-      'basic_archive',
-    ],
-    'regress_args': [
-      '--temp-config', files('basic_archive.conf'),
-    ],
-    # Disabled because these tests require "shared_preload_libraries=basic_archive",
-    # which typical runningcheck users do not have (e.g. buildfarm clients).
-    'runningcheck': false,
-  },
-}

diff --git a/contrib/basic_archive/.gitignore b/contrib/basic_wal_module/.gitignore
similarity index 100%
rename from contrib/basic_archive/.gitignore
rename to contrib/basic_wal_module/.gitignore

diff --git a/contrib/basic_archive/Makefile b/contrib/basic_wal_module/Makefile
similarity index 55%
rename from contrib/basic_archive/Makefile
rename to contrib/basic_wal_module/Makefile
index 55d299d650c280ebdc691fddd228bac253fc88c9..1f88aaf4693aa63a3c73ade64f9870977e9a50fe 100644 (file)
--- a/contrib/basic_archive/Makefile
+++ b/contrib/basic_wal_module/Makefile
@@ -1,11 +1,11 @@
-# contrib/basic_archive/Makefile
+# contrib/basic_wal_module/Makefile
 
-MODULES = basic_archive
-PGFILEDESC = "basic_archive - basic archive module"
+MODULES = basic_wal_module
+PGFILEDESC = "basic_wal_module - basic write-ahead log module"
 
-REGRESS = basic_archive
-REGRESS_OPTS = --temp-config $(top_srcdir)/contrib/basic_archive/basic_archive.conf
-# Disabled because these tests require "shared_preload_libraries=basic_archive",
+REGRESS = basic_wal_module
+REGRESS_OPTS = --temp-config $(top_srcdir)/contrib/basic_wal_module/basic_wal_module.conf
+# Disabled because these tests require "shared_preload_libraries=basic_wal_module",
 # which typical installcheck users do not have (e.g. buildfarm clients).
 NO_INSTALLCHECK = 1
 
@@ -14,7 +14,7 @@ PG_CONFIG = pg_config
 PGXS := $(shell $(PG_CONFIG) --pgxs)
 include $(PGXS)
 else
-subdir = contrib/basic_archive
+subdir = contrib/basic_wal_module
 top_builddir = ../..
 include $(top_builddir)/src/Makefile.global
 include $(top_srcdir)/contrib/contrib-global.mk

diff --git a/contrib/basic_archive/basic_archive.c b/contrib/basic_wal_module/basic_wal_module.c
similarity index 93%
rename from contrib/basic_archive/basic_archive.c
rename to contrib/basic_wal_module/basic_wal_module.c
index 3d29711a316dd9e97f388d87d0e19847cd48406e..78c36656a8bdaa2a166891fa19718deecdab68cd 100644 (file)
--- a/contrib/basic_archive/basic_archive.c
+++ b/contrib/basic_wal_module/basic_wal_module.c
@@ -1,6 +1,6 @@
 /*-------------------------------------------------------------------------
  *
- * basic_archive.c
+ * basic_wal_module.c
  *
  * This file demonstrates a basic archive library implementation that is
  * roughly equivalent to the following shell command:
@@ -20,7 +20,7 @@
  * Copyright (c) 2022-2023, PostgreSQL Global Development Group
  *
  * IDENTIFICATION
- *   contrib/basic_archive/basic_archive.c
+ *   contrib/basic_wal_module/basic_wal_module.c
  *
  *-------------------------------------------------------------------------
  */
@@ -41,7 +41,7 @@
 PG_MODULE_MAGIC;
 
 static char *archive_directory = NULL;
-static MemoryContext basic_archive_context;
+static MemoryContext basic_wal_module_context;
 
 static bool basic_archive_configured(void);
 static bool basic_archive_file(const char *file, const char *path);
@@ -57,7 +57,7 @@ static bool compare_files(const char *file1, const char *file2);
 void
 _PG_init(void)
 {
-   DefineCustomStringVariable("basic_archive.archive_directory",
+   DefineCustomStringVariable("basic_wal_module.archive_directory",
                               gettext_noop("Archive file destination directory."),
                               NULL,
                               &archive_directory,
@@ -66,11 +66,11 @@ _PG_init(void)
                               0,
                               check_archive_directory, NULL, NULL);
 
-   MarkGUCPrefixReserved("basic_archive");
+   MarkGUCPrefixReserved("basic_wal_module");
 
-   basic_archive_context = AllocSetContextCreate(TopMemoryContext,
-                                                 "basic_archive",
-                                                 ALLOCSET_DEFAULT_SIZES);
+   basic_wal_module_context = AllocSetContextCreate(TopMemoryContext,
+                                                    "basic_wal_module",
+                                                    ALLOCSET_DEFAULT_SIZES);
 }
 
 /*
@@ -156,7 +156,7 @@ basic_archive_file(const char *file, const char *path)
     * we can easily reset it during error recovery (thus avoiding memory
     * leaks).
     */
-   oldcontext = MemoryContextSwitchTo(basic_archive_context);
+   oldcontext = MemoryContextSwitchTo(basic_wal_module_context);
 
    /*
     * Since the archiver operates at the bottom of the exception stack,
@@ -183,7 +183,7 @@ basic_archive_file(const char *file, const char *path)
 
        /* Reset our memory context and switch back to the original one */
        MemoryContextSwitchTo(oldcontext);
-       MemoryContextReset(basic_archive_context);
+       MemoryContextReset(basic_wal_module_context);
 
        /* Remove our exception handler */
        PG_exception_stack = NULL;
@@ -206,7 +206,7 @@ basic_archive_file(const char *file, const char *path)
 
    /* Reset our memory context and switch back to the original one */
    MemoryContextSwitchTo(oldcontext);
-   MemoryContextReset(basic_archive_context);
+   MemoryContextReset(basic_wal_module_context);
 
    return true;
 }
@@ -221,7 +221,7 @@ basic_archive_file_internal(const char *file, const char *path)
    uint64      epoch;          /* milliseconds */
 
    ereport(DEBUG3,
-           (errmsg("archiving \"%s\" via basic_archive", file)));
+           (errmsg("archiving \"%s\" via basic_wal_module", file)));
 
    snprintf(destination, MAXPGPATH, "%s/%s", archive_directory, file);
 
@@ -285,7 +285,7 @@ basic_archive_file_internal(const char *file, const char *path)
    (void) durable_rename(temp, destination, ERROR);
 
    ereport(DEBUG1,
-           (errmsg("archived \"%s\" via basic_archive", file)));
+           (errmsg("archived \"%s\" via basic_wal_module", file)));
 }
 
 /*

diff --git a/contrib/basic_wal_module/basic_wal_module.conf b/contrib/basic_wal_module/basic_wal_module.conf
new file mode 100644 (file)
index 0000000..9a4ffac
--- /dev/null
+++ b/contrib/basic_wal_module/basic_wal_module.conf
@@ -0,0 +1,4 @@
+archive_mode = on
+archive_library = 'basic_wal_module'
+basic_wal_module.archive_directory = '.'
+wal_level = replica

diff --git a/contrib/basic_archive/expected/basic_archive.out b/contrib/basic_wal_module/expected/basic_wal_module.out
similarity index 100%
rename from contrib/basic_archive/expected/basic_archive.out
rename to contrib/basic_wal_module/expected/basic_wal_module.out

diff --git a/contrib/basic_wal_module/meson.build b/contrib/basic_wal_module/meson.build
new file mode 100644 (file)
index 0000000..59939d7
--- /dev/null
+++ b/contrib/basic_wal_module/meson.build
@@ -0,0 +1,34 @@
+# Copyright (c) 2022-2023, PostgreSQL Global Development Group
+
+basic_wal_module_sources = files(
+  'basic_wal_module.c',
+)
+
+if host_system == 'windows'
+  basic_wal_module_sources += rc_lib_gen.process(win32ver_rc, extra_args: [
+    '--NAME', 'basic_wal_module',
+    '--FILEDESC', 'basic_wal_module - basic write-ahead log module',])
+endif
+
+basic_wal_module = shared_module('basic_wal_module',
+  basic_wal_module_sources,
+  kwargs: contrib_mod_args,
+)
+contrib_targets += basic_wal_module
+
+tests += {
+  'name': 'basic_wal_module',
+  'sd': meson.current_source_dir(),
+  'bd': meson.current_build_dir(),
+  'regress': {
+    'sql': [
+      'basic_wal_module',
+    ],
+    'regress_args': [
+      '--temp-config', files('basic_wal_module.conf'),
+    ],
+    # Disabled because these tests require "shared_preload_libraries=basic_wal_module",
+    # which typical runningcheck users do not have (e.g. buildfarm clients).
+    'runningcheck': false,
+  },
+}

diff --git a/contrib/basic_archive/sql/basic_archive.sql b/contrib/basic_wal_module/sql/basic_wal_module.sql
similarity index 100%
rename from contrib/basic_archive/sql/basic_archive.sql
rename to contrib/basic_wal_module/sql/basic_wal_module.sql

diff --git a/contrib/meson.build b/contrib/meson.build
index bd4a57c43c095b8b19315d18cad11c3486828ca9..2db77a18d74190dbb5d0777c81018068f55d9038 100644 (file)
--- a/contrib/meson.build
+++ b/contrib/meson.build
@@ -11,7 +11,7 @@ subdir('adminpack')
 subdir('amcheck')
 subdir('auth_delay')
 subdir('auto_explain')
-subdir('basic_archive')
+subdir('basic_wal_module')
 subdir('bloom')
 subdir('basebackup_to_shell')
 subdir('bool_plperl')

diff --git a/doc/src/sgml/appendix-obsolete-basic-archive.sgml b/doc/src/sgml/appendix-obsolete-basic-archive.sgml
new file mode 100644 (file)
index 0000000..5070b3b
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete-basic-archive.sgml
@@ -0,0 +1,25 @@
+<!-- doc/src/sgml/appendix-obsolete-basic-archive.sgml -->
+<!--
+  See doc/src/sgml/appendix-obsolete.sgml for why this file exists. Do not change the id attribute.
+-->
+
+<sect1 id="basic-archive" xreflabel="basic_archive">
+  <title><command>basic_archive</command> renamed to <command>basic_wal_module</command></title>
+
+   <indexterm>
+     <primary>basic_archive</primary>
+     <see>basic_wal_module</see>
+   </indexterm>
+
+   <para>
+    PostgreSQL 15 provided an archive module named
+    <filename>basic_archive</filename>
+    <indexterm><primary>basic_archive</primary></indexterm>.
+    This module was renamed to <filename>basic_wal_module</filename>.  See
+    <xref linkend="basic-wal-module"/> for documentation of
+    <filename>basic_wal_module</filename>, and see
+    <link linkend="release-prior">the release notes for PostgreSQL 16</link>
+    for details on this change.
+   </para>
+
+</sect1>

diff --git a/doc/src/sgml/appendix-obsolete.sgml b/doc/src/sgml/appendix-obsolete.sgml
index b1a00c8ce67b5515d93d14e6ff82dd842471ead8..87c1b1020dfc3cae02cef7f19c7718205d1d5f8f 100644 (file)
--- a/doc/src/sgml/appendix-obsolete.sgml
+++ b/doc/src/sgml/appendix-obsolete.sgml
@@ -38,5 +38,6 @@
  &obsolete-pgxlogdump;
  &obsolete-pgresetxlog;
  &obsolete-pgreceivexlog;
+ &obsolete-basic-archive;
 
 </appendix>

diff --git a/doc/src/sgml/archive-modules.sgml b/doc/src/sgml/archive-modules.sgml
index ef02051f7f08f0a34899be360df479a54e72b2a3..1a32006e2c7cf0c9f8668757ec44e5de29da1700 100644 (file)
--- a/doc/src/sgml/archive-modules.sgml
+++ b/doc/src/sgml/archive-modules.sgml
@@ -32,7 +32,7 @@
  </para>
 
  <para>
-  The <filename>contrib/basic_archive</filename> module contains a working
+  The <filename>contrib/basic_wal_module</filename> module contains a working
   example, which demonstrates some useful techniques.
  </para>
 

diff --git a/doc/src/sgml/basic-archive.sgml b/doc/src/sgml/basic-wal-module.sgml
similarity index 64%
rename from doc/src/sgml/basic-archive.sgml
rename to doc/src/sgml/basic-wal-module.sgml
index b4d43ced203b24e04b58e3f89984691b0a07db05..c418b01eb85d07c2ad6c604cb716c6d3f402c306 100644 (file)
--- a/doc/src/sgml/basic-archive.sgml
+++ b/doc/src/sgml/basic-wal-module.sgml
@@ -1,16 +1,16 @@
-<!-- doc/src/sgml/basic-archive.sgml -->
+<!-- doc/src/sgml/basic-wal-module.sgml -->
 
-<sect1 id="basic-archive" xreflabel="basic_archive">
- <title>basic_archive &mdash; an example WAL archive module</title>
+<sect1 id="basic-wal-module" xreflabel="basic_wal_module">
+ <title>basic_wal_module &mdash; an example write-ahead log module</title>
 
- <indexterm zone="basic-archive">
-  <primary>basic_archive</primary>
+ <indexterm zone="basic-wal-module">
+  <primary>basic_wal_module</primary>
  </indexterm>
 
  <para>
-  <filename>basic_archive</filename> is an example of an archive module.  This
-  module copies completed WAL segment files to the specified directory.  This
-  may not be especially useful, but it can serve as a starting point for
+  <filename>basic_wal_module</filename> is an example of an archive module.
+  This module copies completed WAL segment files to the specified directory.
+  This may not be especially useful, but it can serve as a starting point for
   developing your own archive module.  For more information about archive
   modules, see <xref linkend="archive-modules"/>.
  </para>
@@ -21,15 +21,15 @@
   must be enabled.
  </para>
 
- <sect2 id="basic-archive-configuration-parameters">
+ <sect2 id="basic-wal-module-configuration-parameters">
   <title>Configuration Parameters</title>
 
   <variablelist>
    <varlistentry>
     <term>
-     <varname>basic_archive.archive_directory</varname> (<type>string</type>)
+     <varname>basic_wal_module.archive_directory</varname> (<type>string</type>)
      <indexterm>
-      <primary><varname>basic_archive.archive_directory</varname> configuration parameter</primary>
+      <primary><varname>basic_wal_module.archive_directory</varname> configuration parameter</primary>
      </indexterm>
     </term>
     <listitem>
@@ -52,12 +52,12 @@
 <programlisting>
 # postgresql.conf
 archive_mode = 'on'
-archive_library = 'basic_archive'
-basic_archive.archive_directory = '/path/to/archive/directory'
+archive_library = 'basic_wal_module'
+basic_wal_module.archive_directory = '/path/to/archive/directory'
 </programlisting>
  </sect2>
 
- <sect2 id="basic-archive-notes">
+ <sect2 id="basic-wal-module-notes">
   <title>Notes</title>
 
   <para>
@@ -70,7 +70,7 @@ basic_archive.archive_directory = '/path/to/archive/directory'
   </para>
  </sect2>
 
- <sect2 id="basic-archive-author">
+ <sect2 id="basic-wal-module-author">
   <title>Author</title>
 
   <para>

diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml
index 12c79b798ba3c48abb5320bb33e331e6b8e81489..3225284eead3e8daae5998f6114771f4fc3c18c2 100644 (file)
--- a/doc/src/sgml/contrib.sgml
+++ b/doc/src/sgml/contrib.sgml
@@ -105,7 +105,7 @@ CREATE EXTENSION <replaceable>extension_name</replaceable>;
  &auth-delay;
  &auto-explain;
  &basebackup-to-shell;
- &basic-archive;
+ &basic-wal-module;
  &bloom;
  &btree-gin;
  &btree-gist;

diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 0d6be9a2faf9a0bb8648f2fb0111050b804055c4..2d36c34ce813b0a6e7c7c828482f873782e1656d 100644 (file)
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -116,7 +116,7 @@
 <!ENTITY amcheck         SYSTEM "amcheck.sgml">
 <!ENTITY auth-delay      SYSTEM "auth-delay.sgml">
 <!ENTITY auto-explain    SYSTEM "auto-explain.sgml">
-<!ENTITY basic-archive   SYSTEM "basic-archive.sgml">
+<!ENTITY basic-wal-module SYSTEM "basic-wal-module.sgml">
 <!ENTITY basebackup-to-shell SYSTEM "basebackup-to-shell.sgml">
 <!ENTITY bloom           SYSTEM "bloom.sgml">
 <!ENTITY btree-gin       SYSTEM "btree-gin.sgml">
@@ -200,3 +200,4 @@
 <!ENTITY obsolete-pgxlogdump SYSTEM "appendix-obsolete-pgxlogdump.sgml">
 <!ENTITY obsolete-pgresetxlog SYSTEM "appendix-obsolete-pgresetxlog.sgml">
 <!ENTITY obsolete-pgreceivexlog SYSTEM "appendix-obsolete-pgreceivexlog.sgml">
+<!ENTITY obsolete-basic-archive SYSTEM "appendix-obsolete-basic-archive.sgml">