IntelliJ IDEA 2026.1 Help

Flyway

Flyway 是一款数据库迁移工具，可进行版本控制、跟踪并应用数据库更改。 IntelliJ IDEA 通过专用操作生成 迁移 （定义数据库更改）和 回调 （在迁移生命周期特定环节执行）来支持 Flyway。

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

为现有项目添加 Flyway

  1. 在编辑器中打开构建文件（ pom.xml 或 build.gradle ，取决于您在项目中使用的构建工具）。

  2. 请添加以下依赖项，但请确保版本与项目中的其他部分保持一致：

    <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") }

  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 配置文档。

  4. 按 Ctrl+Shift+O 导入更改。

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

Flyway 迁移

Flyway 迁移定义数据库架构或数据的更改。 通常这些迁移使用 SQL 编写，但 Flyway 也支持基于 Java 及脚本的迁移。 IntelliJ IDEA 提供用于生成空 基于 Java 的迁移和两种 SQL 架构迁移的内置操作：

  • 初始迁移 ：捕获当前表（数据库或持久化单元）的数据模型。 结果为 DDL 脚本，可用于在空数据库中重建该数据模型。

  • 差异迁移 ：捕获两个数据模型之间的差异，比如当前数据库架构与代码中的实体映射之间的差异。 结果为 DDL 脚本，可用于将目标模型变为与源模型一致。

生成初始迁移

  1. 打开 持久性 工具窗口。

  2. 在工具窗口中，右键点击持久化单元或实体，然后选择 新建(N) | Flyway 初始迁移…。

  3. 在打开的 Flyway 初始化架构迁移 对话框中，选择迁移应基于的数据模型：

    init-schema-changelog

    根据选择，IntelliJ IDEA 会自动填写持久化单元或数据库连接，您可按需更改。

  4. 点击 确定(O)。

  5. 在打开的 Flyway 迁移预览 对话框中，配置迁移并点击 保存。

生成差异迁移

  1. 打开 持久性 工具窗口，右键点击持久化单元或实体，然后选择 新建(N) | Flyway 迁移…。

    • 或者，打开 数据库 工具窗口，右键点击数据库或表，然后选择 创建Flyway 迁移…。

  2. 在打开的 Flyway 差异迁移 对话框中，选择要比较的数据模型：

    • 来源 （当前数据模型）：

    • 目标 （前一个数据模型）：

      • 数据库 ：来自已连接数据库的架构

      • 快照 ：来自 数据模型快照的架构

    迁移脚本窗口

    如果选择 数据库 或 模型 ，IntelliJ IDEA 会自动填写数据库连接或持久化单元，您可按需更改。

  3. 点击 确定(O)。

  4. 在打开的 Flyway 迁移预览 对话框中，配置迁移并点击 保存。

迁移文件支持表名快捷导航。 可以跳转到表的实体类、第一个引入表的迁移，或（如 已附加数据源到该文件）连接数据库中的该表 DDL 定义。

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

导航到表声明选项

Flyway 迁移预览对话框

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

flyway-preview

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

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

添加迁移

添加迁移

创建额外的迁移。

从迁移中移除

从迁移中移除

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

从忽略状态还原

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

移至另一个迁移

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

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

显示其他操作

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

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

条目

描述

另存为

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

目录

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

文件名

设置文件名。

IntelliJ IDEA 会根据 Flyway 设置 自动填写前缀和编号。

基于 Java 的迁移

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

生成空的 Java 迁移

  1. 请按 Ctrl+Shift+A ，输入 Flyway Java 迁移 ，再按 Enter。

  2. 在打开的 Flyway Java 迁移 对话框中，设置文件名。 IntelliJ IDEA 会根据 Flyway 设置 自动填写前缀和编号。

    flyway-java-migration

    如有需要，请更改迁移应创建的源码根目录或软件包。

  3. 点击 OK。

IntelliJ IDEA 会生成以下 Java 类：

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

Flyway 回调函数

虽然迁移对于大多数需求来说已经足够，但在某些情况下，您需要反复执行相同的操作。 借助 IntelliJ IDEA，可生成 Flyway 支持的所有事件。

生成 SQL Callback

  1. 按 Ctrl+Shift+A ，开始输入 Flyway SQL 回调。

  2. 在打开的窗口中，选择生成文件的源根目录和目录。

    Flyway SQL 回调

  3. 在 回调事件 字段中，选择 Flyway 支持的事件之一。

    回调事件

回调还可以选择包含描述。 描述 字段的值会附加到回调名称。

生成 Java 回调

  1. 在编辑器中打开一个 Java 文件。

  2. 按 Ctrl+Shift+A ，开始输入 Flyway Java 回调。

  3. 在打开的窗口中，输入类名和回调名称并选择回调事件。 选择类源根目录和包。

    使用 可以在事务中处理 复选框来指定 canHandleInTransaction 重写方法应返回 true 还是 false。

    Flyway Java 回调

Flyway 设置

每次创建空迁移或差异迁移时，IntelliJ IDEA 会根据 flyway 命名模式 生成文件名。 在 IDE 设置 (Ctrl+Alt+S )中，您可以配置名称生成的值。

Flyway 设置窗口

  • 迁移前缀。 默认值为 V。

  • 版本模式。 在连字符之后，展示了生成序列的示例。

  • 迁移分隔符。 默认值为"_"。

  • 迁移描述。

以下变量和宏在模板中可用：

  • #date([format]) – 以指定的 SimpleDateFormat 表示的当前系统日期。 例如， #date(\"yyyy-MM-dd\") 返回的日期格式为 2020-12-31。

  • #increment([start], [step], [decimalFormat]) — 用于保持名称唯一的数字。 start 值用于第一个文件，并在每个后续文件中按步长递增。 decimalFormat 参数指定了该数字的 DecimalFormat格式。 例如， #increment(1.0, 0.1, \"#.0\") 返回的值格式为 1.1、1.2、1.3 等。

  • semVer — 项目的语义化版本（又称 SemVer）是一种被广泛采用的版本方案，使用由三位数字（主、次、补丁）组成的序列，以及可选的预发布标签和可选的构建元标签。 该对象包含以下方法（示例中的完整版本为 1.2.3-SNAPSHOT+meta）：

    • ${semVer.getRawVersion()} ：1.2.3-SNAPSHOT

    • ${semVer.getMajor()} ：1

    • ${semVer.getMinor()} ：2

    • ${semVer.getPatch()} ：3

    • ${semVer.getPreRelease()} ：SNAPSHOT

    • ${semVer.getMeta()} ：元数据

2026年 3月 24日
Liquibase应用服务器