Add macro for customizing an archiving WARNING message.

nathan-bossart · nathan-bossart · commit 2c29e7fc95b2 · 2024-03-04T15:41:42.000-06:00
Presently, if an archive module's check_configured_cb callback returns false, a generic WARNING message is emitted, which unfortunately provides no actionable details about the reason why the module is not configured. This commit introduces a macro that archive module authors can use to add a DETAIL line to this WARNING message. Co-authored-by: Tung Nguyen Reviewed-by: Daniel Gustafsson, Álvaro Herrera Discussion: https://postgr.es/m/4109578306242a7cd5661171647e11b2%40oss.nttdata.com
diff --git a/contrib/basic_archive/basic_archive.c b/contrib/basic_archive/basic_archive.c
@@ -161,7 +161,12 @@ check_archive_directory(char **newval, void **extra, GucSource source)
 static bool
 basic_archive_configured(ArchiveModuleState *state)
 {
-	return archive_directory != NULL && archive_directory[0] != '\0';
+	if (archive_directory != NULL && archive_directory[0] != '\0')
+		return true;
+
+	arch_module_check_errdetail("%s is not set.",
+								"basic_archive.archive_directory");
+	return false;
 }
 
 /*
diff --git a/doc/src/sgml/archive-modules.sgml b/doc/src/sgml/archive-modules.sgml
@@ -114,6 +114,18 @@ WARNING:  archive_mode enabled, yet archiving is not configured
     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.
+    </para>
+   </note>
   </sect2>
 
   <sect2 id="archive-module-archive">
diff --git a/src/backend/archive/shell_archive.c b/src/backend/archive/shell_archive.c
@@ -45,7 +45,12 @@ shell_archive_init(void)
 static bool
 shell_archive_configured(ArchiveModuleState *state)
 {
-	return XLogArchiveCommand[0] != '\0';
+	if (XLogArchiveCommand[0] != '\0')
+		return true;
+
+	arch_module_check_errdetail("%s is not set.",
+								"archive_command");
+	return false;
 }
 
 static bool
diff --git a/src/backend/postmaster/pgarch.c b/src/backend/postmaster/pgarch.c
@@ -88,6 +88,7 @@ typedef struct PgArchData
 } PgArchData;
 
 char	   *XLogArchiveLibrary = "";
+char	   *arch_module_check_errdetail_string;
 
 
 /* ----------
@@ -401,12 +402,17 @@ pgarch_ArchiverCopyLoop(void)
 			 */
 			HandlePgArchInterrupts();
 
+			/* Reset variables that might be set by the callback */
+			arch_module_check_errdetail_string = NULL;
+
 			/* can't do anything if not configured ... */
 			if (ArchiveCallbacks->check_configured_cb != NULL &&
 				!ArchiveCallbacks->check_configured_cb(archive_module_state))
 			{
 				ereport(WARNING,
-						(errmsg("archive_mode enabled, yet archiving is not configured")));
+						(errmsg("archive_mode enabled, yet archiving is not configured"),
+						 arch_module_check_errdetail_string ?
+						 errdetail_internal("%s", arch_module_check_errdetail_string) : 0));
 				return;
 			}
 
diff --git a/src/include/archive/archive_module.h b/src/include/archive/archive_module.h
@@ -56,4 +56,12 @@ typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit) (void);
 
 extern PGDLLEXPORT const ArchiveModuleCallbacks *_PG_archive_module_init(void);
 
+/* Support for messages reported from archive module callbacks. */
+
+extern PGDLLIMPORT char *arch_module_check_errdetail_string;
+
+#define arch_module_check_errdetail \
+	pre_format_elog_string(errno, TEXTDOMAIN), \
+	arch_module_check_errdetail_string = format_elog_string
+
 #endif							/* _ARCHIVE_MODULE_H */

Original file line number	Diff line number	Diff line change
`@@ -161,7 +161,12 @@ check_archive_directory(char newval, void extra, GucSource source)`
`161`	`161`	`static bool`
`162`	`162`	`basic_archive_configured(ArchiveModuleState *state)`
`163`	`163`	`{`
`164`		`- return archive_directory != NULL && archive_directory[0] != '\0';`
	`164`	`+ if (archive_directory != NULL && archive_directory[0] != '\0')`
	`165`	`+ return true;`
	`166`	`+`
	`167`	`+ arch_module_check_errdetail("%s is not set.",`
	`168`	`+ "basic_archive.archive_directory");`
	`169`	`+ return false;`
`165`	`170`	`}`
`166`	`171`
`167`	`172`	`/*`
Original file line number	Diff line number	Diff line change
`@@ -45,7 +45,12 @@ shell_archive_init(void)`
`45`	`45`	`static bool`
`46`	`46`	`shell_archive_configured(ArchiveModuleState *state)`
`47`	`47`	`{`
`48`		`- return XLogArchiveCommand[0] != '\0';`
	`48`	`+ if (XLogArchiveCommand[0] != '\0')`
	`49`	`+ return true;`
	`50`	`+`
	`51`	`+ arch_module_check_errdetail("%s is not set.",`
	`52`	`+ "archive_command");`
	`53`	`+ return false;`
`49`	`54`	`}`
`50`	`55`
`51`	`56`	`static bool`