Flyway

Flyway 是一款数据库迁移工具，可进行版本控制、跟踪并应用数据库更改。 IntelliJ IDEA 提供如下对 Flyway 的支持：

生成迁移脚本和回调脚本的操作
快速导航于 SQL 迁移和实体类之间
执行 SQL 迁移和回调至数据库的运行配置
迁移文件命名模式的自定义

在 IntelliJ IDEA 2024.1 版本之前，部分 Flyway 功能仅可通过 JPA Buddy 插件使用。下列视频演示了这些功能，现在可通过 Flyway 插件使用。

为现有项目添加 Flyway

在编辑器中打开构建文件（根据项目中所用构建工具，可能是 pom.xml 或 build.gradle ）。
添加 Flyway 依赖项，并确保其版本与项目的其他部分一致：
<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") }
（可选）如需通过 Maven 或 Gradle 运行 Flyway 命令，请添加如下插件：
<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>" }
完整的 Flyway 插件配置列表可参考 Flyway 配置文档。
按 Ctrl+Shift+O 导入更改。

有关使用构建工具的详细信息，请参阅 Maven 或 Gradle。

Flyway 迁移

Flyway 迁移定义数据库架构或数据的更改。这些通常是 SQL 文件，但 Flyway 也支持基于 Java 和脚本的迁移。 IntelliJ IDEA 提供内置操作来生成以下类型的 Flyway 迁移：

初始迁移：捕获当前表（数据库或持久化单元）的数据模型。结果为 DDL 脚本，可用于在空数据库中重建该数据模型。
差异迁移：捕获两个数据模型之间的差异，比如当前数据库架构与代码中的实体映射之间的差异。结果为 DDL 脚本，可用于将目标模型变为与源模型一致。
Java 迁移：创建一个继承 Flyway BaseJavaMigration 类并包含 migrate() 方法存根的 Java 类。与其他迁移类型不同，IntelliJ IDEA 在生成 Java 迁移时不会捕获数据模型或任何架构更改。

生成初始迁移

打开 Persistence 工具窗口。
在工具窗口中，右键点击持久化单元或实体，然后选择新建 | Flyway 初始迁移…。
在打开的 Flyway 初始化架构迁移对话框中，选择迁移应基于的数据模型：
- 模型：来自持久化单元的实体映射
- 数据库：来自已连接数据库的架构
根据选择，IntelliJ IDEA 会自动填写持久化单元或数据库连接，您可按需更改。
点击 OK。
在打开的 Flyway 迁移预览对话框中，配置迁移并点击保存。

生成差异迁移

打开 Persistence工具窗口，右键点击持久化单元或实体，然后选择新建 | Flyway 迁移…。
- 或者，打开数据库工具窗口，右键点击数据库或表，然后选择创建 Flyway 迁移…。
在打开的 Flyway 差异迁移对话框中，选择要比较的数据模型：
- 源(referenceURL) （当前数据模型）：
  - 数据库：来自已连接数据库的架构
  - 模型：来自持久化单元的实体映射
- 目标(URL) （前一个数据模型）：
  - 数据库：来自已连接数据库的架构
  - 快照：来自数据模型快照的架构
如果选择数据库或模型，IntelliJ IDEA 会自动填写数据库连接或持久化单元，您可按需更改。
如果经常在同一持久化单元与数据库连接之间生成差异迁移，可选中持久性单元的默认连接，以便 IntelliJ IDEA 记住该关联。
点击 OK。
在打开的 Flyway 迁移预览对话框中，配置迁移并点击保存。

要在迁移文件中使用快捷导航，请将光标放在表名处，按下 Ctrl+B ，并从选择声明列表中选择目标。请注意无法对 CREATE TABLE 语句进行快捷导航。

Flyway 迁移预览对话框

Flyway 迁移预览对话框可预览生成的 DDL 语句，将其整理为迁移文件，并配置保存方式。

对话框左侧展示了生成的架构更改树。每个更改按其风险等级着色，并带有代表更改类型的图标。选择某项更改时，IntelliJ IDEA 会在对话框右侧显示其 DDL 语句。

更改树上方的图标可用于管理生成的更改和迁移：

添加迁移

创建额外的迁移。

从迁移中移除

移除迁移中的所选更改，并可选择将它们移动到已忽略部分，以便将其排除在以后迁移之外。

从忽略状态还原

将所选更改从已忽略部分移动至指定迁移。

移至另一个迁移

