Flyway

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

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

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

为现有项目添加 Flyway

在编辑器中打开构建文件（ pom.xml 或 build.gradle ，具体取决于项目中使用的构建工具）。
添加 Flyway 库，并确保其版本与项目的其余部分匹配：
<dependency> <groupId>org.flywaydb</groupId> <artifactId>flyway-core</artifactId> <version>13.1.0</version> </dependency>
implementation 'org.flywaydb:flyway-core:13.1.0'
implementation("org.flywaydb:flyway-core:13.1.0")
（可选）如果要使用 Maven 或 Gradle 运行 Flyway 命令，请添加专用插件：
<plugin> <groupId>org.flywaydb</groupId> <artifactId>flyway-maven-plugin</artifactId> <version>13.1.0</version> <configuration> <url>${YOUR_DATABASE_URL}</url> <user>${YOUR_DATABASE_USERNAME}</user> <password>${YOUR_DATABASE_PASSWORD}</password> </configuration> </plugin>
有关配置插件的更多信息，请参阅官方 Flyway 文档。
plugins { id 'org.flywaydb.flyway' version '13.1.0' } flyway { url = '<YOUR DATABASE URL>' user = '<YOUR DATABASE USERNAME>' password = '<YOUR DATABASE PASSWORD>' }
有关配置插件的更多信息，请参阅官方 Flyway 文档。
plugins { id ("org.flywaydb.flyway") version "13.1.0" } flyway { url = "<YOUR DATABASE URL>" user = "<YOUR DATABASE USERNAME>" password = "<YOUR DATABASE PASSWORD>" }
有关配置插件的更多信息，请参阅官方 Flyway 文档。
按 Ctrl+Shift+O 导入更改。

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

Flyway 迁移

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

初始化迁移：以当前形式捕获所选数据模型（数据库、持久化单元或映射上下文）。结果是一个 DDL 脚本，可用于在空数据库中重新创建该数据模型。
差异迁移：捕获两个数据模型之间的差异：例如，当前数据库架构与代码中的实体映射之间的差异。结果是一个 DDL 脚本，可以针对目标模型运行，使其与源匹配。
空迁移：创建一个遵循 Flyway 命名模式的空 SQL 文件。
Java 迁移：创建一个 Java 类，该类扩展 Flyway 的 BaseJavaMigration 类，并包含 migrate() 方法的存根。 IntelliJ IDEA 在生成 Java 迁移时不会捕获数据模型或任何架构更改。

生成初始迁移

打开 Persistence 工具窗口。
在工具窗口中，右键点击持久化单元、映射上下文或实体，然后选择新建 | Flyway Init 迁移……。
在打开的 Flyway 初始化架构迁移对话框中，选择迁移应基于的数据模型：
- 模型：来自以下项之一的实体映射：
  - 持久化单元（在 JPA 和 Spring Data JPA 项目中）
  - 映射上下文（在 Spring Data JDBC 项目中）
- 数据库：来自已连接的数据库的架构
根据所选内容，IntelliJ IDEA 会自动填写持久化单元、映射上下文或数据库连接，必要时可以更改。
点击 OK。
在打开的 Flyway 迁移预览对话框中，配置迁移并点击保存。

生成差异迁移

确保 IntelliJ IDEA 已连接到数据库。
如果项目使用 Spring、 Micronaut 或 Quarkus ，可以直接从配置文件（ application.properties 或 application.yml ）快速创建数据库连接。
为此，请在编辑器中打开该文件，然后在编辑器装订区域中点击从现有属性创建新数据源。
打开数据库工具窗口，右键点击数据库或表，然后选择创建 Flyway 迁移…。
- 或者，打开持久化工具窗口，右键点击持久化单元、映射上下文或实体，然后选择新建 | Flyway 迁移……。
在打开的 Flyway 差异迁移对话框中，选择要比较的数据模型：
- 源(referenceURL) (当前数据模型)：
  - 数据库：来自已连接的数据库的架构
  - 模型：来自以下项之一的实体映射：
    - 持久化单元（在 JPA 和 Spring Data JPA 项目中）
    - 映射上下文（在 Spring Data JDBC 项目中）
- 目标(URL) (先前数据模型)：
  - 数据库：来自已连接数据库的架构
  - 快照：来自数据模型快照的架构
如果选择数据库或模型，IntelliJ IDEA 会自动填写持久化单元、映射上下文或数据库连接，必要时可以更改。
如果经常在相同的数据库连接与持久化单元或映射上下文之间生成差异迁移，可以选择持久性单元的默认连接，以便 IntelliJ IDEA 今后记住此关联。
点击 OK。
在打开的 Flyway 迁移预览对话框中，配置迁移并点击保存。

创建空迁移

除了生成已填充 DDL 脚本的迁移外，还可以创建空 SQL 迁移并自行填写。

打开项目工具窗口（Alt+1）。
右键点击包含 SQL 迁移的文件夹，然后选择新建 | Flyway 空迁移。
- 或者，选择文件夹，按 Alt+Insert ，然后选择 Flyway 空迁移。
如果此操作不可用，请参阅故障排除指南。

IntelliJ IDEA 会根据 Flyway 插件设置自动填写前缀和版本，并在编辑器中打开新迁移。

要在迁移文件中使用快速导航，请将文本光标放在表名称处，按 Ctrl+B ，然后从选择声明列表中选择目标。请注意，不能对 CREATE TABLE 语句调用快速导航。

Flyway 迁移预览对话框

Flyway 迁移预览对话框可用于检查生成的 DDL 语句、将其整理到迁移中，并配置保存方式。

