feat(spring): Support auditing multiple datasources

The audit suite injected DataSource and EntityManagerFactory by type, so
it was ambiguous in an application with several datasources. Let a
consumer wire the whole suite at any chosen (DataSource,
EntityManagerFactory) pair, once per datasource. Core is unchanged: it
stays dependency-injection-neutral, and the EntityManagerFactory
constructor argument is the targeting hook.

Extract DatabaseAuditSuite, a plain factory that wires the entire audit
graph for one (DataSource, EntityManagerFactory) pair and exposes the
DatabaseAuditAssertions facade plus each *AuditAssertion. It is now the
single place mirroring core's audit constructors.
DatabaseAuditTestConfiguration builds one suite from the context's
primary DataSource/EntityManagerFactory and delegates every assertion
bean to it, keeping the existing bean names; its capturer and facade
beans are @primary so the default config's by-type injections survive
the extra datasources' beans.

An application with multiple datasources adds one @TestConfiguration per
datasource that builds a suite from its @qualifier'd beans. The archetype
generates these from a new dataSourceNames property (comma-separated,
default 'none'): for each name it emits a
DatabaseAudit<Name>TestConfiguration plus a @disabled
DatabaseAudit<Name>IT under multi/, named alongside the default
DatabaseAuditTestConfiguration with the datasource name inserted (e.g.
DatabaseAuditAuroraTestConfiguration). The multi/ token templates are
expanded once per name by archetype-post-generate.groovy.

* Add DatabaseAuditSuite and update DatabaseAuditTestConfigurationIT to
  construct the suite against core's constructors.
* Add the dataSourceNames archetype property and a multi-datasource
  self-test variant; cover per-name expansion and the multi/ deletion in
  PostGenerateScriptTest.
* Document the suite and the property in usage.adoc, architecture.adoc,
  archetype.adoc, and CLAUDE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UkRk16pW4VEM3E6vrDoG5y

Author: jeffjensen

CLAUDE.md

@@ -52,13 +52,24 @@ Use the bundled Maven wrapper from this directory. JDK 21 is required.
 
 ## Architecture
 
-### The config mirrors core's constructors — keep them in sync
-
-Each `@Bean` method in `DatabaseAuditTestConfiguration` calls a core audit's constructor directly. There is no
-component scan and no magic: **when a core audit's constructor signature changes (or an audit is added/removed),
-this class must change in lockstep**, or the wiring fails to compile against core. This is the spring-boot half of
-core's standing directive ("when updating any audit class, also update the spring-boot beans"). Treat a compile
-failure here as a signal to read the changed core constructor.
+### `DatabaseAuditSuite` mirrors core's constructors — keep them in sync
+
+`DatabaseAuditSuite` (`src/main/java/.../spring/boot/`) is the single place that calls core's audit and
+collaborator constructors directly: it wires the whole graph for one `(DataSource, EntityManagerFactory)` pair and
+exposes each `*AuditAssertion` plus the `DatabaseAuditAssertions` facade. `DatabaseAuditTestConfiguration` builds
+one suite from the context's primary `DataSource`/`EntityManagerFactory` and registers its assertions as `@Bean`s
+(no component scan). **When a core audit's constructor signature changes (or an audit is added/removed),
+`DatabaseAuditSuite` must change in lockstep** — and a new audit also needs its `*AuditAssertion` and a delegating
+`@Bean` in the config. This is the spring-boot half of core's standing directive ("when updating any audit class,
+also update the spring-boot beans"); a compile failure against core is the intended signal.
+
+To audit **multiple datasources**, a consumer builds one `DatabaseAuditSuite` per datasource from its
+`@Qualifier`'d beans in a `@TestConfiguration` named `DatabaseAudit<Name>TestConfiguration` (mirroring the default
+config with the datasource name inserted). The archetype generates one such config plus a `@Disabled`
+`DatabaseAudit<Name>IT` per name under `multi/` when `-DdataSourceNames=Aurora,Reporting`: the `multi/` holds
+`DsNameToken` token templates that `archetype-post-generate.groovy` expands once per name (`dataSourceNames` is a
+declared property, default `none`). The default config's capturer and facade beans are `@Primary` so its by-type
+injections survive the extra datasources' beans.
 
 ### Platform detection and the PostgreSQL-only plan audits
 

