安全集成 Flyway 到现有数据库：避免重复执行迁移的策略

日期：2025-10-07 00:00 / 作者：心靈之曲

本文旨在解决将 Flyway 集成到已手动执行过迁移的现有数据库时，如何避免重复执行迁移脚本导致数据损坏的问题。核心策略是利用干净的测试数据库生成 flyway_schema_history 表，然后将其内容手动同步到生产数据库，从而让 Flyway 识别出已执行的迁移，确保数据安全和无缝过渡。

挑战与背景

在软件开发生命周期中，数据库迁移是一个核心环节。Flyway 作为一款流行的数据库迁移工具，通过版本控制和自动化执行脚本来管理数据库架构的演进。然而，当面临一个特殊场景时，即现有生产数据库的迁移历史并非通过 Flyway 管理，而是通过手动方式（例如直接执行 SQL 脚本）完成，此时直接引入 Flyway 并让其扫描所有历史迁移脚本，可能会导致一个严重的问题：Flyway 可能会尝试重新执行这些已经应用过的脚本，从而引发数据损坏、约束冲突或不可预知的系统行为。

为了安全地将 Flyway 引入此类项目，我们需要一种策略，既能让 Flyway 接管未来的迁移管理，又能避免对现有数据造成任何破坏。

核心策略：利用测试环境构建历史记录

解决此问题的关键在于“欺骗”Flyway，让它认为所有已手动执行的迁移都已通过其自身机制完成。这可以通过在受控的测试环境中模拟 Flyway 的首次运行，并将其生成的迁移历史记录复制到生产环境来实现。

具体步骤如下：

1. 准备并运行 Flyway 于干净的测试数据库

首先，我们需要一个与生产环境数据库结构一致（或至少兼容）的干净测试数据库实例。这个数据库不应包含任何业务数据，仅用于生成 Flyway 的迁移历史。

创建干净的测试数据库： 确保这是一个全新的、未被任何业务数据污染的数据库。
配置 Flyway： 将 Flyway 配置指向您的所有历史迁移脚本（这些脚本是之前手动执行过的）。确保这些脚本的版本号（V1, V2, V3...）与它们在生产环境中执行的顺序一致。
运行应用程序/Flyway： 启动您的应用程序，让 Flyway 针对这个干净的测试数据库执行所有配置的迁移脚本。由于数据库是空的，Flyway 将会顺序执行所有脚本，并将其执行记录保存到默认的 flyway_schema_history 表中（如果未自定义表名）。

完成此步骤后，您的测试数据库中将包含完整的数据库架构，以及一个记录了所有迁移历史的 flyway_schema_history 表。此表是 Flyway 判断哪些迁移已执行、哪些未执行的唯一依据。

示例 Flyway 配置（Java Spring Boot）：

@Configuration
public class FlywayConfig {

    @Bean
    public Flyway flyway(DataSource dataSource) {
        return Flyway.configure()
                .dataSource(dataSource)
                .locations("classpath:db/migration") // 指向您的迁移脚本目录
                .baselineOnMigrate(false) // 首次集成时通常不需要baseline
                .load();
    }
}

检查 flyway_schema_history 表： 在测试数据库中，查询 flyway_schema_history 表，您会看到类似以下结构的记录：

SELECT
    installed_rank,
    version,
    description,
    type,
    script,
    checksum,
    installed_by,
    installed_on,
    execution_time,
    success
FROM
    flyway_schema_history
ORDER BY
    installed_rank;

这些记录包含了每个迁移脚本的版本、描述、校验和、执行时间等信息。

2. 将 flyway_schema_history 迁移到生产数据库

这是最关键的一步。我们需要将测试数据库中生成的 flyway_schema_history 表的结构和数据，完整地复制到生产数据库中。

在生产数据库中创建 flyway_schema_history 表： 根据测试数据库中 flyway_schema_history 表的结构，在生产数据库中手动创建此表。确保所有列名、数据类型、约束等都完全一致。

示例 SQL (PostgreSQL/MySQL 类似):