将所选更改移动到其他迁移。

如果对话框内没有其他迁移且选择此选项，IntelliJ IDEA 会自动创建一个。

显示其他操作

可一次性与多个更改交互：全选（特定风险等级）、全部展开或全部折叠。

对话框右侧展示所选更改生成的 DDL 语句。如选择了迁移（而非单独更改），还可以通过此区域指定保存方式：

条目	描述
另存为	可以选择将迁移保存为 SQL 文件、临时文件，复制到剪贴板，或在查询控制台中打开。
目录	请选择 IntelliJ IDEA 保存 SQL 文件的位置。 Flyway 在 Maven 和 Gradle 项目中默认查找迁移的目录为 src/main/resources/db/migration 。请确保将迁移保存到该目录，或者更改 Flyway 位置设置。
文件名	设置文件名。迁移命名必须遵循既定格式，Flyway 才能正确识别。可访问 Flyway 官方 GitHub 页面了解详情。 IntelliJ IDEA 会根据 Flyway 插件设置自动填充前缀和版本。

条目

描述

另存为

可以选择将迁移保存为 SQL 文件、临时文件，复制到剪贴板，或在查询控制台中打开。

请选择 IntelliJ IDEA 保存 SQL 文件的位置。

文件名

设置文件名。

IntelliJ IDEA 会根据 Flyway 插件设置自动填充前缀和版本。

基于 Java 的迁移

基于 Java 的迁移适用于无法使用 SQL 轻松表示的更改，是 SQL 迁移的替代方案。这些为实现 Flyway JavaMigration 接口的 Java 类（通常通过扩展 BaseJavaMigration 类），需遵循 Flyway 的命名模式。

生成 Java 迁移文件

请按 Ctrl+Shift+A ，输入 Flyway Java 迁移 并按 Enter。
在打开的 Flyway Java 迁移对话框中，设置文件名。 IntelliJ IDEA 会根据 Flyway 插件设置自动填充前缀和版本。
如有需要，请更改迁移应创建的源码根目录或软件包。
点击 OK。

IntelliJ IDEA 会在编辑器中打开生成的 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 回调函数

当运行迁移流程时，Flyway 会依次执行待处理迁移，一旦所有迁移应用完成则结束流程。虽然这种流程适合大多数常见场景，但更复杂的项目可能需要在每次迁移或迁移生命周期的特定点运行额外逻辑。 Flyway 通过回调支持此类要求。

IntelliJ IDEA 提供内置操作来生成以下类型的 Flyway 回调：

SQL 回调：创建一个具有已识别回调事件名称的空 SQL 文件。
Java 回调：生成一个实现 回调 接口并包含所有方法初始实现的 Java 类。

创建空 SQL 回调

请按 Ctrl+Shift+A ，输入 Flyway SQL 回调 并按 Enter。
将打开 Flyway SQL 回调对话框。 IntelliJ IDEA 会自动填写将要创建回调的源根目录和目录，但如有需要可更改。
点击字段旁的回调事件。将会打开选择回调事件对话框，可在其中选择回调将在迁移生命周期的哪个阶段运行。
每个回调事件旁的图标指示其是否可用于 Flyway Community Edition（CE ），或是否需要 Enterprise Edition（TE）。
（可选）添加回调描述。该值将附加到文件名称。
点击 OK。

IDE 会在编辑器中打开回调文件。您现在可以添加将在所选回调事件期间执行的 SQL 语句。

生成 Java 回调

请按 Ctrl+Shift+A ，输入 Flyway Java 回调 并按 Enter。

将打开 Flyway Java 回调对话框。其选项决定回调类名称、位置以及接口方法的初始实现。

配置回调选项：

条目	描述
名称	指定类名称。
回调名称	指定回调名称。这将成为 `getCallbackName()` 方法的返回值。
回调事件	指定 Flyway 在迁移生命周期的哪些点将从该类调用 `handle()` 方法。 IntelliJ IDEA 会自动将它们添加到 `supports()` 方法。可手动输入事件名称，或点击，在选择回调事件对话框中选择。
可以在事务中处理	如果希望 `canHandleInTransaction()` 方法返回 `true` ，请选择此选项。
源根	选择要创建回调的源根。
软件包	选择要创建回调的软件包。 Flyway 默认查找 Java 回调的软件包为 db.callback 。请确保在此软件包中创建 Java 回调，或更改 Flyway 回调设置。

点击 OK。

