Spring-Boot-2-实战使用-Flyway-管理你数据库的版本变更

jiezi

5 年前

随着项目的不断迭代，数据库表结构、数据都在发生着变化。甚至有的业务在多环境版本并行运行。数据为王的时代，管理好数据库的版本也成为了迫切的需要。如何能做到像 Git 之类的版本控制工具来管理数据库？Java 项目中常用 Flyway 和 Liquibase 来管理数据库版本。其中 Flyway 相对来说比较受欢迎。

Flyway 大受欢迎是因为它具有以下优点：

简单非常容易安装和学习，同时迁移的方式也很容易被开发者接受。
专一 Flyway 专注于搞数据库迁移、版本控制而并没有其它副作用。
强大专为连续交付而设计。让 Flyway 在应用程序启动时迁移数据库。

Flyway 需要在 DB 中先创建一个 metadata 表 (缺省表名为 flyway_schema_history), 在该表中保存着每次 migration（迁移）的记录, 记录包含 migration 脚本的版本号和 SQL 脚本的 checksum 值。下图表示了多个数据库版本。

对应的 metadata 表记录：

installed_rank	version	description	type	script	checksum	installed_by	installed_on	execution_time	success
1	1	Initial Setup	SQL	V1__Initial_Setup.sql	1996767037	axel	2016-02-04 22:23:00.0	546	true
2	2	First Changes	SQL	V2__First_Changes.sql	1279644856	axel	2016-02-06 09:18:00.0	127	true

Flyway 扫描文件系统或应用程序的类路径读取 DDL 和 DML 以进行迁移。根据 metadata 表进行检查迁移。如果脚本声明的版本号小于或等于标记为当前版本的版本号之一，将忽略它们。其余迁移是待处理迁移：可用，但未应用。最后按版本号对它们进行排序并按顺序执行并将执行结果写入 metadata 表。

对应的 metadata 表记录：

installed_rank	version	description	type	script	checksum	installed_by	installed_on	execution_time	success
1	1	Initial Setup	SQL	V1__Initial_Setup.sql	1996767037	axel	2016-02-04 22:23:00.0	546	true
2	2	First Changes	SQL	V2__First_Changes.sql	1279644856	axel	2016-02-06 09:18:00.0	127	true
3	2.1	Refactoring	JDBC	V2_1__Refactoring	axel	2016-02-10	17:45:05.4	251	true

Flyway 支持命令行（需要下载命令行工具）和 Java Api，也支持构建工具 Maven 和 Gradle。这里我们将目光放在 Java Api 上。

Flyway 是如何比较两个 SQL 文件的先后顺序呢？它采用 采用左对齐原则, 缺位用 0 代替。举几个例子：

1.0.1.1 比 1.0.1 版本高。

1.0.10 比 1.0.9.4 版本高。

1.0.10 和 1.0.010 版本号一样高, 每个版本号部分的前导 0 会被忽略。

Flyway 将 SQL 文件分为 Versioned、Repeatable 和 Undo 三种：

Versioned 用于版本升级, 每个版本有唯一的版本号并只能执行一次.
Repeatable 可重复执行, 当 Flyway检测到 Repeatable 类型的 SQL 脚本的 checksum 有变动, Flyway 就会重新应用该脚本. 它并不用于版本更新, 这类的 migration 总是在 Versioned 执行之后才被执行。
Undo 用于撤销具有相同版本的版本化迁移带来的影响。但是该回滚过于粗暴，过于机械化，一般不推荐使用。一般建议使用 Versioned 模式来解决。

这三种的命名规则如下图：

Prefix 可配置，前缀标识，默认值 V 表示 Versioned, R 表示 Repeatable, U 表示 Undo
Version 标识版本号, 由一个或多个数字构成, 数字之间的分隔符可用点 . 或下划线 _
Separator 可配置, 用于分隔版本标识与描述信息, 默认为两个下划线 __
Description 描述信息, 文字之间可以用下划线 _ 或空格分隔
Suffix 可配置, 后续标识, 默认为 .sql

Spring Boot 提供了对 Flyway 的自动配置。使我们可以开箱即用 Flyway 进行数据库版本控制。

你只需要引入依赖：

      <!-- 无需版本号 -->
 <dependency>
      <groupId>org.flywaydb</groupId>
      <artifactId>flyway-core</artifactId>
 </dependency>

当然你要集成你的相关数据库环境。这里我们采用 H2 数据库来演示，其它数据库同理只不过方言不同。不熟悉 H2 数据库的可参阅我的专题文章 Spring Boot 2 实战：H2 数据库集成以及使用。

为了直观的讲解配置，首先在 Spring Boot 配置文件 application.yml 我们配置 H2 数据库为:

 spring:
   datasource:
     #  h2 驱动
     driver-class-name: org.h2.Driver
     # h2  数据库 持久化到磁盘 D:/h2 库名: flyway  mysql 模式
     url: jdbc:h2:file:D:/h2/flyway;MODE=MySQL;DATABASE_TO_LOWER=TRUE
   h2:
     #    开启 console 访问 默认 false
     console:
       enabled: true
       settings:
         #      开启 h2 console 跟踪 方便调试  默认 false
         trace: true
         #      允许 console 远程访问 默认 false
         web-allow-others: true
       #  h2 访问路径上下文
       path: /h2-console

