Flyway

Flyway is a database migration tool that lets you version, track, and apply database changes. IntelliJ IDEA provides the following support for Flyway:

Actions for generating migrations and callbacks
Quick navigation between SQL migrations and entity classes
Run configuration for executing SQL migrations and callbacks against the database
Customization of naming patterns for migration files

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.

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 migration process, Flyway executes pending migrations 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";
                        }
                    }
                

Deploy migrations

Once your migrations and callbacks are ready, you can use a dedicated Flyway run configuration to trigger the migration process and bring your database up to date with your code. You can launch this run configuration from the run widget and from selected tool windows.

If the Flyway run configuration is already selected in the widget, click Run.
- Alternatively, press Shift+F10.
If another configuration is selected in the widget, click its name. In the popup that opens, find the Flyway run configuration and click Run next to it.
- Alternatively, press Alt+Shift+F10. In the popup that opens, select the Flyway run configuration.

IntelliJ IDEA launches the Flyway run configuration in the Run tool window.

Run the migration process from tool windows

You can launch the Flyway run configuration from the following tool windows:

Persistence tool window:
- Right-click a persistence unit or entity and select Run Flyway Migrate….
Database tool window:
- Go to the toolbar and select Run Flyway Migrate….
- Right-click a database, schema, or table, and select Run Flyway Migrate….
Project tool window:
- Right-click the directory with your SQL migration files and select Run | Flyway.
  If a Flyway run configuration already exists, this action will be available under Run '<Configuration Name>' instead.

IntelliJ IDEA launches the Flyway run configuration in the Run tool window.

Flyway run configuration

The Flyway run configuration lets you execute your SQL migration files and callbacks against a connected database without having to run the whole application or use the terminal. Under the hood, this configuration runs the Flyway migrate command.

Create a Flyway run configuration

Open the Run/Debug Configurations dialog:
- In the main toolbar, click the run widget and select Edit Configurations….
- Alternatively, go to Run | Edit Configurations….
On the left side of the dialog, select Add New Configuration | Flyway.
Set up the run configuration options.

Run configuration options

Item	Description
Name	Specify a name for the run configuration to quickly identify it among others when editing or running.
Store as project file	Save the run configuration settings to a file that you can share with other team members. The default location is .idea/runConfigurations. However, if you do not want to share the .idea directory, you can save the configuration to any other directory within the project. By default, this option is disabled, and IntelliJ IDEA stores run configuration settings in .idea/workspace.xml.

Item

Description

Name

Specify a name for the run configuration to quickly identify it among others when editing or running.

Store as project file

Save the run configuration settings to a file that you can share with other team members. The default location is .idea/runConfigurations. However, if you do not want to share the .idea directory, you can save the configuration to any other directory within the project.

By default, this option is disabled, and IntelliJ IDEA stores run configuration settings in .idea/workspace.xml.

Required options

Item	Description
Directory	Specify the path to the directory with your SQL migrations.
DB connection	Specify which database Flyway should target when running the migrations. You need to select an existing data source from the Database tool window or create a new one by clicking .

Item

Description

Additional options

To add these options to your run configuration, select Modify options on the right side of the dialog.

Item	Description
Baseline on migrate	Decide how Flyway will behave if you try to execute migrations against a non-empty database schema that does not have a schema history table: If you select this option, Flyway will create the history table, mark the existing schema as baseline, and only execute migrations with a version of 2 and higher. If you clear this option, Flyway will throw an error and not execute the migrations. Learn more about this setting from Flyway's official documentation.
Schemas	Specify which database schema Flyway should target when running the migrations. In case of multiple values, separate them with commas. Learn more about this setting from Flyway's official documentation.

Item

Description

Baseline on migrate

Decide how Flyway will behave if you try to execute migrations against a non-empty database schema that does not have a schema history table:

If you select this option, Flyway will create the history table, mark the existing schema as baseline, and only execute migrations with a version of 2 and higher.
If you clear this option, Flyway will throw an error and not execute the migrations.

Learn more about this setting from Flyway's official documentation.

Schemas

Specify which database schema Flyway should target when running the migrations.

In case of multiple values, separate them with commas.

Learn more about this setting from Flyway's official documentation.

Flyway plugin settings

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

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 migrations 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+build4 `${semVer.getMajor()}`: 1 `${semVer.getMinor()}`: 2 `${semVer.getPatch()}`: 3 `${semVer.getPreRelease()}`: SNAPSHOT
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 use Flyway features in IntelliJ IDEA without adding the dependency to your build files, select this option.

Additional features for Spring projects

On top of the standard Flyway support provided by IntelliJ IDEA, projects based on the Spring framework can leverage additional IDE features.

Migration statuses

Typically, if you want to check which migrations were already executed and with what result, you need to either run Flyway's info command or inspect its schema history table in your database. IntelliJ IDEA provides a faster alternative by displaying the statuses of your SQL migrations directly in the IDE.

Statuses of whole migration files are displayed in the Project tool window (Alt+1).

Each migration is represented by the Flyway logo (), and its status is reflected by a small icon in the logo's lower-right corner:

Icon	Status
	The migration was successfully applied to the database.
	The migration was executed, but one of its SQL statements failed. If a failed migration is additionally underlined in red, you can find out more about the error by hovering over the file name. To check which SQL statement caused the error, open the underlined migration in the editor and look for a red exclamation mark in the gutter. The underline and the gutter icon can only appear when you run the migration process from the IDE, either manually or by launching your Spring Boot application. When you restart the IDE, both the underline and the icon are cleared.
(None)	The migration was not executed yet. If status icons are not displayed for any migrations, refer to the troubleshooting guide.

Icon

Status

The migration was successfully applied to the database.

The migration was executed, but one of its SQL statements failed.

If a failed migration is additionally underlined in red, you can find out more about the error by hovering over the file name.

Red exclamation mark in the editor gutter next to an SQL statement

To check which SQL statement caused the error, open the underlined migration in the editor and look for a red exclamation mark in the gutter.

(None)

The migration was not executed yet.

Troubleshooting

Migrations are displayed without status icons

This feature is only available in Spring projects. If your project does use Spring, make sure that:

You added the Flyway dependency to your project's build file.
You connected to the corresponding database, and the connection is active in the Database tool window.
Your configuration file (application.properties or application.yml) meets the following criteria:
- spring.flyway.locations points to the directory with your migration files.
- spring.flyway.url or spring.datasource.url matches the URL you used to connect to the database.
You already ran Flyway's migrate command, and its results were recorded in the schema history table.

13 July 2026

IntelliJ IDEA 2026.2 Help

Flyway

Add Flyway to an existing project

Flyway migrations

Generate an init migration

Generate a diff migration

Flyway Migration Preview dialog

Java-based migrations

Generate a Java migration

Flyway callbacks

Create an empty SQL callback

Generate a Java callback

Deploy migrations

Run the migration process from the run widget

Run the migration process from tool windows

Flyway run configuration

Create a Flyway run configuration

Run configuration options

Required options

Additional options

Flyway plugin settings

Additional features for Spring projects

Migration statuses

Troubleshooting