Flyway 版本迁移文件

Flyway 是一个用于管理数据库版本控制和迁移的工具，广泛用于 DevOps 和持续集成环境中。它可以帮助开发者在不同的环境中保持数据库的状态一致性，同时可以方便地进行数据库的更新和回滚操作。Flyway 的核心功能是通过 版本迁移文件 来管理数据库的 schema 变更，确保数据库变更的自动化和安全性。

一、Flyway 版本迁移文件的作用

Flyway 版本迁移文件的主要作用是记录数据库的变更历史。通过将 SQL 语句放入版本迁移文件，Flyway 可以自动执行这些变更操作并追踪数据库的状态。每个版本迁移文件都包含了一组用于修改数据库结构或数据的 SQL 操作（如 CREATE TABLE、ALTER TABLE、INSERT 等），Flyway 会根据文件中的版本号依次执行这些操作。

主要功能：

1. 版本控制：通过 Flyway 的迁移文件，可以为每一次数据库变更指定一个版本号，便于追踪和管理。
2. 自动执行：Flyway 会自动识别新的迁移文件并执行，确保数据库 schema 一致性。
3. 回滚：如果在执行迁移时发生错误，可以使用回滚功能来恢复数据库的状态。

二、版本迁移文件的命名规范

Flyway 采用特定的文件命名规范来管理数据库迁移文件。文件名不仅仅是标识文件的作用，它还决定了 Flyway 执行迁移文件的顺序和类型。

迁移文件的命名格式通常为：

V<Version>__<Description>.sql

• V：表示这是一个版本迁移文件。
• ：版本号，Flyway 会根据版本号的顺序依次执行文件。版本号可以是纯数字、数字和小数的组合，支持多层次的版本控制（如 V1, V1.1, V2.0 等）。
• ：对文件内容的简短描述，用两个下划线 __ 分隔版本号和描述。描述可以使用下划线代替空格。

例如：

• V1__Create_users_table.sql：创建一个用户表的迁移文件。
• V2.1__Add_email_column_to_users.sql：为用户表添加 email 列的迁移文件。

除了 V 作为版本迁移文件的标识外，Flyway 还支持其他类型的迁移文件命名：

• R：表示重复运行的迁移（Repeatable migrations），例如：R__Refresh_views.sql。这种文件可以在每次执行 Flyway 的 migrate 操作时重新运行。
• U：表示 Undo 迁移文件，用于回滚版本变更。格式为 U<Version>__<Description>.sql，例如：U2__Drop_email_column.sql。

三、创建版本迁移文件

在 Flyway 中，每个迁移文件都应包含与当前数据库变更相关的 SQL 语句。常见的数据库变更包括表的创建、字段的添加、索引的添加和修改等。

1. 创建基本的迁移文件

假设我们希望创建一个包含用户信息的表，可以编写如下迁移文件。

文件名：V1__Create_users_table.sql

-- 创建用户表
CREATE TABLE users (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

2. 添加新字段的迁移

随着业务的发展，可能需要在 users 表中增加新的字段。此时可以创建一个新版本的迁移文件。

文件名：V2__Add_phone_to_users.sql

-- 为 users 表添加 phone 字段
ALTER TABLE users ADD phone VARCHAR(20);

Flyway 将根据版本号的顺序，依次执行 V1__Create_users_table.sql 和 V2__Add_phone_to_users.sql，确保数据库版本的有序演进。

3. 批量插入数据的迁移

在某些情况下，除了修改数据库结构，还需要在迁移中插入初始数据。例如：

文件名：V3__Insert_initial_users.sql

-- 插入初始用户数据
INSERT INTO users (name, email, phone) VALUES ('John Doe', 'john.doe@example.com', '123456789');
INSERT INTO users (name, email, phone) VALUES ('Jane Doe', 'jane.doe@example.com', '987654321');

4. 创建索引的迁移

为了提高查询性能，可能需要为表添加索引：

文件名：V4__Add_index_on_users_email.sql

-- 为 email 字段添加唯一索引
CREATE UNIQUE INDEX idx_users_email ON users (email);

四、执行版本迁移

1. Flyway 配置

在 Spring Boot 或其他 Java 项目中，Flyway 可以通过配置文件进行设置。例如在 application.yml 文件中，可以配置 Flyway 的基本信息：

spring:
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: true

• enabled：启用 Flyway。
• locations：指定迁移文件的存放路径。
• baseline-on-migrate：如果数据库已经存在结构，启用 baseline 来初始化迁移。

2. 执行 Flyway 迁移

在 Spring Boot 项目中，Flyway 会在应用启动时自动执行迁移文件。每次启动应用，Flyway 会检查是否有新的迁移文件，如果有则按顺序执行。

如果使用命令行，可以通过 Flyway 提供的 flyway migrate 命令执行数据库迁移。

flyway migrate

此命令会读取指定路径下的迁移文件，并按顺序应用到数据库。

五、回滚与修复迁移

1. 迁移回滚

Flyway 不支持自动回滚每个迁移文件，但是可以手动编写 Undo 迁移文件进行回滚操作。例如，假设我们希望删除前面添加的 phone 字段，可以创建一个新的 Undo 文件：

文件名：U2__Drop_phone_from_users.sql

-- 删除 users 表的 phone 字段
ALTER TABLE users DROP COLUMN phone;

回滚时执行 flyway undo 命令即可。

2. 修复失败的迁移

如果某次迁移由于某种原因失败了，可以使用 Flyway 的 repair 命令来修复不一致的迁移状态。该命令会删除失败的迁移记录，允许开发者重新运行失败的迁移。

flyway repair

六、常见问题与注意事项

1. 迁移文件的版本冲突

在多人协作开发时，如果两个开发者同时创建了相同版本号的迁移文件，可能会导致版本冲突。为避免这种情况，建议为迁移文件使用更精细的版本号（如 V1.1、V1.2），并尽量在团队中沟通好版本控制策略。

2. 执行顺序不正确

Flyway 会严格按照迁移文件中的版本号顺序执行。如果文件名不符合版本控制规则，可能会导致某些迁移文件没有执行。因此，确保命名的唯一性和正确性非常重要。

3. 基线（Baseline）操作

当你有一个已经部署的数据库，但希望从某个版本开始使用 Flyway 进行迁移时，可以通过 baseline 操作将当前数据库标记为某个版本。这样，Flyway 会从该版本之后开始应用新的迁移文件。

flyway baseline

七、总结

Flyway 通过版本迁移文件的方式提供了高效的数据库版本控制机制，能够确保数据库 schema 的一致性，并且支持自动执行数据库变更操作。通过合理使用 Flyway 的版本控制机制，开发者可以更好地管理数据库的演进和升级。