IntelliJ IDEA 会在编辑器中打开生成的 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";
                        }
                    }
                
   

部署迁移脚本

准备好迁移脚本和回调后，可使用专用 Flyway 运行配置触发迁移流程，让数据库与代码保持同步。可通过运行微件或选定的工具 Windows 启动此运行配置。

如果运行微件中已选择 Flyway 运行配置，请点击运行。
- 或者按 Shift+F10。
如果运行微件中选择了其他配置，请点击其名称。在弹出的窗口中，找到 Flyway 运行配置，并点击其旁的运行。
- 或者按 Alt+Shift+F10。在弹窗中选择 Flyway 运行配置。

IntelliJ IDEA 会在运行工具窗口中启动 Flyway 运行配置。

从工具 Windows 运行迁移流程

可从以下工具 Windows 启动 Flyway 运行配置：

持久性工具窗口：
- 右键点击持久化单元或实体并选择运行 Flyway 迁移…。
数据库工具窗口：
- 转到工具栏并选择运行 Flyway 迁移…。
- 右键点击数据库、架构或表，并选择运行 Flyway 迁移…。
项目工具窗口：
- 右键点击 SQL 迁移文件所在目录并选择运行 | Flyway。
  若已存在 Flyway 运行配置，该操作将会显示在运行“<配置名称>” 下。

IntelliJ IDEA 会在运行工具窗口中启动 Flyway 运行配置。

Flyway 运行配置

Flyway 运行配置允许无需启动整个应用程序或使用终端，即可针对已连接数据库执行 SQL 迁移文件和回调。在底层，该配置会运行 Flyway migrate 命令。

创建 Flyway 运行配置

打开运行/调试配置对话框：
- 在主工具栏，点击运行微件并选择编辑配置…。
- 或者，转到运行 | 编辑配置…。
在对话框左侧，选择添加新配置 | Flyway。
设置运行配置选项。

运行配置选项

条目	描述
名称	在编辑或运行时，指定运行配置的名称以便快速识别。
存储为项目文件	将运行配置设置保存到文件中，以便与其他团队成员共享。默认位置是 .idea/runConfigurations 。但是，如果您不想共享 .idea 目录，您可以将配置保存到项目内的任何其他目录。默认情况下，此选项是禁用的，IntelliJ IDEA 将运行配置设置存储在 .idea/workspace.xml 。

条目

描述

名称

在编辑或运行时，指定运行配置的名称以便快速识别。

存储为项目文件

将运行配置设置保存到文件中，以便与其他团队成员共享。默认位置是 .idea/runConfigurations 。但是，如果您不想共享 .idea 目录，您可以将配置保存到项目内的任何其他目录。

默认情况下，此选项是禁用的，IntelliJ IDEA 将运行配置设置存储在 .idea/workspace.xml 。

必填选项

条目	描述
目录	指定 SQL 迁移文件所在目录的路径。
数据库连接	指定 Flyway 在运行迁移时应目标哪个数据库。需从数据库工具窗口选择现有数据源，或点击新建。

条目

描述

指定 SQL 迁移文件所在目录的路径。

数据库连接

指定 Flyway 在运行迁移时应目标哪个数据库。

需从数据库工具窗口选择现有数据源，或点击新建。

其他选项

要将这些选项添加到运行配置中，请在对话框右侧选择修改选项。

条目	描述
迁移时设置基线	决定当尝试在没有历史表的非空数据库架构上执行迁移时，Flyway 应如何处理：如果选择此选项，Flyway 会创建历史表，将现有架构标记为基线，并仅在版本为 2 及以上时执行迁移。如果取消选择此选项，Flyway 将抛出错误并不执行迁移。可通过 Flyway 官方文档详细了解该设置。
架构	指定 Flyway 在运行迁移时应目标哪个数据库架构。如需填写多个值，请用逗号分隔。可通过 Flyway 官方文档详细了解该设置。

条目

描述

迁移时设置基线

决定当尝试在没有历史表的非空数据库架构上执行迁移时，Flyway 应如何处理：

如果选择此选项，Flyway 会创建历史表，将现有架构标记为基线，并仅在版本为 2 及以上时执行迁移。
如果取消选择此选项，Flyway 将抛出错误并不执行迁移。

可通过 Flyway 官方文档详细了解该设置。

架构

指定 Flyway 在运行迁移时应目标哪个数据库架构。

如需填写多个值，请用逗号分隔。

可通过 Flyway 官方文档详细了解该设置。

