Flyway 校验机制

Flyway 校验机制

Flyway 是一个数据库迁移工具，用于确保数据库结构和数据迁移与应用程序的版本变化保持一致。在管理数据库迁移的过程中，Flyway 通过校验机制（Validation），确保已经执行过的迁移文件未被修改，未执行的迁移文件可以被正常执行，帮助开发者避免数据库变更过程中的意外情况和错误。

Flyway 的校验机制通过校验和（Checksum）确保数据库的版本化文件没有被修改，并且可以及时发现潜在的问题。

1. Flyway 校验机制概述

Flyway 的校验机制主要用于在执行数据库迁移之前，验证迁移文件是否有变化，确保数据库迁移的正确性和一致性。它会检查迁移文件的以下几个方面：

• 文件名：验证迁移文件的名称是否保持不变。
• 版本号：检查迁移文件的版本号是否正确，是否与已经执行过的迁移文件匹配。
• 校验和（Checksum）：验证迁移文件的内容是否被修改，Flyway 会自动生成并记录每个迁移文件的校验和。

当 Flyway 执行 validate 命令时，它会根据这些规则验证迁移文件是否符合预期。如果发现某个迁移文件被修改，Flyway 会抛出校验错误，停止迁移的执行。

2. 校验和（Checksum）

校验和 是 Flyway 校验机制的核心。Flyway 会为每个迁移文件计算一个唯一的校验和，并将其记录在数据库的 flyway_schema_history 表中。当 Flyway 再次执行校验时，它会重新计算这些文件的校验和，并与数据库中记录的校验和进行对比。如果发现校验和不一致，则认为迁移文件被修改，迁移失败。

校验和的生成方式是基于迁移文件的内容。因此，任何对文件内容的修改（即便是空格或注释的变化）都会导致校验和的变化，从而触发校验错误。

3. Flyway 校验的配置

在 Spring Boot 项目中，Flyway 校验机制默认是启用的。开发者可以通过配置文件进行自定义校验的行为。

3.1 启用校验

Flyway 的 validateOnMigrate 属性用于控制在执行迁移前是否进行校验。默认情况下，这个选项是开启的。每当执行迁移时，Flyway 会先对迁移文件进行校验，确保文件的正确性。

在 application.yml 中配置：

spring:
  flyway:
    validate-on-migrate: true  # 启用迁移前校验，默认为 true

在 application.properties 中配置：

spring.flyway.validate-on-migrate=true

3.2 手动校验

除了在迁移前自动校验之外，Flyway 还提供了 validate 命令，可以手动执行校验。该命令通常用于在部署前检查迁移文件的完整性，确保不会出现校验和错误。

手动执行校验命令：

flyway validate

执行后，Flyway 会检查所有迁移文件，并输出校验结果。如果某个迁移文件被修改或丢失，Flyway 会报错并显示详细的错误信息。

3.3 忽略迁移校验失败

在某些特殊情况下，开发者可能希望忽略某些迁移文件的校验错误，允许迁移继续执行。这可以通过 ignorePendingMigrations 或 ignoreIgnoredMigrations 等选项来实现。

• 忽略未执行的迁移：

spring:
  flyway:
    ignore-missing-migrations: true  # 忽略数据库中记录的迁移文件缺失的情况

• 忽略重复迁移：

spring:
  flyway:
    ignore-ignored-migrations: true  # 忽略被忽略的迁移

• 忽略挂起的迁移：

spring:
  flyway:
    ignore-pending-migrations: true  # 忽略尚未执行的迁移

这些选项允许 Flyway 在某些校验失败的情况下继续执行后续的迁移。

4. 校验失败的常见情况

Flyway 校验失败时，会抛出错误并停止迁移操作。常见的校验失败场景包括迁移文件的内容修改、版本冲突和文件丢失。

4.1 迁移文件修改

原因：迁移文件的内容被修改，例如更改了 SQL 语句、添加了注释或修改了文件格式。

解决方法：

• 如果修改是无意的，可以恢复迁移文件的原始版本，确保校验和一致。
• 如果需要修改迁移文件的内容，推荐创建一个新的迁移文件，而不是直接修改已经执行过的迁移文件。

4.2 迁移文件丢失

原因：Flyway 在数据库中记录了某个迁移文件的执行，但该文件在文件系统中丢失或被删除。

解决方法：

• 恢复丢失的迁移文件到 db/migration 目录中，使其与数据库中的记录一致。
• 如果该迁移文件已经不再需要，可以通过 repair 命令修复迁移历史记录。

