首页/资讯中心/详情

还在手动改数据库？Flyway 自动化迁移实战指南 - lxr

还在手动改数据库？Flyway 自动化迁移实战指南 - lxr
📅 发布时间：2026/6/20 16:19:04

Flyway 操作文档

文档目标：

  1. 作为团队的规范文档，确保团队所有成员遵循相同的操作规范。
  2. 介绍 Flyway 相关的操作说明，包括编写 SQL 迁移脚本的规范、回滚策略等，确保团队在使用 Flyway 时的统一性和一致性。

Flyway 的引入与相关配置

在 Maven 中引入相应的模块：

<dependency><groupId>org.flywaydb</groupId><artifactId>flyway-core</artifactId>
</dependency>

在 application.yml 文件中添加以下配置：

flyway:enabled: truebaseline-on-migrate: trueclean-on-validation-error: falsesql-migration-prefix: Vsql-migration-suffixes: .sqllocations: classpath:db/migration

在 resources 目录下创建 db/migration 目录，存放迁移文件。

SQL 迁移文件的命名规范

Flyway 的 SQL 文件命名规则如下：

  • 文件名以大写字母 "V" 开头，后跟版本号（数字与 . 或 _ 分隔），例如：V2.1.5__create_user_ddl.sql。
  • 描述部分应尽量简洁明了，用双下划线分隔版本号和描述部分。
  • 可重复执行的 SQL 文件以 "R" 开头，如：R__truncate_user_dml.sql。

命名规范示例：

版本号格式

  • 使用

    V<主版本号>.<次版本号>.<修订号>

    格式，例如：

    • V1.0.0：初始版本。
    • V1.1.0：引入新功能，保持向后兼容。
    • V1.1.1：修复 bugs 或小修改。
    • V2.0.0：重大更新，不兼容的变更。

命名示例：

  • V1.0.0__create_user_table.sql：初始化脚本，创建 user 表。
  • V1.1.0__add_email_column_to_user_table.sql：添加 email 列到 user 表。
  • V1.2.0__update_user_table_indexes.sql：更新 user 表的索引。
  • V2.0.0__create_product_table.sql：创建 product 表，作为重大版本更新。

Flyway 使用的最佳实践

  1. 所有数据库变更通过 Flyway 管理：无论是创建表、修改表结构，还是插入初始数据，都应该写成 Flyway 的迁移文件。例如：

    • 新建表：

      CREATE TABLE test (id INT PRIMARY KEY AUTO_INCREMENT,name VARCHAR(100) NOT NULL
);

    • 修改表结构（添加列）：

      ALTER TABLE test ADD COLUMN email VARCHAR(255) NOT NULL;

  2. 避免直接操作数据库：将 Navicat 等数据库操纵工具主要用于查看数据或调试，而不是直接修改表结构。在开发过程中，始终通过 Flyway 管理数据库变更，避免直接修改生产环境数据库。

  3. 规范迁移文件的编写：遵循 Flyway 的文件命名规则（如 V001__create_test_table.sql），并保持每个迁移文件只包含一次性、独立的变更。例如，一个文件只负责创建表，另一个文件只负责修改表结构。

  4. 数据库变更流程：

    • 在开发环境中使用工具（如 Navicat）测试并确认数据库变更。
    • 将确认的变更记录到 Flyway 的 SQL 脚本中，并通过 Flyway 执行迁移。
    • 提交迁移文件到版本控制系统，确保其他环境（如测试环境、生产环境）能够通过 CI/CD 自动执行这些迁移。

Flyway 的回滚策略

我们遵循 Flyway 的核心设计理念：

  1. 迁移操作只向前推进：通过新的迁移脚本来修正错误或调整数据库结构，而不是撤销已经应用的迁移。
  2. 保留完整的迁移历史：所有变更（包括错误修正）都记录在 Flyway 的迁移文件和 schema_version 表中，以便追踪和审计。
  3. 数据保护优先：在执行迁移前，务必进行数据备份，防止因操作失误导致的数据丢失。

回滚实施流程

1. 确认问题
  • 分析迁移问题的范围和影响（如表、字段、约束、数据）。
  • 确定需要修正的内容以及对现有数据的影响。
  • 在开发环境中复现问题，确保完全理解问题的根源。
2. 编写新的迁移脚本
  • 命名规则：遵循 Flyway 的版本命名规范（如 V2__Fix_table_structure.sql）。
  • 脚本内容
    • 确保新的迁移脚本仅修改问题部分。
    • 如果需要删除表、字段或数据，建议使用备份表或临时表存储重要数据，避免丢失。
3. 在生产环境中的验证
  • 在生产环境之前，务必在开发或测试环境中验证回滚脚本，确保不会引发其他问题。

使用 Flyway 的注意事项

  1. 非项目初期引入 Flyway 的注意事项
    如果 Flyway 不是在项目初期引入，而是在数据库已有表的情况下引入时，必须设置 baseline-on-migrate: true。启动项目后，Flyway 会在数据库中创建 flyway_schema_history 表，并在表中插入一条版本为 1 的建表记录。如果迁移文件中存在以 V1__ 开头的文件，Flyway 会忽略该文件并避免执行，可能导致其他迁移数据出现问题。
  2. 及时备份 SQL 文件
    始终备份 SQL 脚本，避免在极端情况下丢失重要的数据库变更记录。