feat(spring): Validate JPA mappings via core audit, not ddl-auto=validate

The generated SchemaEntityValidationAuditIT no longer overrides
ddl-auto=validate: the context boots under the default ddl-auto=none and
SchemaEntityValidationAudit validates every entity mapping against the live
schema, reporting all mismatches in one run instead of Hibernate's fail-fast
startup validation that surfaces them one at a time.

* Wire the audit via SchemaEntityValidationAudit.forEntityManagerFactory
* Bump database-audits-core to 1.2.0
* Refresh the assertion message, archetype template, and audit docs

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

Author: jeffjensen

CLAUDE.md

@@ -113,8 +113,9 @@ assertion API; these ITs show how to wire and call it. They mirror core's three
   run *after* the SQL is captured. What actually enforces order is the priming test `RepositoryWorkloadIT`
   (`@Order(Integer.MIN_VALUE)`, runs first, via `junit-platform.properties` enabling
   `ClassOrderer$OrderAnnotation`). **All example classes must use JUnit's `@Order`, not Spring's.**
-- The JPA example sets `@TestPropertySource(properties = "spring.jpa.hibernate.ddl-auto=validate")`: the real check is
-  Hibernate's startup schema validation; reaching the test means it passed.
+- The JPA example runs under the default `ddl-auto=none`: `SchemaEntityValidationAudit` walks Hibernate's entity
+  mappings against the live schema and reports every mismatch in one run, instead of relying on Hibernate's
+  fail-fast `ddl-auto=validate` startup check (which aborts on the first mismatch).
 - Most show `EXCLUDED_*` exclusion constants (relations, SQL fragments, columns, indexes, statements) — the
   intended way for consumers to suppress known/intentional violations instead of weakening the audit.
   `ForeignKeyIndexAuditIT` and `PrimaryKeyPresenceAuditIT` call the no-exclusion overload directly.

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

@@ -38,7 +38,7 @@
     </requiredProperty>
     <!-- When 'true', every generated test is annotated with JUnit's @Disabled, so the suite is generated and
          compiles but does not run. SchemaEntityValidationAuditIT is annotated on the class (not the method) so
-         its ddl-auto=validate Spring context never loads. Default 'false' runs the audits. Useful for scaffolding
+         its Spring context never loads. Default 'false' runs the audits. Useful for scaffolding
          the suite into a project that does not pass it yet, then enabling audits one at a time. -->
     <requiredProperty key="disabledTests">
       <defaultValue>false</defaultValue>

archetype/src/main/resources/archetype-resources/src/test/java/jpa/SchemaEntityValidationAuditIT.java

@@ -5,7 +5,6 @@
 #end
 import org.junit.jupiter.api.Test;
 import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.test.context.TestPropertySource;
 
 #if($parentClass && $parentClass != '' && $parentClass != 'none')
 #set($simpleParentClass = $parentClass.replaceAll('.*\.', ''))
@@ -16,10 +15,10 @@
 import io.github.databaseaudits.spring.boot.assertion.SchemaEntityValidationAuditAssertion;
 
 /**
- * The {@code ddl-auto=validate} setting makes Hibernate validate entity↔schema at startup; reaching the test means
- * it passed.
+ * Validates that every JPA entity mapping matches the schema, reporting all mismatches in one run. It runs under
+ * the default {@code ddl-auto=none}: Hibernate's own {@code validate} fails fast on the first mismatch and aborts
+ * startup, so this audit walks the mappings against the live schema itself instead.
  */
-@TestPropertySource(properties = "spring.jpa.hibernate.ddl-auto=validate")
 #if($disabledTests == 'true')
 @Disabled("Generated as disabled; remove @Disabled to enable")
 #end

archetype/src/main/resources/archetype-resources/src/test/resources/application.properties

@@ -1,7 +1,7 @@
 # Demo harness configuration that lets the audit ITs run standalone.
 # The DataSource (URL with preferQueryMode=simple, username, password) is supplied by DemoPostgresTestConfig via a
-# DynamicPropertyRegistrar. Liquibase owns the schema; Hibernate does not (ddl-auto=none) except the JPA example,
-# which overrides ddl-auto=validate to assert entity/schema agreement.
+# DynamicPropertyRegistrar. Liquibase owns the schema; Hibernate does not (ddl-auto=none) — the JPA example audit
+# validates entity/schema agreement itself rather than relying on Hibernate's fail-fast startup validation.
 spring.jpa.open-in-view=false
 spring.jpa.hibernate.ddl-auto=none
 spring.liquibase.change-log=classpath:db/changelog/db.changelog-master.xml

integration/pom.xml

@@ -19,7 +19,7 @@
   </description>
 
   <properties>
-    <database-audits-core.version>1.1.0</database-audits-core.version>
+    <database-audits-core.version>1.2.0</database-audits-core.version>
   </properties>
 
   <developers>

integration/src/main/java/io/github/databaseaudits/spring/boot/DatabaseAuditSuite.java