archetype/src/main/resources/META-INF/archetype-post-generate.groovy

@@ -61,3 +61,39 @@ def destRoot = (generateMode == 'project') ? outputDir : resolveDestRoot(targetD
 if (parentClass != 'none') {
     new File(destRoot, "src/test/java/${packagePath}/AbstractDatabaseAuditIT.java").delete()
 }
+
+// For each name in dataSourceNames (comma-separated; 'none' or empty means none), generate a
+// DatabaseAudit<Name>TestConfiguration plus a DatabaseAudit<Name>IT from the multi/ token templates, then delete
+// the templates; with no names, remove the whole multi/ directory.
+def dataSourceNames = request.properties.getProperty('dataSourceNames', 'none')
+def multiDir = new File(destRoot, "src/test/java/${packagePath}/multi")
+def names = []
+if (dataSourceNames && dataSourceNames != 'none') {
+    names = dataSourceNames.split(',').collect { it.trim() }.findAll { it }
+    names.each { name ->
+        if (!(name ==~ /[A-Za-z_][A-Za-z0-9_]*/)) {
+            throw new IllegalArgumentException("Invalid dataSourceNames entry '" + name +
+                    "': each name must be a valid Java identifier (a letter or underscore followed by " +
+                    "letters, digits, or underscores) so it can form class names like " +
+                    "DatabaseAudit<Name>TestConfiguration.")
+        }
+    }
+}
+if (names) {
+    def configTemplate = new File(multiDir, "DatabaseAuditDsNameTokenTestConfiguration.java")
+    def itTemplate = new File(multiDir, "DatabaseAuditDsNameTokenIT.java")
+    def configBody = configTemplate.getText('UTF-8')
+    def itBody = itTemplate.getText('UTF-8')
+    names.each { name ->
+        def pascal = name.substring(0, 1).toUpperCase() + name.substring(1)
+        def camel = name.substring(0, 1).toLowerCase() + name.substring(1)
+        new File(multiDir, "DatabaseAudit${pascal}TestConfiguration.java")
+                .write(configBody.replace('DsNameToken', pascal).replace('dsNameToken', camel), 'UTF-8')
+        new File(multiDir, "DatabaseAudit${pascal}IT.java")
+                .write(itBody.replace('DsNameToken', pascal).replace('dsNameToken', camel), 'UTF-8')
+    }
+    configTemplate.delete()
+    itTemplate.delete()
+} else {
+    multiDir.deleteDir()
+}

archetype/src/main/resources/META-INF/maven/archetype-metadata.xml

@@ -43,6 +43,13 @@
     <requiredProperty key="disabledTests">
       <defaultValue>false</defaultValue>
     </requiredProperty>
+    <!-- Comma-separated datasource names (e.g. "Aurora,Reporting"). For each name, the post-generate script
+         expands the multi/ token templates into a DatabaseAudit<Name>TestConfiguration plus a
+         DatabaseAudit<Name>IT. Default 'none' (a non-empty sentinel, like parentClass, so the integration-test
+         mojo does not treat it as missing) generates the single-datasource suite only. -->
+    <requiredProperty key="dataSourceNames">
+      <defaultValue>none</defaultValue>
+    </requiredProperty>
   </requiredProperties>
 
   <fileSets>

archetype/src/main/resources/archetype-resources/src/test/java/multi/DatabaseAuditDsNameTokenIT.java

@@ -0,0 +1,44 @@
+package ${package}.multi;
+
+import org.junit.jupiter.api.Disabled;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.context.annotation.Import;
+
+#if($parentClass && $parentClass != '' && $parentClass != 'none')
+#set($simpleParentClass = $parentClass.replaceAll('.*\.', ''))
+import ${parentClass};
+#else
+import ${package}.AbstractDatabaseAuditIT;
+#end
+import io.github.databaseaudits.spring.boot.assertion.DatabaseAuditAssertions;
+
+/**
+ * Scaffold example that audits the DsNameToken datasource, using {@link DatabaseAuditDsNameTokenTestConfiguration}.
+ * The default audit beans (from the imported {@code DatabaseAuditTestConfiguration}) audit the primary datasource;
+ * the {@code @Qualifier} here selects the DsNameToken datasource's facade.
+ *
+ * <p>
+ * Generated {@code @Disabled} because it cannot run until you wire the DsNameToken datasource: fill in the
+ * {@code @Qualifier} bean names in {@link DatabaseAuditDsNameTokenTestConfiguration}, set the schema below, then
+ * remove {@code @Disabled}.
+ */
+@Disabled("Scaffold: wire the DsNameToken datasource and fill in the @Qualifiers in DatabaseAuditDsNameTokenTestConfiguration, then remove @Disabled.")
+@Import(DatabaseAuditDsNameTokenTestConfiguration.class)
+#if($parentClass && $parentClass != '' && $parentClass != 'none')
+public class DatabaseAuditDsNameTokenIT extends ${simpleParentClass} {
+#else
+public class DatabaseAuditDsNameTokenIT extends AbstractDatabaseAuditIT {
+#end
+    @Autowired
+    @Qualifier("dsNameTokenDatabaseAuditAssertions")
+    private DatabaseAuditAssertions dsNameTokenAudits;
+
+    @Test
+    void testDsNameTokenSchemaIsClean() {
+        // TODO: replace with the DsNameToken datasource's schema name.
+        dsNameTokenAudits.assertCatalogClean("${schemaName}");
+        dsNameTokenAudits.assertJpaClean();
+    }
+}

archetype/src/main/resources/archetype-resources/src/test/java/multi/DatabaseAuditDsNameTokenTestConfiguration.java

@@ -0,0 +1,64 @@
+package ${package}.multi;
+
+import javax.sql.DataSource;
+
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.boot.test.context.TestConfiguration;
+import org.springframework.context.annotation.Bean;
+
+import io.github.databaseaudits.capture.SqlCapturingStatementInspector;
+import io.github.databaseaudits.spring.boot.DatabaseAuditSuite;
+import io.github.databaseaudits.spring.boot.assertion.DatabaseAuditAssertions;
+import jakarta.persistence.EntityManagerFactory;
+
+/**
+ * Audits the DsNameToken datasource. The default {@code DatabaseAuditTestConfiguration} (imported by
+ * {@code AbstractDatabaseAuditIT}) audits the application's primary {@code DataSource} and
+ * {@code EntityManagerFactory}; this configuration audits the DsNameToken datasource, selected by
+ * {@code @Qualifier}.
+ *
+ * <p>
+ * To use it: replace the placeholder {@code @Qualifier} values with your DsNameToken {@code DataSource} and
+ * {@code EntityManagerFactory} bean names, {@code @Import} this class from a test, and inject the
+ * {@code dsNameTokenDatabaseAuditAssertions} bean (see {@code DatabaseAuditDsNameTokenIT}).
+ *
+ * <p>
+ * It is a {@code @TestConfiguration}, so it stays inert until imported: the placeholder qualifiers never resolve
+ * and the build still compiles. For the runtime (PostgreSQL-only) audits to see SQL, register
+ * {@code dsNameTokenSqlCapturer} as that {@code EntityManagerFactory}'s Hibernate {@code StatementInspector} where
+ * you build it, and connect that datasource with {@code preferQueryMode=simple}; otherwise call only
+ * {@code assertCatalogClean} and {@code assertJpaClean}.
+ */
+@TestConfiguration(proxyBeanMethods = false)
+public class DatabaseAuditDsNameTokenTestConfiguration {
+    /**
+     * The SQL capturer the DsNameToken datasource's runtime audits read. Must be the same instance registered as
+     * that {@code EntityManagerFactory}'s Hibernate {@code StatementInspector}.
+     *
+     * @return the DsNameToken datasource's SQL capturer.
+     */
+    @Bean
+    SqlCapturingStatementInspector dsNameTokenSqlCapturer() {
+        return new SqlCapturingStatementInspector();
+    }
+
+    /**
+     * Builds the audit assertions for the DsNameToken datasource. Replace the placeholder {@code @Qualifier}
+     * values with your own bean names.
+     *
+     * @param dataSource
+     *                                the DsNameToken datasource to audit.
+     * @param entityManagerFactory
+     *                                the DsNameToken entity-manager factory the JPA audit confirms.
+     * @param dsNameTokenSqlCapturer
+     *                                the DsNameToken datasource's SQL capturer.
+     * @return the DsNameToken datasource's assertions facade.
+     */
+    @Bean
+    DatabaseAuditAssertions dsNameTokenDatabaseAuditAssertions(
+            @Qualifier("dsNameTokenDataSource") DataSource dataSource,
+            @Qualifier("dsNameTokenEntityManagerFactory") EntityManagerFactory entityManagerFactory,
+            @Qualifier("dsNameTokenSqlCapturer") SqlCapturingStatementInspector dsNameTokenSqlCapturer) {
+        return new DatabaseAuditSuite(dataSource, entityManagerFactory, dsNameTokenSqlCapturer).assertions();
+    }
+}

archetype/src/test/java/io/github/databaseaudits/archetype/PostGenerateScriptTest.java

@@ -1,6 +1,7 @@
 package io.github.databaseaudits.archetype;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 import java.io.IOException;
 import java.io.InputStream;
@@ -16,10 +17,12 @@
 import groovy.lang.GroovyShell;
 
 /**
- * Verifies the archetype post-generate script behavior for the {@code tests-only} generation mode,
+ * Verifies the archetype post-generate script behavior: the {@code tests-only} generation mode —
  * particularly that {@code projectDirectory} is honored whether it arrives in {@code request.properties}
  * (the archetype integration-test mojo) or only as a JVM system property (the {@code archetype:generate}
- * command line, where {@code projectDirectory} is not a declared archetype property).
+ * command line, where {@code projectDirectory} is not a declared archetype property) — and that the
+ * {@code multi/} token templates expand into a {@code DatabaseAudit<Name>TestConfiguration} per
+ * {@code dataSourceNames} entry, or are removed when no names are given.
  */
 class PostGenerateScriptTest {
 
@@ -170,6 +173,67 @@ void testPostGenerate_TestsOnlyWithAbsoluteProjectDirectoryAsSystemProperty_Copi
                 .doesNotExist();
     }
 
+    @Test
+    void testPostGenerate_ProjectModeWithoutDataSourceNames_DeletesMultiTemplates()
+            throws Exception {
+        Path outputDir = tempDir.resolve("output");
+        setupGeneratedProject(outputDir, "demo", PACKAGE_PATH);
+        setupMultiTemplates(outputDir, "demo", PACKAGE_PATH);
+
+        runPostGenerateScriptInProjectMode(outputDir, "demo", "none");
+
+        assertThat(outputDir.resolve("demo/src/test/java/" + PACKAGE_PATH + "/multi").toFile())
+                .as("The multi/ templates must be deleted when dataSourceNames is 'none'.")
+                .doesNotExist();
+        assertThat(outputDir.resolve("demo/src/test/java/" + PACKAGE_PATH + "/catalog/ForeignKeyIndexAuditIT.java"))
+                .as("Audit IT files are kept in project mode.")
+                .exists();
+    }
+
+    @Test
+    void testPostGenerate_ProjectModeWithDataSourceNames_GeneratesNamedClassesPerDatasource()
+            throws Exception {
+        Path outputDir = tempDir.resolve("output");
+        setupGeneratedProject(outputDir, "demo", PACKAGE_PATH);
+        setupMultiTemplates(outputDir, "demo", PACKAGE_PATH);
+
+        runPostGenerateScriptInProjectMode(outputDir, "demo", "Aurora, Reporting");
+
+        Path multi = outputDir.resolve("demo/src/test/java/" + PACKAGE_PATH + "/multi");
+        assertThat(multi.resolve("DatabaseAuditAuroraTestConfiguration.java"))
+                .as("A config class is generated for each datasource name.").exists();
+        assertThat(multi.resolve("DatabaseAuditAuroraIT.java"))
+                .as("An IT is generated for each datasource name.").exists();
+        assertThat(multi.resolve("DatabaseAuditReportingTestConfiguration.java"))
+                .as("A config class is generated for each datasource name (whitespace is trimmed).").exists();
+        assertThat(multi.resolve("DatabaseAuditReportingIT.java"))
+                .as("An IT is generated for each datasource name.").exists();
+        assertThat(multi.resolve("DatabaseAuditDsNameTokenTestConfiguration.java").toFile())
+                .as("The token templates are removed after generation.").doesNotExist();
+        assertThat(Files.readString(multi.resolve("DatabaseAuditAuroraTestConfiguration.java")))
+                .as("Tokens are replaced with the datasource name throughout.")
+                .contains("class DatabaseAuditAuroraTestConfiguration", "auroraDataSource")
+                .doesNotContain("DsNameToken", "dsNameToken");
+        assertThat(Files.readString(multi.resolve("DatabaseAuditAuroraIT.java")))
+                .as("Tokens are replaced in the generated IT body too, not just its filename.")
+                .contains("class DatabaseAuditAuroraIT", "auroraDataSource")
+                .doesNotContain("DsNameToken", "dsNameToken");
+    }
+
+    @Test
+    void testPostGenerate_ProjectModeWithInvalidDataSourceName_FailsWithClearError()
+            throws Exception {
+        Path outputDir = tempDir.resolve("output");
+        setupGeneratedProject(outputDir, "demo", PACKAGE_PATH);
+        setupMultiTemplates(outputDir, "demo", PACKAGE_PATH);
+
+        assertThatThrownBy(() -> runPostGenerateScriptInProjectMode(outputDir, "demo",
+                "read-replica"))
+                .as("A datasource name that is not a valid Java identifier must fail generation, "
+                        + "not emit an uncompilable class.")
+                .hasMessageContaining("read-replica");
+    }
+
     private void setupGeneratedProject(Path outputDir, String artifactId, String packagePath)
             throws IOException {
         Path projectDir = outputDir.resolve(artifactId);
@@ -245,6 +309,33 @@ private void runPostGenerateScriptWithSystemProjectDirectory(Path outputDir, Str
         }
     }
 
+    private void setupMultiTemplates(Path outputDir, String artifactId, String packagePath)
+            throws IOException {
+        Path multiDir = outputDir.resolve(artifactId).resolve("src/test/java/" + packagePath + "/multi");
+        Files.createDirectories(multiDir);
+        Files.writeString(multiDir.resolve("DatabaseAuditDsNameTokenTestConfiguration.java"),
+                "class DatabaseAuditDsNameTokenTestConfiguration { String ds = \"dsNameTokenDataSource\"; }");
+        Files.writeString(multiDir.resolve("DatabaseAuditDsNameTokenIT.java"),
+                "class DatabaseAuditDsNameTokenIT { String ds = \"dsNameTokenDataSource\"; }");
+    }
+
+    /**
+     * Runs the post-generate script in {@code project} mode, where the only cleanup is the {@code parentClass}
+     * deletion and the {@code dataSourceNames} expansion. A {@code null} {@code dataSourceNames} omits the
+     * property entirely, mirroring no datasource names.
+     */
+    private void runPostGenerateScriptInProjectMode(Path outputDir, String artifactId, String dataSourceNames)
+            throws IOException {
+        Properties props = new Properties();
+        props.setProperty("generateMode", "project");
+        props.setProperty("parentClass", "none");
+        props.setProperty("package", PACKAGE);
+        if (dataSourceNames != null) {
+            props.setProperty("dataSourceNames", dataSourceNames);
+        }
+        evaluateScript(outputDir, artifactId, props, null);
+    }
+
     private void evaluateScript(Path outputDir, String artifactId, Properties props, String pwdOverride)
             throws IOException {
         String script;

archetype/src/test/resources/projects/disabled-tests/archetype.properties

@@ -10,3 +10,4 @@ springBootVersion=4.1.0
 generateMode=project
 parentClass=none
 disabledTests=true
+dataSourceNames=none

archetype/src/test/resources/projects/full/archetype.properties

@@ -10,3 +10,4 @@ springBootVersion=4.1.0
 generateMode=project
 parentClass=none
 disabledTests=false
+dataSourceNames=none

archetype/src/test/resources/projects/multi-datasource/archetype.properties

@@ -0,0 +1,13 @@
+groupId=com.example
+artifactId=archetype-it-multi-datasource
+version=1.0.0-SNAPSHOT
+package=com.example.demo
+schemaName=public
+schemaPropertyName=database.datasource.schema-name
+postgresImage=postgres:16
+databaseAuditsVersion=@project.version@
+springBootVersion=4.1.0
+generateMode=project
+parentClass=none
+disabledTests=true
+dataSourceNames=Aurora,Reporting

archetype/src/test/resources/projects/multi-datasource/goal.txt

@@ -0,0 +1 @@
+verify