feat(spring): One datasource in generated tests, not many

The handling of multiple datasources per database integration module
tests is rare and a cumbersome design.  When encountering this, instead,
configure the correct single datasource for the tests or generate
separate tests for each datasource if more than one is valid.

Replace the archetype's multi-datasource generation (multi/ token
expansion, aggregator, @ParameterizedTest) with one specified
datasource, named by dataSourceName / dataSourceBeanName /
entityManagerFactoryBeanName and resolved by @qualifier; regenerate per
datasource to cover several. Also:

- Import the generated DatabaseAudit<Name>TestConfiguration once on the
  base test class, not on each generated IT, so it cannot clash with a
  consumer base that declares its context via @ContextConfiguration.
- Auto-wire runtime SQL capture for the named datasource: the generated
  config registers a SqlCapturerRegisteringPostProcessor that sets its
  capturer as that EntityManagerFactory's Hibernate StatementInspector
  before the factory is built, so the plan-based audits run with no
  change to the application's own datasource configuration.
- Drop SingleDataSourceCondition: the stock DatabaseAuditTestConfiguration
  resolves the DataSource/EntityManagerFactory by type and fails fast on
  genuinely ambiguous peer datasources instead of backing off silently.
- Print the remaining manual steps after generation, and update the usage
  guide, CLAUDE.md, and archetype docs to match.

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

Author: jeffjensen

CLAUDE.md