@@ -75,8 +75,9 @@ public class DatabaseAuditSuite {
      *                                runtime audits inspect; its platform is
      *                                auto-detected from its metadata.
      * @param entityManagerFactory
-     *                                the entity-manager factory whose Hibernate
-     *                                startup validation the JPA audit confirms.
+     *                                the entity-manager factory whose entity
+     *                                mappings the JPA audit validates against the
+     *                                schema.
      * @param sqlCapturer
      *                                the SQL capturer the runtime audits read;
      *                                must be the same instance registered as the
@@ -110,7 +111,8 @@ public DatabaseAuditSuite(final DataSource dataSource,
                 new RedundantIndexAudit(indexCatalog));
         this.schemaEntityValidationAuditAssertion =
                 new SchemaEntityValidationAuditAssertion(
-                        new SchemaEntityValidationAudit(entityManagerFactory));
+                        SchemaEntityValidationAudit.forEntityManagerFactory(
+                                entityManagerFactory, dataSource));
         this.joinIndexAuditAssertion = new JoinIndexAuditAssertion(
                 new JoinIndexAudit(queryPlanExplainer, sqlCapturer));
         this.orderByIndexAuditAssertion = new OrderByIndexAuditAssertion(

integration/src/main/java/io/github/databaseaudits/spring/boot/DatabaseAuditTestConfiguration.java

@@ -92,8 +92,9 @@ HibernatePropertiesCustomizer sqlCaptureHibernatePropertiesCustomizer(
      * @param dataSource
      *                                the primary datasource to audit.
      * @param entityManagerFactory
-     *                                the primary entity-manager factory the JPA
-     *                                audit confirms.
+     *                                the primary entity-manager factory whose
+     *                                mappings the JPA audit validates against the
+     *                                schema.
      * @param sqlCapturer
      *                                the shared SQL capturer the runtime audits
      *                                read.

integration/src/main/java/io/github/databaseaudits/spring/boot/assertion/SchemaEntityValidationAuditAssertion.java

@@ -1,5 +1,7 @@
 package io.github.databaseaudits.spring.boot.assertion;
 
+import java.util.Set;
+
 import io.github.databaseaudits.audit.jpa.SchemaEntityValidationAudit;
 
 /**
@@ -9,8 +11,8 @@
 public class SchemaEntityValidationAuditAssertion
         extends AbstractAuditAssertion {
     private static final String MESSAGE =
-            "JPA entity mappings must match the schema — the EntityManagerFactory must be built under "
-                    + "ddl-auto=validate (its startup validation is the real check).";
+            "JPA entity mappings do not match the schema; reconcile each mapping with the schema "
+                    + "(whichever drifted):";
 
     private final SchemaEntityValidationAudit audit;
 
@@ -31,4 +33,19 @@ public SchemaEntityValidationAuditAssertion(
     public void assertClean() {
         failOnViolations(MESSAGE, audit.audit());
     }
+
+    /**
+     * Asserts that the JPA entity mappings match the schema, ignoring the
+     * excluded relations.
+     *
+     * @param excludedRelations
+     *                              relations to skip, each a table name or a
+     *                              {@code table.column} pair — optionally
+     *                              schema-qualified ({@code schema.table} or
+     *                              {@code schema.table.column}) — matched
+     *                              case-insensitively.
+     */
+    public void assertClean(final String... excludedRelations) {
+        failOnViolations(MESSAGE, audit.audit(Set.of(excludedRelations)));
+    }
 }

integration/src/site/asciidoc/archetype.adoc

@@ -139,7 +139,7 @@ Pass only the ones that differ.
 | `disabledTests`
 | `false`
 | both
-| When `true`, annotates every generated test with JUnit's `@Disabled`, so the suite is generated and compiles but does not run. (`SchemaEntityValidationAuditIT` is annotated on the class rather than the method, so its `ddl-auto=validate` context never loads.) Useful for scaffolding the audits into a project that does not pass them yet — remove the `@Disabled` annotations to enable audits one at a time.
+| When `true`, annotates every generated test with JUnit's `@Disabled`, so the suite is generated and compiles but does not run. (`SchemaEntityValidationAuditIT` is annotated on the class rather than the method, so its Spring context never loads.) Useful for scaffolding the audits into a project that does not pass them yet — remove the `@Disabled` annotations to enable audits one at a time.
 
 | `dataSourceNames`
 | `none`
@@ -258,8 +258,8 @@ The generated tests compile against your existing Spring Boot test context. Run
 * Generated classes are pure Java with no Lombok. Dependencies are JUnit Jupiter, Spring Boot test, and this
   integration artifact only.
 * `@Order` annotations use JUnit's `org.junit.jupiter.api.Order`, not Spring's.
-* `SchemaEntityValidationAuditIT` sets `@TestPropertySource(properties = "spring.jpa.hibernate.ddl-auto=validate")`;
-  reaching the test body means Hibernate's startup validation passed.
+* `SchemaEntityValidationAuditIT` validates Hibernate's entity mappings against the live schema and reports every
+  mismatch in one run; it runs under the default `ddl-auto=none`, not Hibernate's fail-fast `ddl-auto=validate`.
 * Each catalog IT uses constants (e.g., `EXCLUDED_TABLES`, `EXCLUDED_CONSTRAINTS`) to name known/intentional
   exclusions. `ForeignKeyIndexAuditIT` and `PrimaryKeyPresenceAuditIT` call the no-exclusion overload directly
   to show that pattern as well.

integration/src/site/asciidoc/audits.adoc

@@ -62,14 +62,13 @@ void assertForeignKeysIndexed() {
 
 | `SchemaEntityValidationAudit`
 | `SchemaEntityValidationAuditAssertion`
-| None. Set `spring.jpa.hibernate.ddl-auto=validate` so Hibernate validates the schema at `@SpringBootTest` startup; reaching `assertClean()` confirms that validation passed.
+| None. The audit walks Hibernate's entity mappings against the live schema and reports every mismatch (missing table, missing column, incompatible column type) in one run. Run under the default `ddl-auto=none`; do not set `ddl-auto=validate`, whose fail-fast startup check aborts the context on the first mismatch.
 |===
 
 === JPA audit example
 
 [source,java]
 ----
-@TestPropertySource(properties = "spring.jpa.hibernate.ddl-auto=validate")
 class SchemaEntityValidationAuditIT extends AbstractDatabaseAuditIT {
 
     @Autowired