# Flyway
> **TL;DR**
> Required plugin: [Flyway](https://plugins.jetbrains.com/plugin/23740-flyway) (bundled)
[Flyway](https://documentation.red-gate.com/fd/getting-started-with-flyway-184127223.html) 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](#flyway-migrations) and [callbacks](#flyway-callbacks)
* [Quick navigation](#migrations-quick-navigation) between SQL migrations and entity classes
* [Run configuration](#flyway-run-configuration) for executing SQL migrations and callbacks against the database
* [Customization](#flyway-settings) of naming patterns for migration files
Prior to IntelliJ IDEA version 2024.1, some Flyway features were only available with the [JPA Buddy plugin](jpa-buddy.html). The following video demonstrates these features, which are now available with the Flyway plugin.
[Video](https://www.youtube.com/v/9wEJ29QIDyM)
Procedure: Add Flyway to an existing project
> **Tip:**
> If you want to use Flyway features in IntelliJ IDEA without adding a dependency to your build file, you can enable this in the [Reference: Flyway plugin settings](#flyway-settings).
1. Open the build file in the editor (`pom.xml` or `build.gradle` depending on the [build tool](build-tools.html) used in your project).
2. Add the Flyway library, and make sure its version matches the rest of your project:
Maven:
```XML
org.flywaydb
flyway-core
13.1.0
```
Gradle (Groovy):
```GROOVY
implementation 'org.flywaydb:flyway-core:13.1.0'
```
Gradle (Kotlin):
```KOTLIN
implementation("org.flywaydb:flyway-core:13.1.0")
```
3. Press `Ctrl+Shift+O` (Windows), `Ctrl+Shift+O` (macOS), `Ctrl+Shift+O` (IntelliJ IDEA Classic (macOS)), `Ctrl+Shift+O` (macOS System Shortcuts), `Ctrl+Shift+O` (XWin), `Ctrl+Shift+O` (GNOME), `Ctrl+Shift+O` (KDE), `Ctrl+Shift+O` (Emacs), `Ctrl+Shift+O` (Sublime Text), `Ctrl+Shift+O` (Sublime Text (macOS)), `Ctrl+Shift+O` (NetBeans), `Ctrl+Shift+O` (Visual Studio), `Ctrl+Shift+O` (Visual Studio (macOS)), `Ctrl+Shift+O` (Eclipse), `Ctrl+Shift+O` (Eclipse (macOS)) to import the changes.
For more information about working with build tools, refer to [Maven](maven-support.html) or [Gradle](gradle.html).
## Flyway migrations
[Flyway migrations](https://documentation.red-gate.com/fd/migrations-271585107.html) 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](#initialize-schema): captures a selected data model (database, persistence unit, or mapping context) 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](#generate-migration-script): 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.
* [Empty migration](#generate-empty-file): creates an empty SQL file that follows Flyway's naming patterns.
* [Java migration](#java-migration): creates a Java class that extends Flyway's [BaseJavaMigration class](https://javadoc.io/doc/org.flywaydb/flyway-core/latest/org/flywaydb/core/api/migration/BaseJavaMigration.html) and includes a stub of the [migrate() method](https://javadoc.io/doc/org.flywaydb/flyway-core/latest/org/flywaydb/core/api/migration/JavaMigration.html#migrate(org.flywaydb.core.api.migration.Context)). IntelliJ IDEA does not capture the data model or any schema changes when generating Java migrations.
Procedure: Generate an init migration
1. Open the [Persistence](persistence-tool-window.html) tool window.
2. Right-click a persistence unit, mapping context, 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:
* Model: entity mappings from one of the following: * [persistence unit](persistence-tool-window.html#create-persistence-unit) (in JPA and Spring Data JPA projects) * [mapping context](persistence-tool-window.html#create-mapping-context) (in Spring Data JDBC projects)
* DB: schema from a [connected database](connecting-to-a-database.html)
Based on your selection, IntelliJ IDEA automatically fills in the persistence unit, mapping context, or database connection, which you can change if needed.
4. Click OK.
5. In the [Flyway Migration Preview dialog](#migration-preview-window) that opens, configure the migration and click Save.
Procedure: Generate a diff migration
1. Make sure IntelliJ IDEA is [connected
to your database](managing-data-sources.html#create_a_data_source).
> **Tip:**
> If your project uses [Spring](spring-support.html), [Micronaut](micronaut.html), or [Quarkus](quarkus.html), you can quickly create a database connection right from your configuration file (`application.properties` or `application.yml`).
>
>
>
> To do so, open the file in the editor and click  Create new datasource from existing properties in the editor gutter.
2. Open the [Database](database-tool-window.html) tool window, right-click a database or table, and select  Create Flyway Migration… .
* Alternatively, open the [Persistence](persistence-tool-window.html) tool window, right-click a persistence unit, mapping context, or entity, and select ` New |  Flyway Migration…`.
3. 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](connecting-to-a-database.html) * Model: entity mappings from one of the following: * [persistence unit](persistence-tool-window.html#create-persistence-unit) (in JPA and Spring Data JPA projects) * [mapping context](persistence-tool-window.html#create-mapping-context) (in Spring Data JDBC projects)
* Target (URL) (previous data model): * DB: schema from a connected database * Snapshot: schema from a [data model snapshot](database-versioning.html#generate-data-model-snapshot)
If you select DB or Model, IntelliJ IDEA automatically fills in the persistence unit, mapping context, or database connection, which you can change if needed.
> **Tip:**
> If you frequently generate diff migrations between the same database connection and persistence unit or mapping context, you can select Default connection for persistence unit so IntelliJ IDEA remembers this association in the future.
4. Click OK.
5. In the [Flyway Migration Preview dialog](#migration-preview-window) that opens, configure the migration and click Save.
Procedure: Create an empty migration
Apart from generating migrations that are already filled with DDL scripts, you can also create an empty SQL migration and fill it out yourself.
1. Open the [Project](project-tool-window.html) tool window (`Alt+1` (Windows), `⌘ 1` (macOS), `⌘ 1` (IntelliJ IDEA Classic (macOS)), `⌘ 1` (macOS System Shortcuts), `Alt+1` (XWin), `Alt+1` (GNOME), `Alt+1` (KDE), `Alt+1` (Emacs), `Alt+1` (Sublime Text), `⌘ 1` (Sublime Text (macOS)), `Ctrl+1` (NetBeans), `Ctrl+Alt+L` (Visual Studio), `⌘ ⌥ L` (Visual Studio (macOS)), `Alt+1` (Eclipse), `Alt+1` (Eclipse (macOS))).
2. Right-click the folder with your SQL migrations and select ` New |  Flyway Empty Migration`.
> **Note:**
> If this action is not available, refer to [the
> troubleshooting guide](#cannot-create-empty-migration).
IntelliJ IDEA automatically fills in the prefix and version based on the [Flyway plugin
settings](#flyway-settings) and opens the new migration in the editor.
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 the database is connected in the Database tool window) the table's DDL definition in the database.
To use quick navigation in a migration file, place the caret at a table name, press `Ctrl+B` (Windows), `⌘ B` (macOS), `⌘ B` (IntelliJ IDEA Classic (macOS)), `⌘ B` (macOS System Shortcuts), `Ctrl+B` (XWin), `Ctrl+B` (GNOME), `Ctrl+B` (KDE), `Ctrl+Alt+G` (Emacs), `F12` (Sublime Text), `F12` (Sublime Text (macOS)), `Ctrl+B` (NetBeans), `F12` (Visual Studio), `F12` (Visual Studio (macOS)), `F3` (Eclipse), `F3` (Eclipse (macOS)), and select a destination from the Choose Declaration list. Note that you cannot invoke quick navigation on `CREATE TABLE` statements.
### 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](database-versioning.html#danger-level-settings) 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.
> **Tip:**
> You can also organize changes by dragging them to the desired sections.
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](scratches.html), copy it to the clipboard, or open it in a [query console](query-consoles.html). |
| Directory | Select a location where IntelliJ IDEA should save the SQL file. |
| File name | Set the file name. > **Note:** > Migrations must follow established naming patterns so that Flyway can recognize how to process them. Learn more from [Flyway's official GitHub page](https://github.com/flyway/flywaydb.org/blob/gh-pages/documentation/concepts/migrations.md#naming). IntelliJ IDEA automatically fills in the prefix and version based on the [Flyway plugin settings](#flyway-settings). |
### Java-based migrations
[Java-based
migrations](https://documentation.red-gate.com/fd/java-based-migrations-273973387.html) 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](https://github.com/flyway/flywaydb.org/blob/gh-pages/documentation/concepts/migrations.md#naming-1).
Procedure: Generate a Java migration
1. Press `Ctrl+Shift+A` (Windows), `⌘ ⇧ A` (macOS), `⌘ ⇧ A` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ P` (macOS System Shortcuts), `Ctrl+Shift+A` (XWin), `Ctrl+Shift+A` (GNOME), `Ctrl+Shift+A` (KDE), `Escape, X` (Emacs), `Ctrl+Shift+P` (Sublime Text), `⌘ ⇧ P` (Sublime Text (macOS)), `Ctrl+I` (NetBeans), `Ctrl+Shift+A` (Visual Studio), `⌘ ⇧ A` (Visual Studio (macOS)), `Ctrl+Shift+A` (Eclipse), `⌘ 3` (Eclipse (macOS)), type `Flyway Java Migration`, and press `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (NetBeans), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (Eclipse), `⏎` (Eclipse (macOS)).
2. 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](#flyway-settings).
If needed, change the source root or package where the migration should be created.
3. Click OK.
IntelliJ IDEA opens the generated Java migration class in the editor.
```JAVA
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](#deploy-migrations), 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](https://documentation.red-gate.com/fd/callbacks-275218509.html).
IntelliJ IDEA provides built-in actions for generating the following types of Flyway callbacks:
* [SQL callback](#generate-sql-callback): creates an empty SQL file with a name that matches one of the recognized callback events.
* [Java callback](#generate-java-callback): generates a Java class that implements the [Callback interface](https://javadoc.io/doc/org.flywaydb/flyway-core/latest/org/flywaydb/core/api/callback/Callback.html) and includes initial implementations of [all its methods](https://javadoc.io/doc/org.flywaydb/flyway-core/latest/org/flywaydb/core/api/callback/GenericCallback.html).
Procedure: Create an empty SQL callback
1. Press `Ctrl+Shift+A` (Windows), `⌘ ⇧ A` (macOS), `⌘ ⇧ A` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ P` (macOS System Shortcuts), `Ctrl+Shift+A` (XWin), `Ctrl+Shift+A` (GNOME), `Ctrl+Shift+A` (KDE), `Escape, X` (Emacs), `Ctrl+Shift+P` (Sublime Text), `⌘ ⇧ P` (Sublime Text (macOS)), `Ctrl+I` (NetBeans), `Ctrl+Shift+A` (Visual Studio), `⌘ ⇧ A` (Visual Studio (macOS)), `Ctrl+Shift+A` (Eclipse), `⌘ 3` (Eclipse (macOS)), type `Flyway SQL Callback`, and press `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (NetBeans), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (Eclipse), `⏎` (Eclipse (macOS)).
2. 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.
3. 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).
4. (Optional) Include a callback description. This value will be appended to the file name.
5. 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.
> **Note:**
> For Flyway to recognize your SQL callbacks when it runs, you need to configure the [Flyway callback locations setting](https://documentation.red-gate.com/fd/flyway-callback-locations-setting-313492695.html).
Procedure: Generate a Java callback
1. Press `Ctrl+Shift+A` (Windows), `⌘ ⇧ A` (macOS), `⌘ ⇧ A` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ P` (macOS System Shortcuts), `Ctrl+Shift+A` (XWin), `Ctrl+Shift+A` (GNOME), `Ctrl+Shift+A` (KDE), `Escape, X` (Emacs), `Ctrl+Shift+P` (Sublime Text), `⌘ ⇧ P` (Sublime Text (macOS)), `Ctrl+I` (NetBeans), `Ctrl+Shift+A` (Visual Studio), `⌘ ⇧ A` (Visual Studio (macOS)), `Ctrl+Shift+A` (Eclipse), `⌘ 3` (Eclipse (macOS)), type `Flyway Java Callback`, and press `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (NetBeans), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (Eclipse), `⏎` (Eclipse (macOS)).
2. The Flyway Java Callback dialog opens. Its options determine the callback class name, location, and initial implementations of the [interface methods](https://javadoc.io/doc/org.flywaydb/flyway-core/latest/org/flywaydb/core/api/callback/GenericCallback.html#method-detail).
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](https://documentation.red-gate.com/flyway/reference/callback-events) 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. > **Note:** > 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](https://documentation.red-gate.com/fd/flyway-callbacks-setting-277578977.html). |
3. Click OK.
IntelliJ IDEA opens the generated Java callback class in the editor.
```JAVA
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](#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 multiple places in IntelliJ IDEA.
Procedure: Run the migration process from the run widget
> **Note:**
> To use this feature, you need to [create a Flyway run
> configuration](#create-flyway-run-configuration) first.
* If the Flyway run configuration is already selected in the widget, click  Run.
* Alternatively, press `Shift+F10` (Windows), `⌃ R` (macOS), `⇧ F10` (IntelliJ IDEA Classic (macOS)), `⌥ ⇧ R` (macOS System Shortcuts), `Shift+F10` (XWin), `Shift+F10` (GNOME), `Shift+F10` (KDE), `Shift+F10` (Emacs), `Shift+F10` (Sublime Text), `Shift+F10` (Sublime Text (macOS)), `F6` (NetBeans), `Ctrl+F5` (Visual Studio), `⌃ F5` (Visual Studio (macOS)), `Alt+Shift+X` (Eclipse), `⌘ ⇧ F11` (Eclipse (macOS)).
* 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` (Windows), `⌃ ⌥ R` (macOS), `⌥ ⇧ F10` (IntelliJ IDEA Classic (macOS)), `⌃ ⌥ R` (macOS System Shortcuts), `Alt+Shift+F10` (XWin), `Alt+Shift+F10` (GNOME), `Alt+Shift+F10` (KDE), `Alt+Shift+F10` (Emacs), `Alt+Shift+F10` (Sublime Text), `⌃ ⌥ R` (Sublime Text (macOS)), `Alt+Shift+F10` (NetBeans), `Ctrl+Alt+Shift+R` (Visual Studio), `⌘ ⌥ ⇧ R` (Visual Studio (macOS)), `Alt+Shift+F10` (Eclipse), `⌃ ⌥ R` (Eclipse (macOS)). In the popup that opens, select the Flyway run configuration.
IntelliJ IDEA launches the Flyway run configuration in the [Run tool window](run-tool-window.html).
Procedure: Run the migration process from a tool window
> **Note:**
> If there are no existing Flyway run configurations when you use this feature, the IDE will try to create one based on your configuration file (`flyway.conf`, `application.properties`, or `application.yml`).
You can launch the Flyway run configuration from the following tool windows:
* [Persistence](persistence-tool-window.html) tool window:
* Right-click anywhere in the tool window and select  Run Flyway Migrate….
* [Database](database-tool-window.html) tool window:
* Go to the toolbar and select  Run Flyway Migrate….
* Right-click a database, schema, or table, and select  Run Flyway Migrate….
* [Project](project-tool-window.html) tool window:
* Right-click the directory with your SQL migration files and select ` Run |  Flyway`.
IntelliJ IDEA launches the Flyway run configuration in the [Run tool window](run-tool-window.html).
Procedure: Run the migration process from the configuration file
You can launch the Flyway run configuration from the following files:
* Flyway configuration file (`flyway.conf`)
* [Spring Boot](spring-boot.html) configuration file (`application.properties` or `application.yml`)
1. Open the configuration file in the editor.
2. In the [gutter](editor-gutter.html), click  Run Flyway Migrate… .
> **Note:**
> If this icon is not displayed in your configuration file, refer to [the
> troubleshooting guide](#cannot-run-migrations-from-config-file).
IntelliJ IDEA launches the Flyway run configuration in the [Run tool window](run-tool-window.html).
> **Tip:**
> If the migration process fails, the Run tool window provides a link to the migration where the error occurred.
>
>
>
> 
>
> If you click the link, the IDE opens the migration in the editor and places the caret at the SQL statement that caused the error.
### 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](https://documentation.red-gate.com/fd/info-277578881.html) or inspect its [schema history table](https://documentation.red-gate.com/fd/flyway-schema-history-table-273973417.html) 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` (Windows), `⌘ 1` (macOS), `⌘ 1` (IntelliJ IDEA Classic (macOS)), `⌘ 1` (macOS System Shortcuts), `Alt+1` (XWin), `Alt+1` (GNOME), `Alt+1` (KDE), `Alt+1` (Emacs), `Alt+1` (Sublime Text), `⌘ 1` (Sublime Text (macOS)), `Ctrl+1` (NetBeans), `Ctrl+Alt+L` (Visual Studio), `⌘ ⌥ L` (Visual Studio (macOS)), `Alt+1` (Eclipse), `Alt+1` (Eclipse (macOS))).
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.  > **Note:** > The underline and the gutter icon can only appear when you run the migration process from the IDE by doing one of the following: > > > > * [Launching a Flyway run configuration](#deploy-migrations) > > * [Launching a Spring Boot application](spring-boot.html#run-a-spring-boot-application) > > * [Running a flyway:migrate Maven goal](work-with-maven-goals.html#run_goal) > > * [Running a flywayMigrate Gradle task](work-with-gradle-tasks.html#gradle_tasks) > > > > When you restart the IDE, both the underline and the icon are cleared. |
| (None) | The migration was not executed yet. > **Note:** > If status icons are not displayed for any migrations, refer to [the troubleshooting guide](#migration-files-no-status-icons). |
## Flyway run configuration
The Flyway [run
configuration](run-debug-configuration.html) 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](https://documentation.red-gate.com/fd/migrate-277578887.html).
Procedure: Create a Flyway run configuration
1. Open the Run/Debug Configurations dialog:
* In the main toolbar, click the [run widget](guided-tour-around-the-user-interface.html#toolbar) and select Edit Configurations….
* Alternatively, go to `Run | Edit Configurations…`.
2. On the left side of the dialog, select ` Add New Configuration |  Flyway`.
3. Set up the [run configuration options.](#run-configuration-options)
### Reference: 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`. |
#### Required options
| Item | Description |
| --- | --- |
| DB connection | Specify which database Flyway should target when running the migrations. You need to select an existing [data source](managing-data-sources.html) from the Database tool window or create a new one by clicking . |
| Directories | Specify the paths to the directories with your SQL migrations. Learn more about this setting from the [official Flyway documentation](https://documentation.red-gate.com/fd/flyway-locations-setting-277579008.html). |
#### 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 the [official Flyway documentation](https://documentation.red-gate.com/fd/flyway-baseline-on-migrate-setting-277578974.html). |
| 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 the [official Flyway documentation](https://documentation.red-gate.com/fd/environment-schemas-setting-277578932.html). |
## Reference: Flyway plugin settings
The Flyway plugin settings in IntelliJ IDEA let you configure the naming patterns that the IDE uses when generating migrations.
> **Note:**
> The default values in the plugin settings match the default values recognized by Flyway. If you change any of these values in IntelliJ IDEA, make sure to update the [corresponding Flyway
> settings](https://documentation.red-gate.com/fd/flyway-namespace-277578913.html#FlywayNamespace-Migrationlocationandnamingsettings). Otherwise, your migrations may be processed incorrectly.
To access the Flyway plugin settings, open Settings (`Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))) 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. > **Warning:** > In addition to versioned migrations that you can generate in IntelliJ IDEA, Flyway also supports [other types of migrations](https://documentation.red-gate.com/fd/migrations-271585107.html). 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](https://documentation.red-gate.com/fd/flyway-namespace-277578913.html#FlywayNamespace-Migrationlocationandnamingsettings). 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(, , )`: generate versions using a numeric sequence. * `start`: version number for the first migration * `step`: value to increase each version number by * `decimalFormat`: [DecimalFormat](https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/text/DecimalFormat.html) pattern used to format the version number * `#date()`: generate versions using the current system date. * `simpleDateFormat`: [SimpleDateFormat](https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/text/SimpleDateFormat.html) pattern used to format the date * `${semVer.}`: generate versions using the [semantic version](https://en.wikipedia.org/wiki/Software_versioning#Semantic_versioning) 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. > **Note:** > If you change this value, make sure to update the [Flyway migration separator > setting](https://documentation.red-gate.com/fd/flyway-sql-migration-separator-setting-277579038.html) 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. |
## Troubleshooting
Spring projects:
Cannot create an empty migration
: Make sure that:
:
:
:
: * You [added the Flyway dependency](#add-to-existing-project) to your project's build file.
:
: * You [connected to the corresponding database](connecting-to-a-database.html), 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 either the directory where you are invoking the action or its parent directory. * `spring.flyway.url` or `spring.datasource.url` matches the URL you used to connect to the database.
Cannot run the migration process from the configuration file
: Make sure that:
:
:
:
: * You [added the Flyway dependency](#add-to-existing-project) to your project's build file.
:
: * You [connected to the corresponding database](connecting-to-a-database.html), 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 directories with your migration files. * `spring.flyway.url` or `spring.datasource.url` matches the URL you used to connect to the database.
Migrations are displayed without status icons
: Make sure that:
:
:
:
: * You [added the Flyway dependency](#add-to-existing-project) to your project's build file.
:
: * You [connected to the corresponding database](connecting-to-a-database.html), 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 directories with your migration files. * `spring.flyway.url` or `spring.datasource.url` matches the URL you used to connect to the database. * `spring.flyway.default-schema` matches the database schema you migrated.
:
: * You already [ran the migration process](#deploy-migrations), and its results were recorded in the [schema history table](https://documentation.red-gate.com/fd/flyway-schema-history-table-273973417.html).
Non-Spring projects:
Cannot create an empty migration
: Make sure that:
:
:
:
: * You [added the Flyway dependency](#add-to-existing-project) to your project's build file.
:
: * You [connected to the corresponding database](connecting-to-a-database.html), and the connection is active in the Database tool window.
:
: * Your configuration file (`flyway.conf`) meets the following criteria: * `flyway.locations` points to either the directory where you are invoking the action or its parent directory. * `flyway.url` matches the URL you used to connect to the database.
Cannot run the migration process from the configuration file
: Make sure that:
:
:
:
: * You [added the Flyway dependency](#add-to-existing-project) to your project's build file.
:
: * You [connected to the corresponding database](connecting-to-a-database.html), and the connection is active in the Database tool window.
:
: * Your configuration file (`flyway.conf`) meets the following criteria: * `flyway.locations` points to the directories with your migration files. * `flyway.url` matches the URL you used to connect to the database.
Migrations are displayed without status icons
: Make sure that:
:
:
:
:
:
: * You [added the Flyway dependency](#add-to-existing-project) to your project's build file.
:
: * You [connected to the corresponding database](connecting-to-a-database.html), and the connection is active in the Database tool window.
:
: * Your configuration file (`flyway.conf`) meets the following criteria: * `flyway.locations` points to the directories with your migration files. * `flyway.url` matches the URL you used to connect to the database. * `flyway.defaultSchema` matches the database schema you migrated.
:
: * You already [ran the migration process](#deploy-migrations), and its results were recorded in the [schema history table](https://documentation.red-gate.com/fd/flyway-schema-history-table-273973417.html).
## See also
### JetBrains Blog Posts
[How to Use Flyway for Database Migrations in Spring Boot Applications](https://blog.jetbrains.com/idea/2024/11/how-to-use-flyway-for-database-migrations-in-spring-boot-applications/) [Database Migrations in the Real World](https://blog.jetbrains.com/idea/2025/02/database-migrations-in-the-real-world/)
### External Links
[Jakarta EE: Entities](https://jakarta.ee/learn/docs/jakartaee-tutorial/current/persist/persistence-intro/persistence-intro.html#_entities) [Jakarta EE: Persistence Units](https://jakarta.ee/learn/docs/jakartaee-tutorial/current/persist/persistence-intro/persistence-intro.html#_persistence_units)
### How tos
[Connect to a database](connecting-to-a-database.html) [Create a persistence
unit manually](persistence-tool-window.html#create-persistence-unit)