Skip to content

Installation

What you'll learn

How to add QueryAudit to your project, choose the right database module, and verify the installation works.

Prerequisites

Requirement Version
Java 17+
JUnit 5.9+
MySQL 5.7+ / 8.0+
PostgreSQL 12+
Spring Boot (optional) 3.0+

Database requirement

You need either MySQL or PostgreSQL -- not both. Pick the tab that matches your database below.

Dependencies

QueryAudit uses a database-module-centric dependency model. Each database module (e.g. query-audit-mysql, query-audit-postgresql) transitively pulls in query-audit-core and query-audit-junit5, so you only need one or two dependencies depending on your setup.

Choose the tab that matches your database and build tool:

dependencies {
    testImplementation 'io.github.haroya01:query-audit-spring-boot-starter:0.1.0'
    testImplementation 'io.github.haroya01:query-audit-mysql:0.1.0'
}

That's all you need

The starter auto-discovers your DataSource bean, wraps it in a capturing proxy, and registers the JUnit 5 extension. No additional configuration required.

dependencies {
    testImplementation 'io.github.haroya01:query-audit-mysql:0.1.0'
}

query-audit-mysql transitively includes query-audit-core and query-audit-junit5.

dependencies {
    testImplementation 'io.github.haroya01:query-audit-spring-boot-starter:0.1.0'
    testImplementation 'io.github.haroya01:query-audit-postgresql:0.1.0'
}

That's all you need

The starter auto-discovers your DataSource bean, wraps it in a capturing proxy, and registers the JUnit 5 extension. No additional configuration required.

dependencies {
    testImplementation 'io.github.haroya01:query-audit-postgresql:0.1.0'
}

query-audit-postgresql transitively includes query-audit-core and query-audit-junit5.

<dependencies>
    <dependency>
        <groupId>io.github.haroya01</groupId>
        <artifactId>query-audit-spring-boot-starter</artifactId>
        <version>0.1.0</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.github.haroya01</groupId>
        <artifactId>query-audit-mysql</artifactId>
        <version>0.1.0</version>
        <scope>test</scope>
    </dependency>
</dependencies>

<dependencies>
    <dependency>
        <groupId>io.github.haroya01</groupId>
        <artifactId>query-audit-mysql</artifactId>
        <version>0.1.0</version>
        <scope>test</scope>
    </dependency>
</dependencies>

<dependencies>
    <dependency>
        <groupId>io.github.haroya01</groupId>
        <artifactId>query-audit-spring-boot-starter</artifactId>
        <version>0.1.0</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.github.haroya01</groupId>
        <artifactId>query-audit-postgresql</artifactId>
        <version>0.1.0</version>
        <scope>test</scope>
    </dependency>
</dependencies>

<dependencies>
    <dependency>
        <groupId>io.github.haroya01</groupId>
        <artifactId>query-audit-postgresql</artifactId>
        <version>0.1.0</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Module Overview

query-audit-mysql              <-- Add this for MySQL
  +-- query-audit-core              (transitive)
  +-- query-audit-junit5            (transitive)

query-audit-postgresql         <-- Add this for PostgreSQL
  +-- query-audit-core              (transitive)
  +-- query-audit-junit5            (transitive)

query-audit-spring-boot-starter  <-- Add this too if using Spring Boot
  +-- query-audit-core              (transitive)
  +-- query-audit-junit5            (transitive)
Module Artifact ID Description
Core query-audit-core Detection engine (57 rules), SQL parser, report generator. Always required (pulled transitively).
MySQL query-audit-mysql MySQL IndexMetadataProvider via SHOW INDEX. Includes core + junit5 transitively.
PostgreSQL query-audit-postgresql PostgreSQL IndexMetadataProvider via pg_catalog. Includes core + junit5 transitively.
JUnit 5 query-audit-junit5 JUnit 5 extension, @QueryAudit / @DetectNPlusOne / @ExpectMaxQueryCount annotations.
Spring Boot Starter query-audit-spring-boot-starter Auto-configuration for Spring Boot tests. Wraps DataSource, binds application.yml settings.

Verify Installation

Run a quick smoke test to confirm everything is wired correctly.

@SpringBootTest
@QueryAudit
class InstallationVerificationTest {

    @Test
    void queryGuardIsActive() {
        // If you see a QueryAudit report in the test output,
        // the installation is working correctly.
    }
}

@EnableQueryInspector
class InstallationVerificationTest {

    private static DataSource dataSource = createTestDataSource();

    @Test
    void queryGuardIsActive() {
        // QueryAudit auto-discovers the static DataSource field
    }
}

Run the test. If QueryAudit is configured correctly, you will see the report header:

================================================================================
                          QUERY AUDIT REPORT
              InstallationVerificationTest (0 queries analyzed)
================================================================================
  0 confirmed issues | 0 info | 0 queries
================================================================================

You're all set!

If you see this output, QueryAudit is installed and working. Move on to the Quick Start to see real detections in action.

Next Steps

Quick Start -- Walk through a full example with real detections.