对应 Flyway 的配置为：

# flyway 配置
spring:
  flyway:
    # 启用或禁用 flyway
    enabled: true
    # flyway 的 clean 命令会删除指定 schema 下的所有 table, 生产务必禁掉。这个默认值是 false 理论上作为默认配置是不科学的。clean-disabled: true
    # SQL 脚本的目录, 多个路径使用逗号分隔 默认值 classpath:db/migration
    locations: classpath:db/migration
    #  metadata 版本控制信息表 默认 flyway_schema_history
    table: flyway_schema_history
    # 如果没有 flyway_schema_history 这个 metadata 表，在执行 flyway migrate 命令之前, 必须先执行 flyway baseline 命令
    # 设置为 true 后 flyway 将在需要 baseline 的时候, 自动执行一次 baseline。baseline-on-migrate: true
    # 指定 baseline 的版本号, 默认值为 1, 低于该版本号的 SQL 文件, migrate 时会被忽略
    baseline-version: 1
    # 字符编码 默认 UTF-8
    encoding: UTF-8
    # 是否允许不按顺序迁移 开发建议 true  生产建议 false
    out-of-order: false
    # 需要 flyway 管控的 schema list, 这里我们配置为 flyway  缺省的话, 使用 spring.datasource.url 配置的那个 schema,
    # 可以指定多个 schema, 但仅会在第一个 schema 下建立 metadata 表, 也仅在第一个 schema 应用 migration sql 脚本.
    # 但 flyway Clean 命令会依次在这些 schema 下都执行一遍. 所以 确保生产 spring.flyway.clean-disabled 为 true
    schemas: flyway
    # 执行迁移时是否自动调用验证   当你的 版本不符合逻辑 比如 你先执行了 DML 而没有 对应的 DDL 会抛出异常
    validate-on-migrate: true

请务必仔细阅读 Flyway 相关配置的说明。

我们先编写一个初始化 SQL 文件，向 H2 数据库已经自动初始化的 schema flyway 添加一张 sys_user 表。请注意命名规则。脚本名称为 V1.0.1__Add_table_user.sql。SQL 脚本的位置在配置的 spring.flyway.locations 下。内容为：

use `flyway`;
CREATE TABLE `sys_user`
(`user_id`         int(10) unsigned NOT NULL AUTO_INCREMENT,
    `username`        varchar(1024)    NOT NULL unique ,
    `encode_password` varchar(1024)       NOT NULL,
    `age`             int(3)           NOT NULL,
    PRIMARY KEY (`user_id`)
) ENGINE = InnoDB
  DEFAULT CHARSET = utf8mb4;

insert into  flyway.sys_user values (1,'Felordcn','{noop}12345',18);

启动 Spring Boot 应用。打开 H2 数据库控制台 http://localhost:8080/h2-console , 在 JDBC URL 一栏粘贴 jdbc:h2:file:D:/h2/flyway;MODE=MySQL;DATABASE_TO_LOWER=TRUE 并点击 Connect 按钮会进入以下界面：

这里 -1 是因为我们缺省了 Flyway 需要的 flyway_schema_history 表。0 是因为 H2 数据库自动初始化了 Schema flyway，其它数据库可能需要你手动来建立。

我们编写一个 V1.0.0__Delete_sysuser_felordcn.sql 来删除 V1.0.1__Add_table_user.sql 中初始化的用户。你会发现启动报错了，因为我们开启了校验，所以对于逻辑错误的版本会抛出异常。我们将版本号更改为 V1.0.2__Delete_sysuser_felordcn.sql 再次启动。通过 H2 数据库控制台我们会发现多了一条变更记录：

同时 sys_user 表的数据也没有了，符合预期。

通过上面的介绍相信你很快就会使用 Flyway 进行数据库版本控制了。这里总结了一些在实际开发中的使用经验：

生产务必禁 spring.flyway.cleanDisabled=false。
尽量避免使用 Undo 模式。
开发版本号尽量根据团队来进行多层次的命名避免混乱。比如 V1.0.1__ProjectName_{Feature|fix}_Developer_Description.sql，这种命名同时也可以获取更多脚本的开发者和相关功能的信息。
spring.flyway.outOfOrder 取值生产上使用 true，开发中使用 false。
多个系统公用一个数据库 schema 时配置spring.flyway.table 为不同的系统设置不同的 metadata 表名而不使用缺省值 flyway_schema_history。

今天我们对 Flyway 数据库版本迁移管理工具进行了介绍并将之与 Spring Boot 相结合。这将大大规范我们的数据库管理，提高生产效率。同时也分享了一些相当有用的生产实践经验。

相关的 DEMO 可通过关注公众号：Felordcn 回复 flyway 进行获取。

关注公众号：Felordcn 获取更多资讯

个人博客：https://felord.cn

Spring-Boot-2-实战使用-Flyway-管理你数据库的版本变更

1. 前言

2. Flyway 的特点

3. Flyway 的工作机制

3. Flyway 的规则

4. Spring Boot 集成 Flyway

4.1 Flyway 依赖

4.2 Flyway 配置

4.3 编写 SQL 初始化脚本

4.4 编写 SQL 变更脚本

5. Flyway 最佳实践

6. 总结