Prerequisites

Your test context must supply:

• A DataSource bean (JDBC connection to your database).
• A JPA EntityManagerFactory (required by the JPA audit family).
• Spring Boot test infrastructure (typically @SpringBootTest).
• A schema-qualified JDBC URL with preferQueryMode=simple appended when targeting PostgreSQL (required by the runtime audit family — see PostgreSQL JDBC requirement: preferQueryMode=simple below).

Enabling the audits

Add @Import(DatabaseAuditTestConfiguration.class) to your test base class. This registers every audit bean, their collaborators, and the SQL-capturing StatementInspector with Hibernate in one step.

@SpringBootTest
@Import(DatabaseAuditTestConfiguration.class)
public abstract class AbstractDatabaseAuditIT {

    @Value("${database.datasource.schema-name}")
    protected String schema;

    @Autowired
    protected DatabaseAuditAssertions audits;
}

Audit families

For a full description of what each audit detects, finding format, and exclusion types, see the core audit reference.

audits.assertCatalogClean(schema);

audits.assertCatalogClean(schema, DatabaseAuditExcludes.builder()
    .primaryKeyTables(Set.of("some_legacy_table"))
    .foreignKeyIndexConstraints(Set.of("fk_known_unindexed"))
    .build());

audits.assertJpaClean();

# src/test/resources/application.properties (or application-test.properties)
spring.datasource.url=jdbc:postgresql://localhost:5432/mydb?preferQueryMode=simple

private static final PostgreSQLContainer<?> POSTGRES =
    new PostgreSQLContainer<>(DockerImageName.parse("postgres:16"));
static {
    POSTGRES.withUrlParam("preferQueryMode", "simple");  // must be before start()
    POSTGRES.start();
}

@Bean
DynamicPropertyRegistrar postgresProperties() {
    return registry -> registry.add("spring.datasource.url", POSTGRES::getJdbcUrl);
}

registry.add("spring.datasource.url", () -> POSTGRES.getJdbcUrl() + "?preferQueryMode=simple");

<!-- docker-maven-plugin: bind random host port to ${pg.port} -->
<image>
    <name>postgres:16</name>
    <run>
        <ports>
            <port>pg.port:5432</port>
        </ports>
    </run>
</image>

<!-- maven-failsafe-plugin: pass the assembled URL as a JVM system property -->
<systemPropertyVariables>
    <spring.datasource.url>
        jdbc:postgresql://localhost:${pg.port}/mydb?preferQueryMode=simple
    </spring.datasource.url>
</systemPropertyVariables>

// Runs first — exercises your repositories to populate the SQL capture buffer.
@Order(Integer.MIN_VALUE)
class RepositoryWorkloadIT extends AbstractDatabaseAuditIT {

    @Autowired
    private MyRepository myRepository;

    @Test
    void primeRepositoryWorkload() {
        myRepository.findAll();
        myRepository.findById(1L);
        // ... other calls to exercise
    }
}

// Runs last — checks the captured SQL.
@Order(Integer.MAX_VALUE)
class WhereClauseIndexAuditIT extends AbstractDatabaseAuditIT {

    @Test
    void assertWhereClauseIndexClean() {
        audits.assertRuntimeClean();
    }
}

junit.jupiter.testclass.order.default=org.junit.jupiter.api.ClassOrderer$OrderAnnotation

// Runs last — after the workload test primes the SQL capture.
@Order(Integer.MAX_VALUE)
class AllAuditsIT extends AbstractDatabaseAuditIT {

    @Test
    void assertAllClean() {
        audits.assertAllClean(schema);
    }
}

audits.assertAllClean(schema, DatabaseAuditExcludes.builder()
    .primaryKeyTables(Set.of("legacy_table_no_pk"))
    .planRelations(Set.of("small_lookup_table"))
    .build());

Using individual assertion beans

Each audit has a dedicated assertion bean you can @Autowired directly for fine-grained control:

@Autowired
private ForeignKeyIndexAuditAssertion foreignKeyIndexAuditAssertion;

@Autowired
private WhereClauseIndexAuditAssertion whereClauseIndexAuditAssertion;

@Test
void assertForeignKeyIndexClean() {
    foreignKeyIndexAuditAssertion.assertClean(schema, Set.of("fk_known_unindexed"));
}

@Test
@Order(Integer.MAX_VALUE)
void assertWhereClauseIndexClean() {
    whereClauseIndexAuditAssertion.assertClean(
        Set.of("large_lookup_table"),
        List.of("SELECT * FROM audit_log")
    );
}

See Exclusions for the full exclusion API reference.

Multiple datasources

DatabaseAuditTestConfiguration audits one datasource — resolved by type from the context’s DataSource and EntityManagerFactory. Spring picks the single, @Primary, or conventionally-named (dataSource/entityManagerFactory) candidate, so importing the stock config audits that datasource out of the box.

With several peer datasources that autowiring can’t disambiguate (no @Primary, custom bean names), by-type resolution fails fast with Spring’s "expected single matching bean but found 2". To audit such a datasource, wire it by name instead, one target per generated suite.

