Configuration Reference¶

Choose the result you need before changing global settings:

Choose Your Workflow provides the recipes. Rule profiles and finding thresholds below configure supporting analysis; they do not change explicit query budgets or snapshot count contracts.

QueryAudit can be configured at three levels. When multiple levels conflict, the most specific one wins:

method-level @QueryAudit  >  class-level @QueryAudit  >  application.yml  >  built-in defaults

application.yml Properties¶

All properties are optional. The table below lists every supported key under the query-audit prefix.

Full Example¶

query-audit:
  enabled: true
  fail-on-detection: true
  n-plus-one:
    threshold: 3
  offset-pagination:
    threshold: 1000
  or-clause:
    threshold: 3
  large-in-list:
    threshold: 100
  too-many-joins:
    threshold: 5
  excessive-column:
    threshold: 15
  repeated-insert:
    threshold: 3
  repeated-update:
    threshold: 3
    exclude-tables: ["temp_*", "*_temp", "tmp_*", "*_tmp", "staging_*", "*_staging"]
  write-amplification:
    threshold: 6
  slow-query:
    warning-ms: 500
    error-ms: 3000
  disabled-rules:
    - "select-all"
  severity-overrides:
    unbounded-result-set: ERROR
  suppress-patterns:
    - "select-all"
    - "missing-where-index:config.key"
  suppress-queries:
    - "SELECT 1"
  baseline-path: ""
  auto-open-report: false
  max-queries: 10000
  report:
    format: console
    output-dir: build/reports/query-audit
    show-info: true

Rule Profiles¶

Since 0.7.0, omitted or blank profile settings select recommended, which runs only the call-site N+1 rule among built-in rules. Choose minimal or strict to add index, write, and SQL style checks:

query-audit:
  profile: recommended
  enabled-rules:
    - update-without-where   # add one rule to the profile

Precedence: disabled-rules > enabled-rules > profile tier.

recommended and minimal are allow-lists over built-in rules, so a new built-in rule stays off until it is added explicitly. recommended never filters custom finding kinds from AuditRule extensions. Legacy DetectionRule extensions report built-in issue types and follow the profile like built-in rules; enable their codes with enabled-rules. External rules registered via ServiceLoader without a rule code are never filtered by profiles.

The N+1 rule groups captured SELECT statements by normalized SQL and the full application call stack, ignoring proxy, reflection, and framework frames. Three executions from one call site that bind different values report a confirmed n-plus-one finding; n-plus-one.threshold changes the count. A query with a multi-placeholder IN list is a batched fetch and a query with OFFSET reads the next page; neither counts. Executions that all bind the same values repeat one lookup and are reported as INFO, which does not fail the test. Hibernate lazy-load events are reported as INFO n-plus-one findings that name the association; they explain a finding but never confirm one on their own.

Migrating from 0.6.x to 0.7¶

If you did not configure a profile, upgrading reduces the active built-in rules to n-plus-one. Set profile: strict to keep every rule, or list the rules you enforce in enabled-rules. Hibernate lazy-load N+1 findings move from ERROR to INFO; the confirmed finding now comes from a SELECT repeated with different values at one call site, so one batch fetch no longer fails a test.

SQL from other threads still counts toward a test that runs alone, as in 0.6. During parallel audits it makes the run INCONCLUSIVE. Name the pools that tests hand work to in await-executors so each test waits for its own background work.

Setting names now follow one rule. The earlier system property names keep working, so existing builds need no change; the Gradle bridge in the CI guide forwards the new names without a per-setting map.

Migrating from 0.5.x to 0.6.0¶

If you did not configure a profile, upgrading changes the active rules from strict to recommended. The profile excludes these 21 rule codes:

count-instead-of-exists already required a separate opt-in in 0.5.x. With recommended, it also needs an entry in enabled-rules. The other listed rules now need an explicit profile or rule override to run.

To retain the previous rule selection in Spring:

query-audit:
  profile: strict

For direct core use, select it on the builder:

QueryAuditConfig config = QueryAuditConfig.builder()
    .ruleProfile(RuleProfile.STRICT)
    .build();

For plain JUnit, set -DqueryAudit.profile=strict on the test JVM. In Gradle, configure tasks.withType(Test).configureEach { systemProperty 'queryAudit.profile', 'strict' }; with Maven Surefire, use mvn test -DqueryAudit.profile=strict. This system property also overrides Spring's profile for the JUnit audit. Omitted values preserve Spring configuration; blank values select recommended.

Explicit strict, recommended, and minimal retain their rule selections. You can also keep recommended and re-enable selected rules with enabled-rules. Query budgets and snapshot contracts still run independently of the profile. Re-record a comparison reference after changing profiles; reports produced with different active rules are not equivalent.