-- PostgreSQL 示例
CREATE TABLE flyway_schema_history (
    installed_rank INT NOT NULL,
    version VARCHAR(50) NULL,
    description VARCHAR(200) NOT NULL,
    type VARCHAR(20) NOT NULL,
    script VARCHAR(1000) NOT NULL,
    checksum INT NULL,
    installed_by VARCHAR(100) NOT NULL,
    installed_on TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    execution_time INT NOT NULL,
    success BOOLEAN NOT NULL,
    CONSTRAINT flyway_schema_history_pk PRIMARY KEY (installed_rank)
);
CREATE INDEX flyway_schema_history_s_idx ON flyway_schema_history (success);

从测试数据库导出数据并导入到生产数据库： 将测试数据库 flyway_schema_history 表中的所有记录导出（例如，使用数据库客户端工具导出为 INSERT 语句或 CSV 格式），然后将这些数据导入到生产数据库中刚刚创建的 flyway_schema_history 表中。

示例 INSERT 语句片段：
```
INSERT INTO flyway_schema_history (installed_rank, version, description, type, script, checksum, installed_by, installed_on, execution_time, success) VALUES
(1, '1.0', 'Initial schema setup', 'SQL', 'V1_0__Initial_schema_setup.sql', 123456789, 'your_user', '2025-01-01 10:00:00', 100, TRUE),
(2, '1.1', 'Add user table', 'SQL', 'V1_1__Add_user_table.sql', 987654321, 'your_user', '2025-01-02 11:00:00', 150, TRUE),
-- ... 更多记录
;
```
重要提示： 确保导入的数据与测试数据库中的数据完全一致，特别是 version 和 checksum 字段，它们是 Flyway 识别迁移的关键。

3. 生产环境验证

完成上述步骤后，当您在生产环境中启动应用程序（已集成 Flyway）时：

Flyway 会连接到生产数据库。
它会发现 flyway_schema_history 表已经存在。
它会扫描 db/migration 目录下的所有迁移脚本，并与 flyway_schema_history 表中的记录进行比对。
由于表中已经包含了所有历史迁移的记录（版本号和校验和匹配），Flyway 将会认为这些迁移已经成功执行，因此不会尝试重新执行它们。
此后，所有新添加的迁移脚本（例如 V1.2__Add_new_feature.sql）将按正常流程被 Flyway 识别并执行。

注意事项

数据备份： 在对生产数据库进行任何手动操作之前，务必进行全面的数据库备份。这是任何生产环境操作的黄金法则。
校验和一致性：
确保生产数据库中 flyway_schema_history 表的 checksum 字段与实际迁移脚本的校验和完全匹配。如果校验和不匹配，Flyway 会报错并拒绝执行后续操作。这意味着您的迁移脚本内容必须与之前手动执行的脚本内容完全一致。
版本控制： 确保所有历史迁移脚本都已纳入版本控制系统，并且其内容与实际在生产环境中执行的 SQL 脚本一致。
团队协作： 如果是团队项目，确保所有开发人员都了解此集成策略，并遵循统一的迁移管理流程。
baselineOnMigrate 参数： 在此场景下，通常不需要设置 baselineOnMigrate(true)。baselineOnMigrate 主要用于当 Flyway 首次接管一个已存在但没有 flyway_schema_history 表的数据库时，将当前数据库状态标记为基线，并跳过所有早于基线的迁移。但我们的策略是手动填充 flyway_schema_history，所以不需要基线操作。
自定义表名： 如果您自定义了 Flyway 的历史表名（例如 flyway.table=my_schema_history），请确保在所有步骤中都使用自定义的表名。

总结

将 Flyway 安全地集成到已手动执行过迁移的现有数据库中，需要一种细致的策略。通过在干净的测试环境中模拟 Flyway 的首次运行，生成完整的 flyway_schema_history 表，并将其结构和数据精确地复制到生产数据库，我们可以有效地让 Flyway 接管未来的数据库迁移管理，同时避免对现有生产数据造成任何破坏。这种方法确保了数据库迁移过程的平稳过渡和数据完整性。