In short: DatabaseAuditTestConfiguration audits the primary datasource by type; a per-datasource DatabaseAudit<Name>TestConfiguration audits a named datasource by name. The stock class is not obsolete — it stays the entry point for any single or @Primary datasource; the per-datasource class is what you add for a non-primary peer.

Give the datasource a @TestConfiguration that resolves its beans by @Qualifier, builds a io.github.databaseaudits.spring.boot.DatabaseAuditSuite — a plain factory that wires the whole audit graph for a given (DataSource, EntityManagerFactory) pair — and registers every *AuditAssertion from it. It mirrors the stock config, but by name. Name it after the datasource, e.g. for a Reporting datasource:

@TestConfiguration(proxyBeanMethods = false)
public class DatabaseAuditReportingTestConfiguration {

    @Bean
    SqlCapturingStatementInspector reportingSqlCapturer() {
        return new SqlCapturingStatementInspector();
    }

    @Bean  // sets reportingSqlCapturer as reportingEntityManagerFactory's StatementInspector before it is built
    static SqlCapturerRegisteringPostProcessor reportingSqlCapturerRegistrar() {
        return new SqlCapturerRegisteringPostProcessor("reportingEntityManagerFactory", "reportingSqlCapturer");
    }

    @Bean
    DatabaseAuditSuite reportingDatabaseAuditSuite(
            @Qualifier("reportingDataSource") DataSource dataSource,
            @Qualifier("reportingEntityManagerFactory") EntityManagerFactory entityManagerFactory,
            @Qualifier("reportingSqlCapturer") SqlCapturingStatementInspector reportingSqlCapturer) {
        return new DatabaseAuditSuite(dataSource, entityManagerFactory, reportingSqlCapturer);
    }

    @Bean
    AuditAssertionRegistrar reportingAuditAssertionRegistrar(
            @Qualifier("reportingDatabaseAuditSuite") DatabaseAuditSuite suite) {
        return new AuditAssertionRegistrar(suite, "reporting", false);
    }
}

One AuditAssertionRegistrar publishes every *AuditAssertion the suite wires — and the DatabaseAuditAssertions facade — as a bean, so this config stays in step with the audit roster automatically; there is no longer a @Bean method per audit to keep in sync. The "reporting" prefix names those beans reportingForeignKeyIndexAuditAssertion, reportingDatabaseAuditAssertions, and so on, so they never collide with the primary datasource’s audit beans; false marks them non-primary, so an unqualified by-type injection still resolves to the primary datasource’s assertions. Your ITs still @Autowired each assertion by type. This is exactly what the archetype-generated DatabaseAudit<Name>TestConfiguration does.

Import that config once on your test base class — not on each IT. A per-test @Import layered on a base that already declares its context via @ContextConfiguration breaks Spring’s context resolution; putting it on the base avoids that. Every audit IT extends the base and injects its assertion bean, exactly like the single-datasource suite:

@SpringBootTest
@Import(DatabaseAuditReportingTestConfiguration.class)
public abstract class AbstractDatabaseAuditIT {
}

class ForeignKeyIndexAuditIT extends AbstractDatabaseAuditIT {

    @Autowired
    private ForeignKeyIndexAuditAssertion foreignKeyIndexAuditAssertion;

    @Value("${database.datasource.schema-name}")
    private String schema;

    @Test
    void everyForeignKeyHasSupportingIndex() {
        foreignKeyIndexAuditAssertion.assertClean(schema);
    }
}

The archetype generates all of this — the DatabaseAudit<Name>TestConfiguration (its capturer, the qualified suite, and every *AuditAssertion bean) and the audit ITs that @Import it — when you pass -DdataSourceName=Reporting -DdataSourceBeanName=reportingDataSource -DentityManagerFactoryBeanName=reportingEntityManagerFactory. To audit several datasources, generate once per datasource into its own package; each target audits its own -DschemaPropertyName, so datasources with different schemas are handled naturally.

Consolidated findings report

Every audit failure is also collected into a single report file, written automatically at the end of the test run by a JUnit TestExecutionListener shipped in the integration jar and auto-registered via META-INF/services — no setup and no console scraping. The listener is inert when the run is clean: it writes nothing unless there are findings, so unrelated test runs are unaffected.

The report groups findings by audit family and audit, reproducing each finding’s message, and can additionally emit a remediation for each finding — raw SQL DDL or a Liquibase changeset.

The report is populated from per-audit assertion failures — the per-audit ITs the archetype generates, or any test that calls an individual *AuditAssertion bean. The DatabaseAuditAssertions facade (assertAllClean / assertCatalogClean / …) aggregates its failures into one combined AssertionError, which the report does not itemize; prefer the per-audit assertions when you want the consolidated report.

# src/test/resources/junit-platform.properties
database-audits.report.format=asciidoc
database-audits.report.fix-format=liquibase-xml
database-audits.report.fix-placement=both