IntelliJ IDEA 2025.3 Help

Flyway

Flyway is a database migration tool that lets you version, track, and apply database changes. IntelliJ IDEA supports Flyway with dedicated actions for generating migrations (which define changes to the database) and callbacks (which run at specific points in the migration lifecycle).

Prior to IntelliJ IDEA version 2024.1, some Flyway features were only available with the JPA Buddy plugin. The following video demonstrates these features, which are now available with the Flyway plugin.

Add Flyway to an existing project

  1. Open the build file in the editor (pom.xml or build.gradle depending on the build tool that you use in your project).

  2. Add the following dependency, but make sure the version matches the rest of your project:

    <dependencies> <dependency> <groupId>org.flywaydb</groupId> <artifactId>flyway-core</artifactId> <version>12.0.3</version> </dependency> </dependencies>
    dependencies { implementation 'org.flywaydb:flyway-core:12.0.3' }
    dependencies { implementation("org.flywaydb:flyway-core:12.0.3") }

  3. (Optional) If you want to run Flyway commands using Maven or Gradle, add the following plugin:

    <plugins> <plugin> <groupId>org.flywaydb</groupId> <artifactId>flyway-maven-plugin</artifactId> <version>12.0.3</version> <configuration> <url>${YOUR_DATABASE_URL}</url> <user>${YOUR_DATABASE_USERNAME}</user> <password>${YOUR_DATABASE_PASSWORD}</password> </configuration> </plugin> </plugins>
    plugins { id 'org.flywaydb.flyway' version '12.0.3' } flyway { url = '<YOUR DATABASE URL>' user = '<YOUR DATABASE USERNAME>' password = '<YOUR DATABASE PASSWORD>' }
    plugins { id ("org.flywaydb.flyway") version "12.0.3" } flyway { url = "<YOUR DATABASE URL>" user = "<YOUR DATABASE USERNAME>" password = "<YOUR DATABASE PASSWORD>" }

    For a complete list of Flyway plugin configurations, refer to the Flyway configuration reference.

  4. Press Ctrl+Shift+O to import the changes.

For more information about working with build tools, refer to Maven or Gradle.

Flyway migrations

Flyway migrations define changes to the database schema or data. They are typically written in SQL, but Flyway also supports Java-based and script migrations. IntelliJ IDEA provides built-in actions for generating empty Java-based migrations and two types of SQL schema migrations:

  • Init migration: captures a selected data model (database or persistence unit) in its current form. The result is a DDL script that you can use to recreate that data model in an empty database.

  • Diff migration: captures the differences between two data models: for example, between the current database schema and the entity mappings in your code. The result is a DDL script that you can run against the target model to make it match the source.

Generate an init migration

  1. Open the Persistence tool window.

  2. In the tool window, right-click a persistence unit or entity, and select New | Flyway Init Migration.

  3. In the Flyway Init Schema Migration dialog that opens, select which data model the migration should be based on:

    init-schema-changelog

    Based on your selection, IntelliJ IDEA automatically fills in the persistence unit or database connection, which you can change if needed.

  4. Click OK.

  5. In the Flyway Migration Preview dialog that opens, configure the migration and click Save.

Generate a diff migration

  1. Open the Persistence tool window, right-click a persistence unit or entity, and select New | Flyway Migration.

    • Alternatively, open the Database tool window, right-click a database or table, and select Create Flyway Migration.

  2. In the Flyway Diff Migration dialog that opens, select which data models to compare:

    Migration Script window

    If you select DB or Model, IntelliJ IDEA automatically fills in the database connection or persistence unit, which you can change if needed.

  3. Click OK.

  4. In the Flyway Migration Preview dialog that opens, configure the migration and click Save.

Flyway Migration Preview dialog

The Flyway Migration Preview dialog lets you review the generated DDL statements, organize them into migrations, and configure how to save them.

flyway-preview

The left side of the dialog displays a tree of the generated schema changes. Each change is color-coded by its danger level and marked with an icon that represents the change type. If you select a specific change, IntelliJ IDEA displays its DDL statement on the right side of the dialog.

The icons above the change tree let you manage the generated changes and migrations:

Add Migration

Add Migration

Create an additional migration.

Remove from Migration

Remove from Migration

