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

Open the build file in the editor (pom.xml or build.gradle depending on the build tool used in your project).
Add the Flyway dependency, and 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") }
(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.
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. These are typically SQL files, but Flyway also supports Java-based and script migrations. IntelliJ IDEA provides built-in actions for generating the following types of Flyway 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.
Java migration: creates a Java class that extends Flyway's BaseJavaMigration class and includes a stub of the migrate() method. Unlike with other migration types, IntelliJ IDEA does not capture the data model or any schema changes when generating Java migrations.

Generate an init migration

Open the Persistence tool window.
In the tool window, right-click a persistence unit or entity, and select New | Flyway Init Migration….
In the Flyway Init Schema Migration dialog that opens, select which data model the migration should be based on:
- Model: entity mappings from a persistence unit
- DB: schema from a connected database
Based on your selection, IntelliJ IDEA automatically fills in the persistence unit or database connection, which you can change if needed.
Click OK.
In the Flyway Migration Preview dialog that opens, configure the migration and click Save.

Generate a diff migration

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….
In the Flyway Diff Migration dialog that opens, select which data models to compare:
- Source (referenceURL) (current data model):
  - DB: schema from a connected database
  - Model: entity mappings from a persistence unit
- Target (URL) (previous data model):
  - DB: schema from a connected database
  - Snapshot: schema from a data model snapshot
If you select DB or Model, IntelliJ IDEA automatically fills in the database connection or persistence unit, which you can change if needed.
If you frequently generate diff migrations between the same persistence unit and database connection, you can select Default connection for persistence unit so IntelliJ IDEA remembers this association in the future.
Click OK.
In the Flyway Migration Preview dialog that opens, configure the migration and click Save.

SQL migration files support quick navigation for table names. You can jump to a table's entity class, the migration that first introduced the table, or (if a data source is attached to the file) the table's DDL definition in a connected database.

To use quick navigation in a migration file, place the caret at a table name, press Ctrl+B, and select a destination from the Choose Declaration list. Note that you cannot invoke quick navigation on CREATE TABLE statements.

Navigating to table declarations options

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.

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

Create an additional 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. The default location where Flyway looks for migrations in Maven and Gradle projects is src/main/resources/db/migration. Make sure to save your migrations in this directory or change the Flyway locations setting.
File name	Set the file name. Migrations must follow established naming patterns so that Flyway can recognize how to process them. Learn more from Flyway's official GitHub page. IntelliJ IDEA automatically fills in the prefix and version based on the Flyway plugin settings.

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.

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 a Java migration

Press Ctrl+Shift+A, type Flyway Java Migration, and press Enter.
In the Flyway Java Migration dialog that opens, set the file name. IntelliJ IDEA automatically fills in the prefix and version based on the Flyway plugin settings.
If needed, change the source root or package where the migration should be created.
Click OK.

IntelliJ IDEA opens the generated Java migration class in the editor.

                    package org.example.demoflyway;

                    import org.flywaydb.core.api.migration.BaseJavaMigration;
                    import org.flywaydb.core.api.migration.Context;
                    import java.sql.PreparedStatement;

                    public class V1__CreateTables extends BaseJavaMigration {

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

                        }
                    }
                

Flyway callbacks

When you run the Flyway migrate command, Flyway executes pending migration files one by one and finishes the process once all migrations are applied. While this flow suits most common scenarios, more complex projects may require running additional logic with each migration or at specific points in the migration lifecycle. Flyway supports such requirements through callbacks.

IntelliJ IDEA provides built-in actions for generating the following types of Flyway callbacks:

SQL callback: creates an empty SQL file with a name that matches one of the recognized callback events.
Java callback: generates a Java class that implements the Callback interface and includes initial implementations of all its methods.

Create an empty SQL callback