对话框左侧显示生成的架构更改树。每项更改都会按其危险级别进行颜色编码，并标有表示更改类型的图标。如果选择特定更改，IntelliJ IDEA 会在对话框右侧显示其 DDL 语句。

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

添加迁移

创建附加迁移。

从迁移中移除

从迁移中移除所选更改，并可选择将它们移动到已忽略部分，以便将它们从将来的迁移中排除。

从忽略状态还原

将所选更改从已忽略部分移动到所选迁移。

移至另一个迁移

将所选更改移动到另一个迁移。

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

显示其他操作

一次性处理多个更改：具有特定危险级别的全选、全部展开或全部收起。

对话框右侧显示当前所选更改生成的 DDL 语句。如果选择的是迁移(而不是单个更改)，还可以使用此部分指定保存方式：

条目	描述
另存为	可以选择将迁移保存为 SQL 文件、临时文件，复制到剪贴板，或在查询控制台中打开。
目录	选择 IntelliJ IDEA 应保存 SQL 文件的位置。
文件名	设置文件名。迁移必须遵循既定命名模式，以便 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 运行配置触发迁移流程，让数据库与代码保持同步。可以从 IntelliJ IDEA 中的多个位置启动此运行配置。

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

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

从工具窗口运行迁移进程

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

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

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

从配置文件运行迁移进程

可以从以下文件启动 Flyway 运行配置：

Flyway 配置文件（ flyway.conf ）
Spring Boot 配置文件（ application.properties 或 application.yml ）

在编辑器中打开配置文件。
在装订区域中，点击运行 Flyway 迁移…。
如果此图标未显示在配置文件中，请参阅故障排除指南。

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

迁移状态

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

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

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

图标	状态
	迁移已成功应用于数据库。
	迁移已执行，但某个 SQL 语句失败。若失败的迁移被红色下划线标记，可将鼠标悬停在文件名称上查看更多错误信息。若要检查是哪个 SQL 语句引发错误，请在编辑器中打开带有下划线的迁移，并查找装订区域中的红色感叹号。可以点击装订区域图标以再次查看错误详细信息。只有在通过以下任一方式从 IDE 运行迁移进程时，下划线和装订区域图标才会出现：启动 Flyway 运行配置启动 Spring Boot 应用程序运行 flyway:migrate Maven 目标运行 flywayMigrate Gradle 任务重启 IDE 后，下划线和图标都会消失。
(无)	迁移尚未执行。如迁移未显示状态图标，请参考故障排除指南。

图标

状态

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

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

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

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

可以点击装订区域图标以再次查看错误详细信息。

(无)

迁移尚未执行。

Flyway 运行配置

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

创建 Flyway 运行配置

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

参考：运行配置选项

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

条目

描述

名称

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

存储为项目文件

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

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

必填选项

条目	描述
数据库连接	指定 Flyway 在运行迁移时应目标哪个数据库。需从数据库工具窗口选择现有数据源，或点击新建。
目录	指定包含 SQL 迁移的目录路径。从官方 Flyway 文档详细了解此设置。

条目

描述

数据库连接

指定 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()}` ：快照
迁移分隔符	指定文件版本与描述之间的分隔符。如果更改此值，请相应更新 Flyway 迁移分隔符设置。
迁移描述	指定将在每个文件名称分隔符后添加的描述。
无依赖项使用 Flyway	如果想在 IntelliJ IDEA 中使用 Flyway 功能而不向构建文件添加依赖项，请选择此选项。

故障排除

无法创建空迁移

确保：

已向项目构建文件添加 Flyway 依赖。
已连接到对应数据库，且连接在数据库工具窗口中处于活动状态。
配置文件（ application.properties 或 application.yml ）满足如下条件：
- spring.flyway.locations 指向调用该操作的目录或其父目录。
- spring.flyway.url 或 spring.datasource.url 与用于连接数据库的 URL 匹配。

无法从配置文件运行迁移进程

确保：

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

迁移不显示状态图标

确保：

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

无法创建空迁移

确保：

已向项目构建文件添加 Flyway 依赖。
已连接到对应数据库，且连接在数据库工具窗口中处于活动状态。
配置文件（ flyway.conf ）符合以下条件：
- flyway.locations 指向调用该操作的目录或其父目录。
- flyway.url 与用于连接数据库的 URL 匹配。

无法从配置文件运行迁移进程

确保：

已向项目构建文件添加 Flyway 依赖。
已连接到对应数据库，且连接在数据库工具窗口中处于活动状态。
配置文件（ flyway.conf ）符合以下条件：
- flyway.locations 指向包含迁移文件的目录。
- flyway.url 与用于连接数据库的 URL 匹配。

迁移不显示状态图标

确保：

已向项目构建文件添加 Flyway 依赖。
已连接到对应数据库，且连接在数据库工具窗口中处于活动状态。
配置文件（ flyway.conf ）符合以下条件：
- flyway.locations 指向包含迁移文件的目录。
- flyway.url 与用于连接数据库的 URL 匹配。
- flyway.defaultSchema 与迁移的数据库架构匹配。
已经运行迁移进程，其结果已记录在架构历史记录表中。

2026年 11月 3日

IntelliJ IDEA 2026.3 Help

Flyway

为现有项目添加 Flyway

Flyway 迁移

生成初始迁移

生成差异迁移

创建空迁移

Flyway 迁移预览对话框

基于 Java 的迁移

生成 Java 迁移文件

Flyway 回调

创建空 SQL 回调

生成 Java 回调

部署迁移脚本

从运行微件运行迁移流程

从工具窗口运行迁移进程

从配置文件运行迁移进程

迁移状态

Flyway 运行配置

创建 Flyway 运行配置

参考：运行配置选项

必填选项

其他选项

参考：Flyway 插件设置

故障排除