# Flyway > For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/idea/llms.txt). > **TL;DR** > 必需插件： [Flyway](https://plugins.jetbrains.com/plugin/23740-flyway)（捆绑） [Flyway](https://documentation.red-gate.com/fd/getting-started-with-flyway-184127223.html) 是一款数据库迁移工具，可用于对数据库更改进行版本控制、跟踪和应用。 IntelliJ IDEA 提供如下对 Flyway 的支持： * 生成 [迁移脚本](#flyway-migrations)和 [回调脚本](#flyway-callbacks)的操作 * [快速导航](#migrations-quick-navigation)于 SQL 迁移和实体类之间 * 执行 SQL 迁移和回调至数据库的 [运行配置](#flyway-run-configuration) * 迁移文件命名模式的 [自定义](#flyway-settings) 在 IntelliJ IDEA 2024.1 版本之前，某些 Flyway 功能仅可通过 [JPA Buddy 插件](jpa-buddy.html) 使用。 以下视频演示了这些功能，它们现在可通过 Flyway 插件使用。 [Video](https://www.youtube.com/v/9wEJ29QIDyM) Procedure: 为现有项目添加 Flyway > **Tip:** > 如果想在 IntelliJ IDEA 中使用 Flyway 功能而不向构建文件添加依赖项，可以在 [参考：Flyway 插件设置](#flyway-settings) 中启用此功能。 1. 在编辑器中打开构建文件（ `pom.xml` 或 `build.gradle` ，具体取决于项目中使用的 [构建工具](build-tools.html)）。 2. 添加 Flyway 库，并确保其版本与项目的其余部分匹配： 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. （可选）如果要使用 Maven 或 Gradle 运行 Flyway 命令，请添加专用插件： Maven: ```XML org.flywaydb flyway-maven-plugin 13.1.0 ${YOUR_DATABASE_URL} ${YOUR_DATABASE_USERNAME} ${YOUR_DATABASE_PASSWORD} ``` 有关配置插件的更多信息，请参阅 [官方 Flyway 文档](https://documentation.red-gate.com/fd/maven-goal-277579365.html)。 Gradle (Groovy): ```GROOVY plugins { id 'org.flywaydb.flyway' version '13.1.0' } flyway { url = '' user = '' password = '' } ``` 有关配置插件的更多信息，请参阅 [官方 Flyway 文档](https://documentation.red-gate.com/fd/gradle-task-277579364.html)。 Gradle (Kotlin): ```KOTLIN plugins { id ("org.flywaydb.flyway") version "13.1.0" } flyway { url = "" user = "" password = "" } ``` 有关配置插件的更多信息，请参阅 [官方 Flyway 文档](https://documentation.red-gate.com/fd/gradle-task-277579364.html)。 4. 按 `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` (Visual Studio), `Ctrl+Shift+O` (Visual Studio (macOS)), `Ctrl+Shift+O` (NetBeans), `Ctrl+Shift+O` (Eclipse), `Ctrl+Shift+O` (Eclipse (macOS)) 导入更改。 有关使用构建工具的更多信息，请参阅 [Maven](maven-support.html) 或 [Gradle](gradle.html)。 ## Flyway 迁移 [Flyway 迁移](https://documentation.red-gate.com/fd/migrations-271585107.html)定义对数据库架构或数据的更改。 这些通常是 SQL 文件，但 Flyway 也支持基于 Java 和脚本的迁移。 IntelliJ IDEA 提供内置操作来生成以下类型的 Flyway 迁移： * [初始化迁移](#initialize-schema)：以当前形式捕获所选数据模型（数据库、持久化单元或映射上下文）。 结果是一个 DDL 脚本，可用于在空数据库中重新创建该数据模型。 * [差异迁移](#generate-migration-script)：捕获两个数据模型之间的差异：例如，当前数据库架构与代码中的实体映射之间的差异。 结果是一个 DDL 脚本，可以针对目标模型运行，使其与源匹配。 * [空迁移](#generate-empty-file)：创建一个遵循 Flyway 命名模式的空 SQL 文件。 * [Java 迁移](#java-migration)：创建一个 Java 类，该类扩展 Flyway 的 [BaseJavaMigration 类](https://javadoc.io/doc/org.flywaydb/flyway-core/latest/org/flywaydb/core/api/migration/BaseJavaMigration.html)，并包含 [migrate() 方法](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 在生成 Java 迁移时不会捕获数据模型或任何架构更改。 Procedure: 生成初始迁移 1. 打开 [Persistence](persistence-tool-window.html) 工具窗口。 2. 在工具窗口中，右键点击持久化单元、映射上下文或实体，然后选择 `![加号图标](https://resources.jetbrains.com/help/img/idea/2026.3/intellij.platform.ide.expui.general.add.svg) 新建 | ![带蓝色加号的数据库图标](https://resources.jetbrains.com/help/img/idea/2026.3/jpa-model.icons.newui.initLiquibaseChangelog.svg) Flyway Init 迁移……` 。 3. 在打开的 Flyway 初始化架构迁移 对话框中，选择迁移应基于的数据模型： * 模型 ：来自以下项之一的实体映射： * [持久化单元](persistence-tool-window.html#create-persistence-unit)（在 JPA 和 Spring Data JPA 项目中） * [映射上下文](persistence-tool-window.html#create-mapping-context)（在 Spring Data JDBC 项目中） * 数据库 ：来自 [已连接的数据库](connecting-to-a-database.html) 的架构 ![Flyway 初始化架构迁移对话框](https://resources.jetbrains.com/help/img/idea/2026.3/flyway_init_migration_action.png) 根据所选内容，IntelliJ IDEA 会自动填写持久化单元、映射上下文或数据库连接，必要时可以更改。 4. 点击 OK 。 5. 在打开的 [Flyway 迁移预览对话框](#migration-preview-window)中，配置迁移并点击 保存 。 Procedure: 生成差异迁移 1. 确保 IntelliJ IDEA 已 [连接到数据库](managing-data-sources.html#create_a_data_source)。 > **Tip:** > 如果项目使用 [Spring](spring-support.html)、 [Micronaut](micronaut.html) 或 [Quarkus](quarkus.html)，可以直接从配置文件（ `application.properties` 或 `application.yml` ）快速创建数据库连接。 > > > > 为此，请在编辑器中打开该文件，然后在编辑器装订区域中点击 ![数据库连接图标](https://resources.jetbrains.com/help/img/idea/2026.3/javaee-persistence-impl.icons.expui.add-db-from-config.svg) 从现有属性创建新数据源 。 2. 打开 [数据库](database-tool-window.html) 工具窗口，右键点击数据库或表，然后选择 ![带有两个蓝色箭头的数据库图标](https://resources.jetbrains.com/help/img/idea/2026.3/jpa-model.icons.newui.diffLiquibaseChangelog.svg) 创建 Flyway 迁移… 。 * 或者，打开 [持久化](persistence-tool-window.html) 工具窗口，右键点击持久化单元、映射上下文或实体，然后选择 `![加号图标](https://resources.jetbrains.com/help/img/idea/2026.3/intellij.platform.ide.expui.general.add.svg) 新建 | ![带有两个蓝色箭头的数据库图标](https://resources.jetbrains.com/help/img/idea/2026.3/jpa-model.icons.newui.diffLiquibaseChangelog.svg) Flyway 迁移……` 。 3. 在打开的 Flyway 差异迁移 对话框中，选择要比较的数据模型： * 源(referenceURL) (当前数据模型)： * 数据库 ：来自 [已连接的数据库](connecting-to-a-database.html) 的架构 * 模型 ：来自以下项之一的实体映射： * [持久化单元](persistence-tool-window.html#create-persistence-unit)（在 JPA 和 Spring Data JPA 项目中） * [映射上下文](persistence-tool-window.html#create-mapping-context)（在 Spring Data JDBC 项目中） * 目标(URL) (先前数据模型)： * 数据库 ：来自已连接数据库的架构 * 快照 ：来自 [数据模型快照](database-versioning.html#generate-data-model-snapshot) 的架构 ![迁移脚本窗口](https://resources.jetbrains.com/help/img/idea/2026.3/flyway_migration_script_window.png) 如果选择 数据库 或 模型 ，IntelliJ IDEA 会自动填写持久化单元、映射上下文或数据库连接，必要时可以更改。 > **Tip:** > 如果经常在相同的数据库连接与持久化单元或映射上下文之间生成差异迁移，可以选择 持久性单元的默认连接 ，以便 IntelliJ IDEA 今后记住此关联。 4. 点击 OK 。 5. 在打开的 [Flyway 迁移预览对话框](#migration-preview-window)中，配置迁移并点击 保存 。 Procedure: 创建空迁移 除了生成已填充 DDL 脚本的迁移外，还可以创建空 SQL 迁移并自行填写。 1. 打开 [项目](project-tool-window.html) 工具窗口（ `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+Alt+L` (Visual Studio), `⌘ ⌥ L` (Visual Studio (macOS)), `Ctrl+1` (NetBeans), `Alt+1` (Eclipse), `Alt+1` (Eclipse (macOS))）。 2. 右键点击包含 SQL 迁移的文件夹，然后选择 `新建 | ![紫色数据库图标](https://resources.jetbrains.com/help/img/idea/2026.3/intellij.liquibase.core.icons.newui.sqlFile.svg) Flyway 空迁移` 。 * 或者，选择文件夹，按 `Alt+Insert` (Windows), `⌘ N` (macOS), `⌃ N` (IntelliJ IDEA Classic (macOS)), `⌘ N` (macOS System Shortcuts), `Alt+Insert` (XWin), `Alt+Insert` (GNOME), `Alt+Insert` (KDE), `Alt+Insert` (Emacs), `Alt+Insert` (Sublime Text), `⌘ N` (Sublime Text (macOS)), `Alt+Insert` (Visual Studio), `⌘ ⌃ N` (Visual Studio (macOS)), `Alt+Insert` (NetBeans), `Alt+Insert` (Eclipse), `⌘ N` (Eclipse (macOS))，然后选择 ![紫色数据库图标](https://resources.jetbrains.com/help/img/idea/2026.3/intellij.liquibase.core.icons.newui.sqlFile.svg) Flyway 空迁移 。 > **Note:** > 如果此操作不可用，请参阅 [故障排除指南](#cannot-create-empty-migration)。 IntelliJ IDEA 会根据 [Flyway 插件设置](#flyway-settings)自动填写前缀和版本，并在编辑器中打开新迁移。 SQL 迁移文件支持对表名称的快速导航。 可以跳转到表的实体类、首次引入该表的迁移，或（如果数据库已在 数据库 工具窗口中连接）数据库中该表的 DDL 定义。 要在迁移文件中使用快速导航，请将文本光标放在表名称处，按 `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)), `F12` (Visual Studio), `F12` (Visual Studio (macOS)), `Ctrl+B` (NetBeans), `F3` (Eclipse), `F3` (Eclipse (macOS))，然后从 选择声明 列表中选择目标。 请注意，不能对 `CREATE TABLE` 语句调用快速导航。 ![导航到表声明选项](https://resources.jetbrains.com/help/img/idea/2026.3/flyway_choose_declaration.png) ### Flyway 迁移预览对话框 Flyway 迁移预览 对话框可用于检查生成的 DDL 语句、将其整理到迁移中，并配置保存方式。 ![flyway-preview](https://resources.jetbrains.com/help/img/idea/2026.3/flyway_versioned_migration_preview.png) 对话框左侧显示生成的架构更改树。 每项更改都会按其 [危险级别](database-versioning.html#danger-level-settings) 进行颜色编码，并标有表示更改类型的图标。 如果选择特定更改，IntelliJ IDEA 会在对话框右侧显示其 DDL 语句。 更改树上方的图标可用于管理生成的更改和迁移： ![添加迁移](https://resources.jetbrains.com/help/img/idea/2026.3/jpa-model.icons.newui.addChangelog.svg) : 添加迁移 : : 创建附加迁移。 ![从迁移中移除](https://resources.jetbrains.com/help/img/idea/2026.3/jpa-model.icons.newui.removeDropDown.svg) : 从迁移中移除 : : 从迁移中移除所选更改，并可选择将它们移动到 已忽略 部分，以便将它们从将来的迁移中排除。 ![](https://resources.jetbrains.com/help/img/idea/2026.3/jpa-model.icons.newui.restoreFromIgnore.svg) : 从忽略状态还原 : : 将所选更改从 已忽略 部分移动到所选迁移。 ![](https://resources.jetbrains.com/help/img/idea/2026.3/jpa-model.icons.newui.moveToAnotherChangelog.svg) : 移至另一个迁移 : : 将所选更改移动到另一个迁移。 : : : : 如果在对话框中没有其他迁移时选择此选项，IntelliJ IDEA 会自动创建一个。 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app-client.expui.inline.inlineSettings.svg) : 显示其他操作 : : 一次性处理多个更改：具有特定危险级别的 全选 、 全部展开 或 全部收起 。 > **Tip:** > 也可以通过将更改拖到所需部分来整理它们。 对话框右侧显示当前所选更改生成的 DDL 语句。 如果选择的是迁移(而不是单个更改)，还可以使用此部分指定保存方式： | 条目 | 描述 | | --- | --- | | 另存为 | 可以选择将迁移保存为 SQL 文件、 [临时文件](scratches.html)，复制到剪贴板，或在 [查询控制台](query-consoles.html) 中打开。 | | 目录 | 选择 IntelliJ IDEA 应保存 SQL 文件的位置。 | | 文件名 | 设置文件名。 > **Note:** > 迁移必须遵循既定命名模式，以便 Flyway 识别如何处理它们。 请访问 [Flyway 官方 GitHub 页面](https://github.com/flyway/flywaydb.org/blob/gh-pages/documentation/concepts/migrations.md#naming)了解更多信息。 IntelliJ IDEA 会根据 [Flyway 插件设置](#flyway-settings)自动填写前缀和版本。 | ### 基于 Java 的迁移 [基于 Java 的迁移](https://documentation.red-gate.com/fd/java-based-migrations-273973387.html)是 SQL 迁移的替代方案，适用于无法轻松用 SQL 表达的更改。 它们是实现 Flyway 的 `JavaMigration` 接口的 Java 类(通常通过扩展 `BaseJavaMigration` 类实现)，并遵循 Flyway 的 [命名模式](https://github.com/flyway/flywaydb.org/blob/gh-pages/documentation/concepts/migrations.md#naming-1)。 Procedure: 生成 Java 迁移文件 1. 请按 `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+Shift+A` (Visual Studio), `⌘ ⇧ A` (Visual Studio (macOS)), `Ctrl+I` (NetBeans), `Ctrl+Shift+A` (Eclipse), `⌘ 3` (Eclipse (macOS))，输入 `Flyway Java 迁移` 并按 `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` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS))。 2. 在打开的 Flyway Java 迁移 对话框中，设置文件名。 IntelliJ IDEA 会根据 [Flyway 插件设置](#flyway-settings)自动填写前缀和版本。 ![flyway-java-migration](https://resources.jetbrains.com/help/img/idea/2026.3/flyway-java-migration.png) 如有需要，更改应创建迁移的源根或软件包。 3. 点击 OK 。 IntelliJ IDEA 会在编辑器中打开生成的 Java 迁移类。 ```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 回调 当 [运行迁移流程](#deploy-migrations)时，Flyway 会依次执行待处理迁移，一旦所有迁移应用完成则结束流程。 虽然这种流程适合大多数常见场景，但更复杂的项目可能需要在每次迁移或迁移生命周期的特定点运行额外逻辑。 Flyway 通过 [回调](https://documentation.red-gate.com/fd/callbacks-275218509.html) 支持此类要求。 IntelliJ IDEA 提供内置操作来生成以下类型的 Flyway 回调： * [SQL 回调](#generate-sql-callback)：创建一个具有已识别回调事件名称的空 SQL 文件。 * [Java 回调](#generate-java-callback)：生成一个实现 [回调 接口](https://javadoc.io/doc/org.flywaydb/flyway-core/latest/org/flywaydb/core/api/callback/Callback.html)并包含 [所有方法](https://javadoc.io/doc/org.flywaydb/flyway-core/latest/org/flywaydb/core/api/callback/GenericCallback.html)初始实现的 Java 类。 Procedure: 创建空 SQL 回调 1. 请按 `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+Shift+A` (Visual Studio), `⌘ ⇧ A` (Visual Studio (macOS)), `Ctrl+I` (NetBeans), `Ctrl+Shift+A` (Eclipse), `⌘ 3` (Eclipse (macOS))，输入 `Flyway SQL 回调` 并按 `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` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS))。 2. Flyway SQL 回调 对话框将打开。 IntelliJ IDEA 会自动填写将要创建回调的源根目录和目录，但如有需要可更改。 ![Flyway SQL 回调](https://resources.jetbrains.com/help/img/idea/2026.3/flyway-sql-callback.png) 3. 点击 ![带有三个水平点的按钮](https://resources.jetbrains.com/help/img/idea/2026.3/intellij.platform.ide.general.ellipsis.svg) 字段旁的 回调事件 。 将会打开 选择回调事件 对话框，可在其中选择回调将在迁移生命周期的哪个阶段运行。 ![回调事件](https://resources.jetbrains.com/help/img/idea/2026.3/flyway-choose-callback-event.png) 每个回调事件旁的图标指示其是否可用于 Flyway Community Edition（ CE ），或是否需要 Enterprise Edition（ TE ）。 4. （可选）添加回调描述。 该值将附加到文件名称。 5. 点击 OK 。 IDE 会在编辑器中打开回调文件。 您现在可以添加将在所选回调事件期间执行的 SQL 语句。 > **Note:** > 要让 Flyway 在运行时识别您的 SQL 回调，需要配置 [Flyway 回调位置设置](https://documentation.red-gate.com/fd/flyway-callback-locations-setting-313492695.html)。 Procedure: 生成 Java 回调 1. 请按 `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+Shift+A` (Visual Studio), `⌘ ⇧ A` (Visual Studio (macOS)), `Ctrl+I` (NetBeans), `Ctrl+Shift+A` (Eclipse), `⌘ 3` (Eclipse (macOS))，输入 `Flyway Java 回调` 并按 `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` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS))。 2. Flyway Java 回调 对话框将打开。 其选项决定回调类名称、位置以及 [接口方法](https://javadoc.io/doc/org.flywaydb/flyway-core/latest/org/flywaydb/core/api/callback/GenericCallback.html#method-detail) 的初始实现。 ![Flyway Java 回调](https://resources.jetbrains.com/help/img/idea/2026.3/flyway-java-callback.png) 配置回调选项： | 条目 | 描述 | | --- | --- | | 名称 | 指定类名称。 | | 回调名称 | 指定回调名称。 这将成为 `getCallbackName()` 方法的返回值。 | | 回调事件 | 指定 Flyway 在迁移生命周期的哪些点将从该类调用 `handle()` 方法。 IntelliJ IDEA 会自动将它们添加到 `supports()` 方法。 可手动输入 [事件名称](https://documentation.red-gate.com/flyway/reference/callback-events)，或点击 ![带有三个水平点的按钮](https://resources.jetbrains.com/help/img/idea/2026.3/intellij.platform.ide.general.ellipsis.svg)，在 选择回调事件 对话框中选择。 | | 可以在事务中处理 | 如果希望 `canHandleInTransaction()` 方法返回 `true` ，请选择此选项。 | | 源根 | 选择要创建回调的源根。 | | 软件包 | 选择要创建回调的软件包。 > **Note:** > Flyway 默认查找 Java 回调的软件包为 `db.callback` 。 请确保在此软件包中创建 Java 回调，或更改 [Flyway 回调设置](https://documentation.red-gate.com/fd/flyway-callbacks-setting-277578977.html)。 | 3. 点击 OK 。 IntelliJ IDEA 会在编辑器中打开生成的 Java 回调类。 ```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 运行配置](#flyway-run-configuration) 触发迁移流程，让数据库与代码保持同步。 可以从 IntelliJ IDEA 中的多个位置启动此运行配置。 Procedure: 从运行微件运行迁移流程 > **Note:** > 要使用此功能，需先 [创建 Flyway 运行配置](#create-run-configuration)。 * 如果运行微件中已选择 Flyway 运行配置，请点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.run.run.svg) 运行 。 * 或者按 `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)), `Ctrl+F5` (Visual Studio), `⌃ F5` (Visual Studio (macOS)), `F6` (NetBeans), `Alt+Shift+X` (Eclipse), `⌘ ⇧ F11` (Eclipse (macOS))。 * 如果运行微件中选择了其他配置，请点击其名称。 在弹出的窗口中，找到 Flyway 运行配置，并点击其旁的 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.run.run.svg) 运行 。 * 或者按 `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)), `Ctrl+Alt+Shift+R` (Visual Studio), `⌘ ⌥ ⇧ R` (Visual Studio (macOS)), `Alt+Shift+F10` (NetBeans), `Alt+Shift+F10` (Eclipse), `⌃ ⌥ R` (Eclipse (macOS))。 在弹窗中选择 Flyway 运行配置。 IntelliJ IDEA 会在 [运行](run-tool-window.html) 工具窗口中启动运行配置。 Procedure: 从工具窗口运行迁移进程 > **Note:** > 如果使用此功能时不存在现有的 Flyway 运行配置，IDE 将尝试根据配置文件（ `flyway.conf` 、 `application.properties` 或 `application.yml` ）创建一个。 可从以下工具 Windows 启动 Flyway 运行配置： * [持久性](persistence-tool-window.html)工具窗口： * 右键点击工具窗口中的任意位置，然后选择 ![](https://resources.jetbrains.com/help/img/idea/2026.3/jpa-model.icons.newui.liquibaseUpdate.svg) 运行 Flyway 迁移… 。 * [数据库](database-tool-window.html)工具窗口： * 转到工具栏并选择 ![](https://resources.jetbrains.com/help/img/idea/2026.3/jpa-model.icons.newui.liquibaseUpdate.svg) 运行 Flyway 迁移… 。 * 右键点击数据库、架构或表，然后选择 ![](https://resources.jetbrains.com/help/img/idea/2026.3/jpa-model.icons.newui.liquibaseUpdate.svg) 运行 Flyway 迁移… 。 * [项目](project-tool-window.html) 工具窗口： * 右键点击 SQL 迁移文件所在目录并选择 `![](https://resources.jetbrains.com/help/img/idea/2026.3/intellij.platform.ide.expui.run.run.svg) 运行 | ![](https://resources.jetbrains.com/help/img/idea/2026.3/intellij.flyway.core.icons.flyway.svg) Flyway` 。 > **Note:** > 若已存在 Flyway 运行配置，该操作将会显示在 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app-client.expui.run.run.svg) 运行“<配置名称>” 下。 IntelliJ IDEA 会在 [运行](run-tool-window.html) 工具窗口中启动运行配置。 Procedure: 从配置文件运行迁移进程 可以从以下文件启动 Flyway 运行配置： * Flyway 配置文件（ `flyway.conf` ） * [Spring Boot](spring-boot.html) 配置文件（ `application.properties` 或 `application.yml` ） 1. 在编辑器中打开配置文件。 2. 在 [装订区域](editor-gutter.html)中，点击 ![指向右侧的绿色三角形图标](https://resources.jetbrains.com/help/img/idea/2026.3/intellij.platform.ide.expui.run.run.svg) 运行 Flyway 迁移… 。 > **Note:** > 如果此图标未显示在配置文件中，请参阅 [故障排除指南](#cannot-run-migrations-from-config-file)。 IntelliJ IDEA 会在 [运行](run-tool-window.html) 工具窗口中启动运行配置。 > **Tip:** > 如果迁移过程失败， 运行 工具窗口会提供一个指向出错迁移的链接。 > > > > ![导致在运行工具窗口中错误高亮的迁移名称。](https://resources.jetbrains.com/help/img/idea/2026.3/flyway_migrate_error_location.png) > > 点击该链接，IDE 会在编辑器中打开迁移，并将文本光标定位到导致错误的 SQL 语句处。 ### 迁移状态 通常，如果要检查哪些迁移已执行以及结果如何，需要运行 Flyway 的 [info 命令](https://documentation.red-gate.com/fd/info-277578881.html)或检查数据库中的 [架构历史记录表](https://documentation.red-gate.com/fd/flyway-schema-history-table-273973417.html)。 IntelliJ IDEA 提供更快捷的替代方案，直接在 IDE 中显示 SQL 迁移状态。 整个迁移文件的状态会显示在 项目 工具窗口（ `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+Alt+L` (Visual Studio), `⌘ ⌥ L` (Visual Studio (macOS)), `Ctrl+1` (NetBeans), `Alt+1` (Eclipse), `Alt+1` (Eclipse (macOS))）中。 ![项目工具窗口中的 Flyway 图标，已应用迁移显示勾选，迁移失败显示感叹号](https://resources.jetbrains.com/help/img/idea/2026.3/flyway_status_icons.png) 每个迁移由 Flyway 徽标表示（ ![Flyway 徽标图标](https://resources.jetbrains.com/help/img/idea/2026.3/intellij.flyway.core.icons.flyway.svg)），其状态通过徽标右下角的小图标反映： | 图标 | 状态 | | --- | --- | | ![绿色勾选图标](https://resources.jetbrains.com/help/img/idea/2026.3/intellij.platform.ide.expui.status.success.svg) | 迁移已成功应用于数据库。 | | ![红色感叹号图标](https://resources.jetbrains.com/help/img/idea/2026.3/intellij.platform.ide.expui.status.error.svg) | 迁移已执行，但某个 SQL 语句失败。 若失败的迁移被红色下划线标记，可将鼠标悬停在文件名称上查看更多错误信息。 ![在编辑器装订区域紧邻 SQL 语句旁显示红色感叹号](https://resources.jetbrains.com/help/img/idea/2026.3/flyway_error_details.png) 若要检查是哪个 SQL 语句引发错误，请在编辑器中打开带有下划线的迁移，并查找装订区域中的红色感叹号。 ![在编辑器装订区域紧邻 SQL 语句旁显示红色感叹号](https://resources.jetbrains.com/help/img/idea/2026.3/flyway_error_gutter_icon.png) 可以点击装订区域图标以再次查看错误详细信息。 > **Note:** > 只有在通过以下任一方式从 IDE 运行迁移进程时，下划线和装订区域图标才会出现： > > > > * [启动 Flyway 运行配置](#deploy-migrations) > > * [启动 Spring Boot 应用程序](spring-boot.html#run-a-spring-boot-application) > > * [运行 flyway:migrate Maven 目标](work-with-maven-goals.html#run_goal) > > * [运行 flywayMigrate Gradle 任务](work-with-gradle-tasks.html#gradle_tasks) > > > > 重启 IDE 后，下划线和图标都会消失。 | | (无) | 迁移尚未执行。 > **Note:** > 如迁移未显示状态图标，请参考 [故障排除指南](#no-status-icons)。 | ## Flyway 运行配置 Flyway [运行配置](run-debug-configuration.html)允许无需启动整个应用程序或使用终端，即可针对已连接数据库执行 SQL 迁移文件和回调。 在底层，该配置会运行 [Flyway migrate 命令](https://documentation.red-gate.com/fd/migrate-277578887.html)。 Procedure: 创建 Flyway 运行配置 1. 打开 运行/调试配置 对话框： * 在主工具栏，点击 [运行微件](guided-tour-around-the-user-interface.html#toolbar)并选择 编辑配置… 。 * 或者，转到 `运行 | 编辑配置…` 。 2. 在对话框左侧，选择 `![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg) 添加新配置 | ![](https://resources.jetbrains.com/help/img/idea/2026.3/intellij.flyway.core.icons.flyway.svg) Flyway` 。 3. 设置 [运行配置选项。](#run-configuration-options) ![Flyway 运行配置选项](https://resources.jetbrains.com/help/img/idea/2026.3/workspace.xml` 。 | #### 必填选项 | 条目 | 描述 | | --- | --- | | 数据库连接 | 指定 Flyway 在运行迁移时应目标哪个数据库。 需从 数据库 工具窗口选择现有 [数据源](managing-data-sources.html)，或点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app-client.expui.general.add.svg) 新建。 | | 目录 | 指定包含 SQL 迁移的目录路径。 从 [官方 Flyway 文档](https://documentation.red-gate.com/fd/flyway-locations-setting-277579008.html)详细了解此设置。 | #### 其他选项 要将这些选项添加到运行配置中，请在对话框右侧选择 修改选项 。 | 条目 | 描述 | | --- | --- | | 迁移时设置基线 | 决定当尝试在没有历史表的非空数据库架构上执行迁移时，Flyway 应如何处理： * 如果选择此选项，Flyway 会创建历史表，将现有架构标记为基线，并仅在版本为 2 及以上时执行迁移。 * 如果取消选择此选项，Flyway 将抛出错误并不执行迁移。 从 [官方 Flyway 文档](https://documentation.red-gate.com/fd/flyway-baseline-on-migrate-setting-277578974.html)详细了解此设置。 | | 架构 | 指定 Flyway 在运行迁移时应目标哪个数据库架构。 如需填写多个值，请用逗号分隔。 从 [官方 Flyway 文档](https://documentation.red-gate.com/fd/environment-schemas-setting-277578932.html)详细了解此设置。 | ## 参考：Flyway 插件设置 IntelliJ IDEA 中的 Flyway 插件设置允许配置 IDE 在生成迁移时使用的命名模式。 > **Note:** > 插件设置中的默认值与 Flyway 识别的默认值一致。 如果在 IntelliJ IDEA 中更改了这些值，请确保更新 [相应的 Flyway 设置](https://documentation.red-gate.com/fd/flyway-namespace-277578913.html#FlywayNamespace-Migrationlocationandnamingsettings)。 否则，您的迁移可能会被错误处理。 如需访问 Flyway 插件设置，请打开 设置 （ `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` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))），然后转到 `工具 | 数据库版本管理 | Flyway` 。 ![设置对话框中的 Flyway 设置](https://resources.jetbrains.com/help/img/idea/2026.3/flyway-settings.png) 您可以配置以下设置： | 条目 | 描述 | | --- | --- | | 迁移前缀 | 指定 IDE 生成迁移文件名称时应使用的前缀。 > **Warning:** > 除可在 IntelliJ IDEA 中生成的版本化迁移外，Flyway 还支持 [其他类型的迁移](https://documentation.red-gate.com/fd/migrations-271585107.html)。 每种类型都会映射到不同的前缀。 默认情况下，Flyway 使用以下映射： > > > > * B：基线迁移 > > * R：可重复迁移 > > * U：撤销迁移 > > * V：版本化迁移 > > > > 如果希望使用不同前缀，请确保更新 [Flyway 前缀设置](https://documentation.red-gate.com/fd/flyway-namespace-277578913.html#FlywayNamespace-Migrationlocationandnamingsettings)。 否则，您的迁移可能会被错误处理。 | | 版本模式 | 指定 IDE 设置文件版本时应使用的模式。 可包含以下宏： * `#increment(, , )` ：使用数字序列生成版本。 * `start` ：首个迁移的版本号 * `step` ：每个版本号的递增值 * `decimalFormat` ：用于格式设置版本号的 [DecimalFormat](https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/text/DecimalFormat.html) 模式 * `#date()` ：使用当前系统日期生成版本。 * `simpleDateFormat` ：用于格式设置日期的 [SimpleDateFormat](https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/text/SimpleDateFormat.html) 模式 * `${semVer.}` ：使用项目构建文件中的 [语义版本](https://en.wikipedia.org/wiki/Software_versioning#Semantic_versioning)生成版本。 * `getterMethod` ：提取语义版本特定段的方法。 以下是 `1.2.3-SNAPSHOT+build4` 版本的示例： * `${semVer.getRawVersion()}` ：1.2.3-快照+build4 * `${semVer.getMajor()}` ：1 * `${semVer.getMinor()}` ：2 * `${semVer.getPatch()}` ：3 * `${semVer.getPreRelease()}` ：快照 | | 迁移分隔符 | 指定文件版本与描述之间的分隔符。 > **Note:** > 如果更改此值，请相应更新 [Flyway 迁移分隔符设置](https://documentation.red-gate.com/fd/flyway-sql-migration-separator-setting-277579038.html)。 | | 迁移描述 | 指定将在每个文件名称分隔符后添加的描述。 | | 无依赖项使用 Flyway | 如果想在 IntelliJ IDEA 中使用 Flyway 功能而不向构建文件添加依赖项，请选择此选项。 | ## 故障排除 Spring 项目: 无法创建空迁移 : 确保： : : : : * 已向项目构建文件 [添加 Flyway 依赖](#add-to-existing-project)。 : : * 已 [连接到对应数据库](connecting-to-a-database.html)，且连接在 数据库 工具窗口中处于活动状态。 : : * 配置文件（ `application.properties` 或 `application.yml` ）满足如下条件： * `spring.flyway.locations` 指向调用该操作的目录或其父目录。 * `spring.flyway.url` 或 `spring.datasource.url` 与用于连接数据库的 URL 匹配。 无法从配置文件运行迁移进程 : 确保： : : : : * 已向项目构建文件 [添加 Flyway 依赖](#add-to-existing-project)。 : : * 已 [连接到对应数据库](connecting-to-a-database.html)，且连接在 数据库 工具窗口中处于活动状态。 : : * 配置文件（ `application.properties` 或 `application.yml` ）满足如下条件： * `spring.flyway.locations` 指向包含迁移文件的目录。 * `spring.flyway.url` 或 `spring.datasource.url` 与用于连接数据库的 URL 匹配。 迁移不显示状态图标 : 确保： : : : : * 已向项目构建文件 [添加 Flyway 依赖](#add-to-existing-project)。 : : * 已 [连接到对应数据库](connecting-to-a-database.html)，且连接在 数据库 工具窗口中处于活动状态。 : : * 配置文件（ `application.properties` 或 `application.yml` ）满足如下条件： * `spring.flyway.locations` 指向包含迁移文件的目录。 * `spring.flyway.url` 或 `spring.datasource.url` 与用于连接数据库的 URL 匹配。 * `spring.flyway.default-schema` 与迁移的数据库架构匹配。 : : * 已经 [运行迁移进程](#deploy-migrations)，其结果已记录在 [架构历史记录表](https://documentation.red-gate.com/fd/flyway-schema-history-table-273973417.html)中。 非 Spring 项目: 无法创建空迁移 : 确保： : : : : * 已向项目构建文件 [添加 Flyway 依赖](#add-to-existing-project)。 : : * 已 [连接到对应数据库](connecting-to-a-database.html)，且连接在 数据库 工具窗口中处于活动状态。 : : * 配置文件（ `flyway.conf` ）符合以下条件： * `flyway.locations` 指向调用该操作的目录或其父目录。 * `flyway.url` 与用于连接数据库的 URL 匹配。 无法从配置文件运行迁移进程 : 确保： : : : : * 已向项目构建文件 [添加 Flyway 依赖](#add-to-existing-project)。 : : * 已 [连接到对应数据库](connecting-to-a-database.html)，且连接在 数据库 工具窗口中处于活动状态。 : : * 配置文件（ `flyway.conf` ）符合以下条件： * `flyway.locations` 指向包含迁移文件的目录。 * `flyway.url` 与用于连接数据库的 URL 匹配。 迁移不显示状态图标 : 确保： : : : : * 已向项目构建文件 [添加 Flyway 依赖](#add-to-existing-project)。 : : * 已 [连接到对应数据库](connecting-to-a-database.html)，且连接在 数据库 工具窗口中处于活动状态。 : : * 配置文件（ `flyway.conf` ）符合以下条件： * `flyway.locations` 指向包含迁移文件的目录。 * `flyway.url` 与用于连接数据库的 URL 匹配。 * `flyway.defaultSchema` 与迁移的数据库架构匹配。 : : * 已经 [运行迁移进程](#deploy-migrations)，其结果已记录在 [架构历史记录表](https://documentation.red-gate.com/fd/flyway-schema-history-table-273973417.html)中。 ## See also ### JetBrains 博客文章 [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/) ### 外部链接 [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) ### 操作指南 [Connect to a database](connecting-to-a-database.html) [Create a persistence unit manually](persistence-tool-window.html#create-persistence-unit)