The JUnit console report shows the effective profile for each test. Spring startup logs show the configured profile; a test JVM override, if present, appears in the JUnit output. JSON schema 1.6 records the effective profile in each test's comparisonInputs entry. The comparator rejects profile differences; see Comparison inputs before replacing a saved baseline.

Audit Coverage Mode¶

By default only tests that opt in via @QueryAudit (or a related annotation) are audited (mode: annotated). This keeps adoption friction low, but every unannotated test is a blind spot — a regression in an uncovered domain merges silently.

mode: all flips the coverage model: every test is audited, and individual tests opt out with @QueryAuditExclude.

Two switches are required:

1. Register the extension suite-wide via JUnit's extension autodetection. In src/test/resources/junit-platform.properties:

junit.jupiter.extensions.autodetection.enabled=true

1. Set the mode — in application.yml for Spring projects:

query-audit:
  mode: all

For plain JUnit, set the same value in the test JVM. With the Gradle property bridge, run ./gradlew test -PqueryAudit.mode=all; with Maven, run mvn test -DqueryAudit.mode=all. The system property wins over the yml value.

Enabling autodetection alone does not widen coverage: in the default annotated mode the extension stays inactive for classes that never opted in, and a class that ends up registered twice (autodetection + @QueryAudit) is audited exactly once.

Brownfield onboarding¶

Turning mode: all on for an existing suite usually surfaces a wall of findings at once. The supported adoption path pairs it with the baseline:

1. Enable mode: all as above.
2. Record the current findings once into the baseline (see Suppressing Issues).
3. From then on, existing findings are frozen — only new violations fail the build.

Coverage first, cleanup incrementally — the audit becomes a ratchet instead of a wall.

Background Work¶

Each audited test captures the SQL that runs on its own thread. Some SQL runs on another thread: an @Async method, an @Async event listener, or a request that a RANDOM_PORT server handles. QueryAudit treats it in two steps.

• Count: while the test is the only audit running, SQL and Hibernate lazy loads from other threads count toward it. When several audits run in parallel, that SQL cannot be assigned to one of them and makes the run INCONCLUSIVE.
• Wait: work handed to a thread pool can still be running when the test method returns. Name those pools in await-executors, and QueryAudit waits until they are idle before it moves to the teardown phase. Their SQL then counts in the test phase, where budgets, contracts, and findings see it. After 30 seconds the test fails with the busy pool's name.

query-audit:
  await-executors: [taskExecutor, webhookExecutor]

Without the wait, background SQL can land in teardown, after the audit ends, or in the next test. QueryContractScope waits for the same pools; see contract a request or job.

Counting covers every thread, not only the named pools, so keep schedulers off during tests. await-executors accepts ThreadPoolTaskExecutor and ThreadPoolExecutor beans. With spring.threads.virtual.enabled, Spring runs @Async work on a SimpleAsyncTaskExecutor, which cannot be awaited; define a ThreadPoolTaskExecutor for tests or wait for the work in the test. Without Spring, wrap the tasks with QueryCaptureSession.wrap; see parallel capture.

Common Configurations¶

Copy-paste these presets for typical use cases.

query-audit:
  profile: recommended               # call-site N+1 only
  await-executors: [taskExecutor]    # wait for @Async work and count its SQL
  contracts:
    path: src/test/resources/query-contracts

query-audit:
  fail-on-detection: false           # report findings, keep budgets and contracts
  report:
    format: html

query-audit:
  auto-open-report: false            # no browser in CI
  report:
    format: json
    output-dir: build/reports/query-audit

query-audit:
  profile: minimal
  slow-query:
    warning-ms: 200
    error-ms: 1000

Recommended Threshold Values¶

Thresholds other than n-plus-one.threshold apply only when their rule is enabled.

@QueryAudit Annotation Attributes¶

See the Annotations Guide for detailed usage patterns.

Annotation-Based Configuration Examples¶

@QueryAudit(
    failOnDetection = BooleanOverride.TRUE,
    nPlusOneThreshold = 2,
    suppress = {"select-all"},
    autoOpenReport = BooleanOverride.FALSE
)
@SpringBootTest
class OrderServiceTest { }

// Annotation overrides only what it specifies.
// Everything else comes from application.yml.
@QueryAudit(nPlusOneThreshold = 2)
@SpringBootTest
class OrderServiceTest { }

# application.yml (base configuration)
query-audit:
  fail-on-detection: true
  suppress-patterns:
    - "select-all"
  report:
    format: console

Programmatic Configuration¶

When using QueryAudit without Spring Boot:

