Flyway 元数据表详解

Flyway 是一个开源的数据库版本控制工具，用于管理和跟踪数据库的变更。它通过 SQL 脚本或 Java 代码来执行数据库迁移，并记录所有的迁移操作。Flyway 通过一个特殊的元数据表来跟踪数据库的变更历史，确保每次执行的迁移操作是唯一的、可重复的且安全的。

---

1. Flyway 元数据表简介

Flyway 通过一个名为 flyway_schema_history 的元数据表来记录每次数据库迁移的状态。这个表用于存储所有已执行的迁移脚本信息，确保每个迁移脚本只会执行一次。Flyway 在每次运行迁移时，都会首先检查这个元数据表，以确定哪些迁移已经执行过，哪些迁移需要执行。

默认元数据表名称

默认情况下，Flyway 使用名为 flyway_schema_history 的表来存储元数据。如果需要，可以通过配置文件自定义该表的名称。

flyway:
  table: flyway_schema_history_custom  # 自定义元数据表名称

---

2. Flyway 元数据表结构

flyway_schema_history 表的结构定义了 Flyway 如何跟踪数据库的迁移操作。下面是该表的常见字段和它们的含义：

CREATE TABLE flyway_schema_history (
    installed_rank INT NOT NULL,
    version VARCHAR(50),
    description VARCHAR(200) NOT NULL,
    type VARCHAR(20) NOT NULL,
    script VARCHAR(1000) NOT NULL,
    checksum INT,
    installed_by VARCHAR(100) NOT NULL,
    installed_on TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    execution_time INT NOT NULL,
    success BOOLEAN NOT NULL
);

字段解释：

1. installed_rank：安装顺序，每个迁移都有唯一的序号，用于记录执行顺序。
2. version：迁移版本号，通常是由迁移文件名中的版本号生成的。比如，文件 V1__Create_user_table.sql 的版本号是 1。
3. description：对迁移的简要描述，通常是从文件名中提取的。例如，Create_user_table。
4. type：迁移的类型，可能的值包括：
   • SQL：SQL 脚本。
   • JDBC：通过 Java 代码的迁移。
   • BASELINE：基准迁移。
   • DELETE：删除操作。
5. script：迁移脚本的文件名或内容的标识符。
6. checksum：脚本文件的校验和，用于验证文件内容是否改变。如果迁移脚本内容发生变化，Flyway 会检测到并提示。
7. installed_by：执行该迁移的用户。
8. installed_on：执行迁移的时间戳。
9. execution_time：迁移的执行时间（以毫秒为单位）。
10. success：标志该迁移是否成功执行。true 表示成功，false 表示失败。

---

3. Flyway 元数据表的作用

元数据表的主要作用是记录所有迁移的执行历史，它确保 Flyway 具有以下功能：

3.1 防止重复执行迁移

Flyway 通过元数据表中的 version 字段来跟踪已经执行过的迁移。如果迁移版本已经存在，Flyway 将不会再次执行该版本的迁移文件，避免重复执行。

3.2 保证迁移顺序

Flyway 使用 installed_rank 来确定每次迁移的顺序。无论是通过手动运行还是通过自动化工具，所有的迁移都会按照指定的顺序依次执行，确保数据变更的顺序性。

3.3 检测迁移文件的变化

Flyway 通过计算迁移文件的 checksum 来检测脚本内容是否发生变化。如果已经执行过的迁移文件发生了变化（例如，开发者手动修改了 SQL 文件），Flyway 会检测到并提示错误，防止已应用的迁移脚本内容不一致。

3.4 记录迁移的详细信息

元数据表不仅记录了迁移的版本和顺序，还记录了每个迁移的执行时间、执行者、脚本文件名和执行结果。这些信息对于调试和回溯数据库变更非常有帮助。

---

4. 元数据表的管理

元数据表是 Flyway 迁移管理中的核心部分，但开发者在日常开发中通常不需要直接操作该表。Flyway 提供了多种工具来管理和维护元数据表。

4.1 自定义元数据表名

如果项目中存在命名冲突或其他需求，可以通过 Flyway 配置文件自定义元数据表的名称。

flyway:
  table: custom_schema_history  # 自定义元数据表名称

4.2 清除元数据表

在某些情况下，开发者可能需要清除所有的迁移记录（例如重新初始化数据库）。Flyway 提供了 flyway clean 命令来删除数据库中的所有表，包括元数据表。这通常用于开发和测试环境，不建议在生产环境中使用。

flyway clean

clean 命令会删除数据库中的所有对象（表、视图、存储过程等），并清空元数据表。

4.3 修复元数据表

Flyway 提供了 flyway repair 命令，用于修复元数据表中的不一致。例如，如果某次迁移失败或元数据表中的校验和不正确，可以使用该命令来修复。

flyway repair

repair 命令会修复以下内容：

• 删除失败的迁移记录。
• 修复校验和不匹配的问题。
• 更新基准迁移信息。

---

5. 元数据表校验和的使用

Flyway 通过 checksum 字段来确保每个迁移文件的内容一致。当 Flyway 检测到一个已经执行过的迁移文件发生了变更（即 checksum 发生变化），它会抛出错误，并提示迁移脚本的内容已被修改。

校验和的典型错误提示：

Detected resolved migration not applied to database: 2
Resolved migration checksum mismatch for migration version 1
- Applied to database : -786652490
- Resolved locally    : 234562789

处理方法：

1. 修复脚本：如果你确实需要修改已经执行过的迁移脚本，应该创建一个新的迁移文件，而不是直接修改已经执行过的文件。
2. 使用 flyway repair：如果你确定迁移脚本的变更不会影响数据库的当前状态，可以使用 flyway repair 来更新 checksum。

---

6. 版本控制和迁移策略

Flyway 依赖版本号来管理数据库的迁移，每个迁移文件都有唯一的版本号。如果版本号重复或者不按顺序，Flyway 会抛出错误。

6.1 版本控制策略

• 严格版本顺序：Flyway 要求迁移文件的版本号按顺序递增。例如，V1__create_user.sql 应该在 V2__add_email_column.sql 之前执行。
• 平行开发：如果多个开发者同时开发，可以使用小数或点分版本号来处理并行开发的迁移文件。例如，开发者 A 创建 V2.1__create_orders.sql，开发者 B 可以创建 V2.2__add_order_status.sql。

6.2 Baseline 和 Repair 机制

• Baseline：Flyway 提供 baseline 功能，用于处理已经存在数据的数据库。在数据库初始化之前，开发者可以通过 flyway baseline 创建一个基准点，使 Flyway 只应用新迁移文件。

  flyway baseline
  

• Repair：repair 功能可以用于修复元数据表中的问题，例如修复失败的迁移或不匹配的校验和。

---

7. 总结

Flyway 通过元数据表 flyway_schema_history 来记录和管理数据库迁移的状态。元数据表确保每个迁移文件只会执行一次，并提供校验和机制来确保迁移文件的内容一致。通过 Flyway 提供的命令，如 clean、repair、baseline 等，开发者可以有效地管理和维护数据库迁移过程。