Flyway 插件设置

IntelliJ IDEA 中的 Flyway 插件设置允许配置 IDE 在生成迁移时使用的命名模式。

如需访问 Flyway 插件设置，请打开设置（Ctrl+Alt+S ），然后转到工具 | 数据库版本管理 | Flyway。

您可以配置以下设置：

条目	描述
迁移前缀	指定 IDE 生成迁移文件名称时应使用的前缀。除可在 IntelliJ IDEA 中生成的版本化迁移外，Flyway 还支持其他类型的迁移。每种类型都会映射到不同的前缀。默认情况下，Flyway 使用以下映射： B：基线迁移 R：可重复迁移 U：撤销迁移 V：版本化迁移如果希望使用不同前缀，请确保更新 Flyway 前缀设置。否则，您的迁移可能会被错误处理。
版本模式	指定 IDE 设置文件版本时应使用的模式。可包含以下宏： `#increment(<start>, <step>, <decimalFormat>)` ：使用数字序列生成版本。 `start` ：首个迁移的版本号 `step` ：每个版本号的递增值 `decimalFormat` ：用于格式设置版本号的 DecimalFormat 模式 `#date(<simpleDateFormat>)` ：使用当前系统日期生成版本。 `simpleDateFormat` ：用于格式设置日期的 SimpleDateFormat 模式 `${semVer.<getterMethod>}` ：使用项目构建文件中的语义版本生成版本。 `getterMethod` ：提取语义版本特定段的方法。以下是 1.2.3-SNAPSHOT+build4 版本的示例： `${semVer.getRawVersion()}` ：1.2.3-快照+build4 `${semVer.getMajor()}` ：1 `${semVer.getMinor()}` ：2 `${semVer.getPatch()}` ：3 `${semVer.getPreRelease()}` ：SNAPSHOT
迁移分隔符	指定文件版本与描述之间的分隔符。如果更改此值，请相应更新 Flyway 迁移分隔符设置。
迁移描述	指定将在每个文件名称分隔符后添加的描述。
无依赖项使用 Flyway	如果想在 IntelliJ IDEA 中使用 Flyway 功能而不向构建文件添加依赖项，请选择此选项。

Spring 项目的其他功能

除了 IntelliJ IDEA 提供的标准 Flyway 支持外，基于 Spring 框架的项目还可使用额外的 IDE 功能。

迁移状态

通常要查看哪些迁移已执行及其结果，可以运行 Flyway 的 info 命令或在数据库中检查其架构历史表。 IntelliJ IDEA 提供更快捷的替代方案，直接在 IDE 中显示 SQL 迁移状态。

整个迁移文件的状态会显示在项目工具窗口（Alt+1 ）中。

每个迁移由 Flyway 徽标表示（），其状态通过徽标右下角的小图标反映：

图标	状态
	迁移已成功应用于数据库。
	迁移已执行，但某个 SQL 语句失败。若失败的迁移被红色下划线标记，可将鼠标悬停在文件名称上查看更多错误信息。若要检查是哪个 SQL 语句引发错误，请在编辑器中打开带有下划线的迁移，并查找装订区域中的红色感叹号。下划线与装订区域图标仅在从 IDE 运行迁移流程时出现，无论是手动还是启动 Spring Boot 应用程序运行。重启 IDE 后，下划线和图标都会消失。
(无)	迁移尚未执行。如迁移未显示状态图标，请参考故障排除指南。

图标

状态

迁移已成功应用于数据库。

迁移已执行，但某个 SQL 语句失败。

若失败的迁移被红色下划线标记，可将鼠标悬停在文件名称上查看更多错误信息。

若要检查是哪个 SQL 语句引发错误，请在编辑器中打开带有下划线的迁移，并查找装订区域中的红色感叹号。

(无)

迁移尚未执行。

故障排除

迁移不显示状态图标

此功能仅在 Spring 项目中可用。若项目使用了 Spring，请确保：

已向项目构建文件添加 Flyway 依赖。
已连接到对应数据库，且连接在数据库工具窗口中处于活动状态。
配置文件（ application.properties 或 application.yml ）满足如下条件：
- spring.flyway.locations 指向迁移文件所在目录。
- spring.flyway.url 或 spring.datasource.url 与用于连接数据库的 URL 匹配。
已运行 Flyway 的 migrate 命令，结果已记录在架构历史表中。

2026年 7月 14日

IntelliJ IDEA 2026.2 Help