Exposed Gradle plugin

The Exposed Gradle plugin provides build-time tooling for working with Exposed-based database schemas.

Its primary feature is generating SQL migration scripts by comparing Exposed table definitions with an existing database schema.

Requirements

Kotlin 2.2 or later
Gradle 8.14 or later (Gradle installation guide)
JVM 11 or later
Docker (only required when using Testcontainers)

Installation

To install the plugin, add it to the plugins block in your Gradle build script:

plugins {
  id("org.jetbrains.exposed.plugin") version "1.3.0"
}

Generate migration scripts

To generate migration scripts based on the difference between your existing database schema and your Exposed table definitions, use the generateMigrations task:

./gradlew generateMigrations

Generated files are written to the configured output directory.

Integration with the build lifecycle

You can configure migration generation to run automatically during the Gradle build lifecycle.

For example, you can generate migrations before the build or the processResources tasks:

// Generate migration scripts before the build task
tasks.named("build") {
    dependsOn("generateMigrations")
}

// Generate migration scripts before the processResources task
tasks.named("processResources") {
    dependsOn("generateMigrations")
}

Configuration

Configure the plugin using the exposed.migrations block in your build.gradle.kts file.

At minimum, configure the following properties:

tablesPackage as the package name where Exposed table definitions are located.
A database configuration or a Testcontainers configuration.

Configure a database connection

To configure a database connection, set the databaseUrl, databaseUser, and databasePassword properties:

exposed {
    migrations {
        tablesPackage.set("com.example.db.tables")
        databaseUrl.set("jdbc:postgresql://localhost:5432/mydb")
        databaseUser.set("postgres")
        databasePassword.set("password")
    }
}

Configure `Testcontainers`

To configure a Testcontainers connection, set the testContainersImageName property:

exposed {
    migrations {
        tablesPackage.set("com.example.db.tables")
        testContainersImageName.set("postgres:latest")
    }
}

Additional configuration

Optionally, you can configure the following properties for additional control over migration generation and file naming:

classpath

Classpath scanned for Exposed table definitions.

Defaults to the project's runtime classpath.

fileDirectory

Directory where migration scripts are stored.

Defaults to "src/main/resources/db/migration".

filePrefix

Prefix used for migration script names.

Defaults to "V".

fileVersionFormat

Version format used for migration script names. For supported values, see version formats.

Defaults to a timestamp in the yyyyMMddHHmmss format.

fileSeparator

Separator used in migration script names.

Defaults to "__".

useUpperCaseDescription

Whether the descriptive part of migration script names is converted to uppercase.

Defaults to true.

fileExtension

File extension used for migration scripts.

Defaults to ".sql".

Example:

exposed {
    migrations {
        // ...
        classpath = sourceSets.main.get().runtimeClasspath
        fileDirectory.set(layout.projectDirectory.dir("src/main/resources/db/migration"))
        filePrefix.set("V")
        fileVersionFormat.set(VersionFormat.TIMESTAMP_ONLY)
        fileSeparator.set("__")
        useUpperCaseDescription.set(true)
        fileExtension.set(".sql")
    }
}

Version formats

The plugin supports the following VersionFormat values:

TIMESTAMP_ONLY

Include only the timestamp.

Example: V20260417195521__CREATE_TABLE_USERS.sql

TIMESTAMP_WITHOUT_SECONDS

Include only the timestamp without seconds.

Example: V202604171955__CREATE_TABLE_USERS.sql

MAJOR_TIMESTAMP

Include the major version and the timestamp.

Example: V3_20260417195521__CREATE_TABLE_USERS.sql

MAJOR_TIMESTAMP_WITHOUT_SECONDS

Include the major version and the timestamp without seconds.

Example: V3_202604171955__CREATE_TABLE_USERS.sql

MAJOR_MINOR

Include the major and the minor version.

Example: V3_1__CREATE_TABLE_USERS.sql

MAJOR_ONLY

Include the major version only.

Example: V3__CREATE_TABLE_USERS.sql

For version formats that include a major version, the plugin scans the configured fileDirectory to determine the next available version. If the directory is empty, or if no compatible migration files are found, numbering starts at 1.

File naming

By default, migration scripts use the following naming pattern:

For example:

V20260417195521__CREATE_TABLE_USERS.sql

The generated description (CREATE_TABLE_USERS) is derived from the generated SQL statement and typically follows this format:

When a migration contains multiple SQL statements, the description is usually derived from the first significant statement.

A migration that creates two related tables typically uses the description of the first CREATE TABLE statement.
If a sequence must be created before a table, the generated description still prefers the CREATE TABLE statement instead of CREATE SEQUENCE.

If the plugin cannot derive a standard description, it falls back to a generic name, such as CUSTOM_STATEMENT_12345.

Override the generated filename

You can override the generated filename by passing the --filename argument to the generateMigrations task:

./gradlew generateMigrations --filename=V0__initialize_schema.sql

Using `Testcontainers`

Testcontainers is a Java library that lets you run temporary Docker containers during tests or build tasks. You can use Testcontainers to start a disposable database instance automatically while generating migration scripts.

`Testcontainers` workflow

When using Testcontainers, the Exposed Gradle plugin performs the following steps:

Starts a database container.
Applies existing migration scripts using Flyway.
Compares the resulting database schema with your Exposed table definitions.
Generates new migration scripts.
Stops the container.

If the configured migration directory contains existing migration scripts, the plugin applies them using Flyway before generating new migrations.

This ensures that newly generated migration scripts are based on the latest schema state, including changes introduced by previous migrations.

Supported databases

The plugin supports the following database container images:

Database	Container images
MySQL	`mysql`, `mysql:latest`, or other tags
MariaDB	`mariadb`, `mariadb:latest`, or other tags
PostgreSQL	`postgres`, `postgres:latest`, or other tags
SQL Server	`mcr.microsoft.com/mssql/server`, `mcr.microsoft.com/mssql/server:2025-latest`, or other tags
Oracle	Images starting with `container-registry.oracle.com/`, `gvenzl/oracle-` or `oracle/`

Next steps

The Exposed Gradle plugin generates migration scripts, but it does not apply them to your database automatically.

After generating migration scripts, review and apply them using your existing database migration workflow. For example, you can:

Apply migrations using tools such as Flyway or Liquibase.
Execute scripts manually using your database client.
Run scripts from the IntelliJ IDEA Database tool window.
Integrate migration execution into your CI/CD pipeline.

After applying the generated scripts, your database schema should match your current Exposed table definitions.

Last modified: 14 May 2026