QueryAuditConfig config = QueryAuditConfig.builder()
    .enabled(true)
    .failOnDetection(true)
    .nPlusOneThreshold(5)
    .offsetPaginationThreshold(500)
    .orClauseThreshold(4)
    .largeInListThreshold(100)
    .tooManyJoinsThreshold(5)
    .excessiveColumnThreshold(15)
    .repeatedInsertThreshold(3)
    .repeatedUpdateThreshold(3)
    .repeatedUpdateExcludeTables(Set.of("temp_*", "staging_*"))
    .writeAmplificationThreshold(6)
    .slowQueryWarningMs(500)
    .slowQueryErrorMs(3000)
    .addDisabledRule("select-all")
    .addSeverityOverride("unbounded-result-set", "ERROR")
    .addSuppressPattern("select-all")
    .addSuppressPattern("missing-where-index:users.email")
    .addSuppressQuery("SELECT 1")       // Suppress health-check queries
    .showInfo(true)
    .maxQueries(10_000)                // Limit recorded queries per test
    .build();

Builder Method Reference¶

Setting names¶

Every setting has one name. In application.yml it is a kebab-case path under query-audit. As a system property, Maven -D, or Gradle -P it is the same path in camelCase under queryAudit:

query-audit.report.output-dir   <->   queryAudit.report.outputDir

Spring Boot binds either form, so a system property overrides application.yml. Plain JUnit projects without Spring read the system properties below. Gradle forwards them to test workers through the property bridge.

Configuration can live in application.yml or on the command line. Actions that change files for one run, such as recording, are command-line flags only.

queryAudit.coverage.manifest is read before any Spring context starts, so it has no application.yml form. The environment variable QUERYAUDIT_AUTO_OPEN_REPORT matches queryAudit.autoOpenReport. Count baselines are deprecated since 0.7.0; use query contracts instead.

./gradlew test -PqueryAudit.contracts.record=true

mvn test -DqueryAudit.contracts.record=true

Issue Types Reference¶

Use these codes in suppress, failOn, and suppress-patterns after reviewing the matching finding. Some codes are disabled or reserved; their presence in configuration does not mean that the corresponding check ran.

ERROR Severity¶

WARNING Severity¶

INFO Severity¶

Memory Optimization¶

QueryAudit retains SQL captured through the instrumented DataSource during the audit window. In large test suites or tests that generate many queries, this can consume significant heap memory. The following settings help control memory usage.

Max Queries Per Test (default: 10,000)¶

Each test retains up to 10,000 queries by default. Reaching the limit is valid when no queries are lost. If another query arrives, it is dropped, a warning is printed to stderr, and the suite outcome becomes INCONCLUSIVE with reason QUERY_LIMIT_REACHED. QueryAudit still analyzes the retained queries and preserves their partial findings and statistics, but it does not evaluate count-based contracts against incomplete data. This limits memory used by retained query records and keeps partial collection from producing a successful audit.

The same limit bounds Hibernate lazy-load and explicit-load events per test. Events beyond it are dropped and the run becomes INCONCLUSIVE with AUDIT_ANALYSIS_FAILED and the detail Query capture incomplete [LAZY_LOAD_LIMIT_REACHED]. Metadata still contributes to heap usage.

query-audit:
  max-queries: 5000   # Lower limit for memory-constrained environments

Or programmatically:

QueryAuditConfig config = QueryAuditConfig.builder()
    .maxQueries(5000)
    .build();

Automatic String Pooling¶

QueryAudit automatically deduplicates SQL strings and stack traces in memory. N+1 queries originate from the same call site and execute the same SQL, so pooling ensures that identical strings share a single object reference. This optimization is always active and requires no configuration.

HTML Report Aggregator Memory¶

The HTML report aggregator accumulates reports across all test classes. For test suites with hundreds of test classes, it automatically switches to lightweight summaries (issues only, no raw query list) after the first 200 reports to prevent unbounded memory growth.

Recommended JVM Heap for Large Test Suites¶

Example Gradle configuration:

test {
    jvmArgs '-Xmx1g'
}

See Also¶

• Annotations Guide -- Annotation usage and examples
• Suppressing Issues -- How to suppress specific detections
• Reports -- Report format details and example output
• CI/CD Integration -- Using configuration in CI pipelines

Machine report detail¶

query-audit.report.redaction accepts redacted (the default) or full. The default removes SQL values, comments, raw diagnostic prose, and framework/absolute-path stack details from JSON and GitHub Actions output. It does not change findings or enforcement. Use full only for local debugging; see machine report redaction.

The plain JUnit equivalent is -DqueryAudit.report.redaction=full. Core callers use QueryAuditConfig.builder().reportRedaction(ReportRedaction.FULL) with JsonReporter.