当前位置：首页 > news >正文

Flyway 校验机制

news 来源：原创 2024/9/23 17:24:45

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 校验机制的核心在于确保迁移文件的一致性和正确性。其工作流程如下：

记录迁移执行历史：当 Flyway 执行迁移时，它会在数据库的 flyway_schema_history 表中记录每个迁移文件的版本号、描述、校验和以及执行状态。
计算校验和：每个迁移文件都会生成一个唯一的校验和（Checksum），Flyway 会将该校验和记录在 flyway_schema_history 表中。校验和是基于文件内容生成的，因此任何对文件内容的修改都会导致校验和的变化。
校验历史记录：在每次执行迁移或显式调用 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 流程中校验的步骤：

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

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

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

8. 校验的最佳实践

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

避免修改已执行的迁移文件：在 Flyway 中，一旦迁移文件被执行，不应该再对其进行修改。如果需要修改数据库结构，应该创建一个新的迁移文件。
使用版本控制：将迁移文件纳入版本控制（如 Git）中，确保每次变更都可以被追踪和恢复。
使用 validate-on-migrate：在 application.yml 中启用 validate-on-migrate，确保每次迁移前都进行校验。
在 CI/CD 中集成校验步骤：在 CI/CD 流程中，集成 flyway validate 命令，确保迁移文件在整个开发流程中保持一致性。