flyway repair

repair 命令会重新计算校验和，并删除失败的迁移记录。

4.3 版本号冲突

原因：多个迁移文件使用了相同的版本号，Flyway 无法确定迁移顺序。

解决方法：

• 确保每个迁移文件的版本号是唯一的，避免版本号冲突。
• 修改冲突的迁移文件名，确保版本号正确排序。

4.4 校验和冲突

原因：迁移文件的校验和与数据库中的记录不一致。

解决方法：

• 检查是否有人手动修改了迁移文件。如果是这样，恢复文件的原始内容。
• 如果需要进行迁移文件的内容修改，建议新建一个新的迁移文件，而不是修改已执行的文件。
• 可以通过 flyway repair 命令重置校验和。

5. Flyway 校验机制的工作原理

Flyway 校验机制的核心在于确保迁移文件的一致性和正确性。其工作流程如下：

1. 记录迁移执行历史：当 Flyway 执行迁移时，它会在数据库的 flyway_schema_history 表中记录每个迁移文件的版本号、描述、校验和以及执行状态。

2. 计算校验和：每个迁移文件都会生成一个唯一的校验和（Checksum），Flyway 会将该校验和记录在 flyway_schema_history 表中。校验和是基于文件内容生成的，因此任何对文件内容的修改都会导致校验和的变化。

3. 校验历史记录：在每次执行迁移或显式调用 flyway validate 时，Flyway 会重新计算迁移文件的校验和，并与 flyway_schema_history 表中的记录进行对比。如果校验和不一致，Flyway 会认为迁移文件被修改，从而报出校验错误。

6. Flyway Schema History 表

Flyway 使用数据库中的一张表 flyway_schema_history 来记录所有迁移文件的执行历史和状态。表的结构如下：

• installed_rank：表示迁移文件的执行顺序。
• version：迁移文件的版本号。
• description：迁移文件的简短描述。
• type：迁移类型（SQL、Java、基准点等）。
• script：迁移文件的名称。
• checksum：迁移文件的校验和。
• installed_by：执行迁移的用户。
• installed_on：迁移执行的时间。
• execution_time：迁移文件的执行时间。
• success：是否成功执行。

通过查询这张表，开发者可以了解数据库的迁移历史以及每个迁移文件的执行状态。

7. 校验机制在 CI/CD 中的应用

在 CI/CD 流水线中，Flyway 的校验机制尤为重要，它可以确保数据库迁移文件在整个团队开发和测试过程中保持一致。开发人员可以通过在 CI/CD 流程中加入 flyway validate 步骤，自动验证迁移文件的完整性和一致性。

CI/CD 流程中校验的步骤：

1. 下载最新代码，并执行 flyway validate，确保迁移文件没有被修改。
2. 执行数据库迁移，如发现校验和错误则终止构建。
3. 如果数据库迁移通过

，则继续进行后续构建和测试步骤。

这种方式可以确保团队协作开发时，所有成员的迁移文件都能保持一致，避免手动修改迁移文件带来的风险。

8. 校验的最佳实践

为了避免 Flyway 校验错误，开发者应遵循以下最佳实践：

1. 避免修改已执行的迁移文件：在 Flyway 中，一旦迁移文件被执行，不应该再对其进行修改。如果需要修改数据库结构，应该创建一个新的迁移文件。

2. 使用版本控制：将迁移文件纳入版本控制（如 Git）中，确保每次变更都可以被追踪和恢复。

3. 使用 validate-on-migrate：在 application.yml 中启用 validate-on-migrate，确保每次迁移前都进行校验。

4. 在 CI/CD 中集成校验步骤：在 CI/CD 流程中，集成 flyway validate 命令，确保迁移文件在整个开发流程中保持一致性。

结论

Flyway 的校验机制通过文件名、版本号和校验和等多种方式，确保数据库迁移文件的完整性和一致性。它在数据库变更管理中起到了关键作用，帮助开发团队避免潜在的数据库一致性问题。通过合理使用 Flyway 的校验功能和最佳实践，开发者可以有效管理数据库迁移，确保数据库结构在不同环境中的稳定和一致。

原文地址：https://blog.csdn.net/Flying_Fish_roe/article/details/142435220

免责声明：本站文章内容转载自网络资源，如本站内容侵犯了原著者的合法权益，可联系本站删除。更多内容请关注自学内容网（zxcms.com）！