Remove the selected changes from the migration and, optionally, move them to the Ignored section so they are excluded from future migrations.

Restore from Ignored

Move the selected changes from the Ignored section to a migration of your choice.

Move to Another Migration

Move the selected changes to another migration.

If you select this option when there are no other migrations in the dialog, IntelliJ IDEA creates one automatically.

Show Other Actions

Interact with multiple changes at once: Select All with a specific danger level, Expand All, or Collapse All.

The right side of the dialog displays the generated DDL statements for the currently selected changes. If you select a migration (not an individual change), you can also use this section to specify how you want to save it:

Item

Description

Save as

Choose whether to save the migration as an SQL file, save it as a scratch file, copy it to the clipboard, or open it in a query console.

Directory

Select a location where IntelliJ IDEA should save the SQL file.

File name

Set the file name.

IntelliJ IDEA automatically fills in the prefix and number based on the Flyway settings.

Java-based migrations

Java-based migrations are an alternative to SQL migrations for changes that cannot easily be expressed in SQL. They are Java classes that implement Flyway's JavaMigration interface (typically by extending the BaseJavaMigration class) and follow Flyway's naming patterns.

Generate an empty Java migration

  1. Press Ctrl+Shift+A, type Flyway Java Migration, and press Enter.

  2. In the Flyway Java Migration dialog that opens, set the file name. IntelliJ IDEA automatically fills in the prefix and number based on the Flyway settings.

    flyway-java-migration

    If needed, change the source root or package where the migration should be created.

  3. Click OK.

IntelliJ IDEA generates the following Java class:

public class V1__YOUR_MIGRATION_NAME extends BaseJavaMigration { @Override public void migrate(Context context) throws Exception { try (PreparedStatement statement = context.getConnection() .prepareStatement("")) { statement.execute(); } } }

Flyway callbacks

While migrations are sufficient for most needs, certain situations require you to execute the same action over and over again. With the help of IntelliJ IDEA, you can generate all events that Flyway supports.

Generate SQL Callback

  1. Press Ctrl+Shift+A and start typing Flyway SQL Callback.

  2. In the window that opens, select the source root and directory for the generated file.

    Flyway SQL Callback

  3. In the Callback event field, select one of the events that Flyway supports.

    Callback event

Optionally, the callbacks may also include a description. The value of the Description field will be appended to the callback name.

Generate Java Callback

  1. Open a Java file in the editor.

  2. Press Ctrl+Shift+A and start typing Flyway Java Callback.

  3. In the window that opens, enter a class name and a callback name and select a callback event. Select the class source root and package.

    Use the Can handle in transaction checkbox to specify whether the canHandleInTransaction overridden method should return true or false.

    Flyway Java Callback

Flyway settings

Whenever an empty or differential Flyway migration is created, IntelliJ IDEA generates the file name based on the flyway naming pattern. In the IDE settings (Ctrl+Alt+S), you can configure values for name generation.

Flyway Settings window

  • Migration prefix. The default value is V.

  • Version pattern. After the hyphen, an example of the generated sequence is presented.

  • Migration separator. The default value is "_".

  • Migration description.

The following variables and macros are available in the templates:

  • #date([format]) – the current system date in the specified SimpleDateFormat. For example, #date(\"yyyy-MM-dd\") returns the date formatted as 2020-12-31.

  • #increment([start], [step], [decimalFormat]) — a number that is used to keep the name unique. start value is used for the first file and is incremented by step for each next file. decimalFormat parameter specifies the DecimalFormat of the number. For example, #increment(1.0, 0.1, \"#.0\") returns the value formatted as 1.1, 1.2, 1.3, etc.

  • semVer — semantic version of the project (aka SemVer) is a widely adopted version scheme that uses a sequence of three digits (Major.Minor.Patch), an optional pre-release tag and optional build meta tag. The object contains the following methods (the full version in the examples is 1.2.3-SNAPSHOT+meta):

    • ${semVer.getRawVersion()}: 1.2.3-SNAPSHOT

    • ${semVer.getMajor()}: 1

    • ${semVer.getMinor()}: 2

    • ${semVer.getPatch()}: 3

    • ${semVer.getPreRelease()}: SNAPSHOT

    • ${semVer.getMeta()}: meta

24 January 2026
LiquibaseApplication servers