Press Ctrl+Shift+A, type Flyway SQL Callback, and press Enter.
The Flyway SQL Callback dialog opens. IntelliJ IDEA automatically fills in the source root and directory where the callback will be created, but you can change them if needed.
Click next to the Callback event field. This opens the Choose Callback Event dialog, where you can select at which point in the migration lifecycle your callback will run.
The icon next to each callback event indicates if it is available in Flyway Community Edition (CE) or if it requires the Enterprise Edition (TE).
(Optional) Include a callback description. This value will be appended to the file name.
Click OK.

The IDE opens the callback file in the editor. You can now add SQL statements that will be executed during the selected callback event.

Generate a Java callback

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

The Flyway Java Callback dialog opens. Its options determine the callback class name, location, and initial implementations of the interface methods.

Configure the callback options:

Item	Description
Name	Specify the class name.
Callback name	Specify the callback name. It will be the return value of the `getCallbackName()` method.
Callback event	Specify at which points in the migration lifecycle Flyway will call the `handle()` method from this class. IntelliJ IDEA will automatically add them to the `supports()` method. You can type the event names manually or click to select them from the Choose Callback Event dialog.
Can handle in transaction	If you want the `canHandleInTransaction()` method to return `true`, select this option.
Source root	Select the source root where you want to create the callback.
Package	Select the package where you want to create the callback. The default package where Flyway looks for Java callbacks is db.callback. Make sure to create your Java callbacks in this package or change the Flyway callbacks setting.

Click OK.

IntelliJ IDEA opens the generated Java callback class in the editor.

                    package db.callback;

                    import org.flywaydb.core.api.callback.Callback;
                    import org.flywaydb.core.api.callback.Context;
                    import org.flywaydb.core.api.callback.Event;

                    public class FlywayCallback implements Callback {

                        @Override
                        public boolean supports(Event event, Context context) {
                            return event.equals(Event.BEFORE_MIGRATE);
                        }

                        @Override
                        public boolean canHandleInTransaction(Event event, Context context) {
                            return true;
                        }

                        @Override
                        public void handle(Event event, Context context) {
                            //TODO handle logic...
                        }

                        public String getCallbackName() {
                            return "Flyway";
                        }
                    }
                

Flyway plugin settings

The Flyway plugin settings in IntelliJ IDEA let you configure the naming patterns that the IDE uses when generating migration files.

To access the Flyway plugin settings, open Settings (Ctrl+Alt+S) and go to Tools | Database Versioning | Flyway.

You can configure the following settings:

Item	Description
Migration prefix	Specify what prefix the IDE should use when generating migration file names. In addition to versioned migrations that you can generate in IntelliJ IDEA, Flyway also supports other types of migrations. Each type is mapped to a different prefix. By default, Flyway uses the following mappings: B: baseline migrations R: repeatable migrations U: undo migrations V: versioned migrations If you want to use different prefixes, make sure to update the Flyway prefix settings. Otherwise, your migration files may be processed incorrectly.
Version pattern	Specify a pattern the IDE should use when setting the file version. You can include the following macros: `#increment(<start>, <step>, <decimalFormat>)`: generate versions using a numeric sequence. `start`: version number for the first migration `step`: value to increase each version number by `decimalFormat`: DecimalFormat pattern used to format the version number `#date(<simpleDateFormat>)`: generate versions using the current system date. `simpleDateFormat`: SimpleDateFormat pattern used to format the date `${semVer.<getterMethod>}`: generate versions using the semantic version from the project's build file. `getterMethod`: method that extracts a specific segment of the semantic version. Here are examples for a 1.2.3-SNAPSHOT+build4 version: `${semVer.getRawVersion()}`: 1.2.3-SNAPSHOT `${semVer.getMajor()}`: 1 `${semVer.getMinor()}`: 2 `${semVer.getPatch()}`: 3 `${semVer.getPreRelease()}`: SNAPSHOT `${semVer.getMetadata()}`: build4
Migration separator	Specify the separator between the file version and description. If you change this value, make sure to update the Flyway migration separator setting accordingly.
Migration description	Specify the description that will be added after the separator in each file name.
Use Flyway without dependency	If you want to generate migrations without having to add the Flyway dependency to your build files, select this option.

08 May 2026