@@ -63,13 +63,27 @@ one suite from the context's primary `DataSource`/`EntityManagerFactory` and reg
 `@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.
+To audit a datasource in an application that configures **several peer datasources** (with no `@Primary`
+`DataSource`/`EntityManagerFactory`), the archetype generates tests that target **one specified datasource**,
+resolved **by name** rather than by type. Pass `-DdataSourceName=Reporting -DdataSourceBeanName=reportingDataSource
+-DentityManagerFactoryBeanName=reportingEntityManagerFactory`: `archetype-post-generate.groovy` expands the
+`DsNameToken` config token template into a `DatabaseAuditReportingTestConfiguration` — a `@Qualifier`-based mirror of
+the stock config (its own capturer, a `DatabaseAuditSuite` built from the two named beans, and every
+`*AuditAssertion` bean) — and the generated `AbstractDatabaseAuditIT` `@Import`s it (the audit ITs carry no
+`@Import` of their own; they just extend that base, so a per-test `@Import` can't clash with a consumer base that
+declares its context via `@ContextConfiguration`). In this **targeted** mode `AbstractDatabaseAuditIT` imports the
+per-datasource config instead of the default `DatabaseAuditTestConfiguration`; when a `parentClass` is given
+`AbstractDatabaseAuditIT` is not generated, so `archetype-post-generate.groovy` prints an instruction telling the
+consumer to add that `@Import` to their own base class. To audit more than one datasource, generate once per
+datasource into its own package. `AbstractDatabaseAuditIT` branches on a `#set($targeted ...)` flag for which config
+it imports; each IT's `*AuditAssertion` injection is unchanged in both modes. Because the generated token config mirrors the stock config's bean list,
+adding/removing a core audit now touches it too — the same lockstep the stock config follows. `dataSourceName`,
+`dataSourceBeanName`, and `entityManagerFactoryBeanName` are declared properties, default `none`.
+
+The stock `DatabaseAuditTestConfiguration` resolves the `DataSource`/`EntityManagerFactory` **by type** — Spring
+picks the single, `@Primary`, or conventionally-named (`dataSource`/`entityManagerFactory`) candidate. Several peer
+datasources it can't disambiguate make importing the config fail fast with `expected single matching bean but found
+2`; audit such a datasource by name via the targeted mode above instead.
 
 ### Platform detection and the PostgreSQL-only plan audits
 
@@ -88,6 +102,15 @@ Hibernate's `StatementInspector` and the instance injected into the audits — t
 the *bean object*, not its class name. Registering by class name spawns a second capturer Hibernate fills but the
 audits never read, silently producing empty captures. Preserve this when editing the config.
 
+The stock config wires the capturer onto the auto-configured **primary** `EntityManagerFactory` via a
+`HibernatePropertiesCustomizer`. That customizer reaches only the primary factory, so a **by-name (peer)**
+datasource can't use it: the generated `DatabaseAudit<Name>TestConfiguration` instead registers a
+`SqlCapturerRegisteringPostProcessor` (`…/spring/boot/`), a `BeanPostProcessor` that puts the same capturer instance
+under `JdbcSettings.STATEMENT_INSPECTOR` on the named `LocalContainerEntityManagerFactoryBean` **before Hibernate
+builds it** (the inspector is a build-time setting — it can't be attached to an already-built factory). This wires
+peer-datasource runtime capture with no change to the application's own factory configuration; it is the one bean
+the token config adds beyond the stock config's list.
+
 ### The reusable assertion API — how consumers consume the audits
 
 The integration's published surface is not just the wiring. `…/spring/boot/assertion/` holds one

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

@@ -64,38 +64,60 @@ 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.")
-        }
+// When dataSourceName is set (not 'none'), the application configures several peer datasources with no @Primary:
+// expand the token config template into a DatabaseAudit<Name>TestConfiguration that resolves this datasource's
+// beans by @Qualifier (each audit IT @Imports it), then delete the token template. With no dataSourceName, just
+// remove the token template — the ITs import the stock DatabaseAuditTestConfiguration instead.
+def dataSourceName = request.properties.getProperty('dataSourceName', 'none')
+def configTemplate = new File(destRoot, "src/test/java/${packagePath}/DatabaseAuditDsNameTokenTestConfiguration.java")
+if (dataSourceName && dataSourceName != 'none') {
+    if (!(dataSourceName ==~ /[A-Za-z_][A-Za-z0-9_]*/)) {
+        throw new IllegalArgumentException("Invalid dataSourceName '" + dataSourceName +
+                "': it must be a valid Java identifier (a letter or underscore followed by letters, digits, or " +
+                "underscores) so it can form the class name 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')
+    def dataSourceBeanName = request.properties.getProperty('dataSourceBeanName', 'none')
+    def entityManagerFactoryBeanName = request.properties.getProperty('entityManagerFactoryBeanName', 'none')
+    if (!dataSourceBeanName || dataSourceBeanName == 'none'
+            || !entityManagerFactoryBeanName || entityManagerFactoryBeanName == 'none') {
+        throw new IllegalArgumentException("dataSourceName '" + dataSourceName +
+                "' requires both dataSourceBeanName and entityManagerFactoryBeanName, naming the DataSource and " +
+                "EntityManagerFactory beans the generated config resolves by @Qualifier.")
     }
+    def pascal = dataSourceName.substring(0, 1).toUpperCase() + dataSourceName.substring(1)
+    def camel = dataSourceName.substring(0, 1).toLowerCase() + dataSourceName.substring(1)
+    def configBody = configTemplate.getText('UTF-8')
+    new File(configTemplate.parentFile, "DatabaseAudit${pascal}TestConfiguration.java")
+            .write(configBody.replace('DsNameToken', pascal).replace('dsNameToken', camel), 'UTF-8')
     configTemplate.delete()
-    itTemplate.delete()
 } else {
-    multiDir.deleteDir()
+    configTemplate.delete()
+}
+
+// Remaining manual steps for the consumer, printed to the archetype:generate console output. The audit ITs no
+// longer carry @Import themselves; the config is imported once on the base class (generated or user-specified).
+def schemaProp = request.properties.getProperty('schemaPropertyName', 'database.datasource.schema-name')
+def site = 'https://database-audits.github.io/spring-boot-integration'
+println ''
+println '=================================================================================='
+println ' database-audits: generation complete. Remaining manual steps:'
+println '=================================================================================='
+if (dataSourceName && dataSourceName != 'none') {
+    def pascal = dataSourceName.substring(0, 1).toUpperCase() + dataSourceName.substring(1)
+    def configClass = "DatabaseAudit${pascal}TestConfiguration"
+    if (parentClass && parentClass != 'none') {
+        println " * Add @Import(${configClass}.class) to your base test class ${parentClass}"
+        println "   (or list ${configClass}.class in its @ContextConfiguration(classes = { ... }))."
+    }
+    println " * Add preferQueryMode=simple to the ${dataSourceName} datasource's JDBC URL (plan-based PostgreSQL"
+    println "   runtime audits only)."
+    println " * Guide: ${site}/usage.html#_multiple_datasources"
+} else if (parentClass && parentClass != 'none') {
+    println " * Add @Import(DatabaseAuditTestConfiguration.class) to your base test class ${parentClass}"
+    println "   (or list it in its @ContextConfiguration(classes = { ... }))."
+    println " * Guide: ${site}/usage.html"
+} else {
+    println " * Guide: ${site}/usage.html"
 }
+println " * Ensure ${schemaProp} is set to the schema the catalog audits scan."
+println '=================================================================================='

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

@@ -43,11 +43,24 @@
     <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">
+    <!-- The datasource to audit when the application configures several peer datasources with no @Primary.
+         When set (not 'none'), the post-generate script expands the token config template into a
+         DatabaseAudit<Name>TestConfiguration that resolves this datasource's beans by @Qualifier, and each audit IT
+         @Imports it. The value labels the generated config class (Pascal-cased) and its SQL capturer bean
+         (camel-cased), so it must be a valid Java identifier. Default 'none' (a non-empty sentinel, like
+         parentClass, so the integration-test mojo does not treat it as missing) generates the single-datasource
+         suite that imports the stock DatabaseAuditTestConfiguration. -->
+    <requiredProperty key="dataSourceName">
+      <defaultValue>none</defaultValue>
+    </requiredProperty>
+    <!-- The DataSource bean name the generated per-datasource config resolves by @Qualifier. Required (not 'none')
+         when dataSourceName is set; ignored otherwise. -->
+    <requiredProperty key="dataSourceBeanName">
+      <defaultValue>none</defaultValue>
+    </requiredProperty>
+    <!-- The EntityManagerFactory bean name the generated per-datasource config resolves by @Qualifier. Required
+         (not 'none') when dataSourceName is set; ignored otherwise. -->
+    <requiredProperty key="entityManagerFactoryBeanName">
       <defaultValue>none</defaultValue>
     </requiredProperty>
   </requiredProperties>

archetype/src/main/resources/archetype-resources/src/test/java/AbstractDatabaseAuditIT.java

@@ -1,10 +1,31 @@
 package ${package};
 
+#set($targeted = $dataSourceName && $dataSourceName != '' && $dataSourceName != 'none')
+#if($targeted)
+#set($dsPascal = "${dataSourceName.substring(0,1).toUpperCase()}${dataSourceName.substring(1)}")
+#end
 import org.springframework.boot.test.context.SpringBootTest;
 import org.springframework.context.annotation.Import;
 
+#if($targeted)
+import ${package}.DatabaseAudit${dsPascal}TestConfiguration;
+#else
 import io.github.databaseaudits.spring.boot.DatabaseAuditTestConfiguration;
+#end
 
+#if($targeted)
+/**
+ * Base class for the audit integration tests. It boots a Spring Boot test context and {@code @Import}s the generated
+ * per-datasource {@code DatabaseAudit<Name>TestConfiguration}, which resolves that datasource's beans by name and
+ * registers every audit bean; every audit IT extends this class and inherits that import. It deliberately does not
+ * import {@code DatabaseAuditTestConfiguration}: that configuration resolves the
+ * {@code DataSource}/{@code EntityManagerFactory} by type, which cannot pick one among several peer datasources.
+ *
+ * <p>
+ * It carries no database or container wiring of its own, so it works unchanged against any application. Point it at
+ * your own application and datasource to audit your real schema.
+ */
+#else
 /**
  * Base class for the audit integration tests. It boots a Spring Boot test context and imports
  * {@link DatabaseAuditTestConfiguration}, which registers every audit bean and wires the shared SQL capturer.
@@ -14,7 +35,12 @@
  * {@code @SpringBootApplication} and {@code DataSource} (a Testcontainers PostgreSQL) supply the database for the
  * audit ITs that extend it. Point it at your own application and {@code DataSource} to audit your real schema.
  */
+#end
 @SpringBootTest
+#if($targeted)
+@Import(DatabaseAudit${dsPascal}TestConfiguration.class)
+#else
 @Import(DatabaseAuditTestConfiguration.class)
+#end
 public abstract class AbstractDatabaseAuditIT {
 }