SpringBoot集成Flyway

1. 背景

• Flyway是一个款数据库版本管理工具,通过集成Flyway可以实现启动项目时自动执行项目迭代升级所需Sql语句,从而减少升级项目时人工干预成本.

2. 集成Flyway

• pom文件引入依赖

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
    <version>8.0.5</version>
</dependency>

• resources下新建/db/migration文件夹,用于存放脚本文件

# 迁移脚本的位置，默认:db/migration,可通过该配置指定脚本文件位置 
spring.flyway.locations

• 添加application.yml配置信息

#  开启自动创建flyway元数据表标识 默认: false
spring.flyway.baseline-on-migrate=true

3. 文件名规范

格式: V + 版本号 + __ (双下划线) + 描述.sql

• Eg:
  • 版本升级: V1_2_0__upgrade.sql
  • BUG修复: V1_2_0_20220816__hotfix.sql
• 规则说明:
  • 前缀分隔符
    • V: 版本化迁移 (使用)
      • 默认V开头 (可配置)
      • V(大些),小些不执行
    • R: 可重复迁移 (不使用)
      • 新增或追加脚本时再次执行该文件所有脚本(包括历史sql)
      • 历史sql脚本不可更改
      • 不需要指定脚步版本
    • U: 撤销迁移 (不使用)
      • 编写各版本对应撤销版本脚步
      • 需要通过Flyway客户端执行撤销命令,执行最近一次版本撤销
      • 撤销场景较复杂,建议版本升级前进行DB备份,实现撤销
  • SQL脚本版本
    • 2_1为sql版本号, ‘_’ 翻译为小数点,即为2.1版本
    • 新建脚本,版本只可递增
    • 不可使用V1作为版本号
  • 分隔符
    • ‘__’ 双下划线 (可配置)
  • SQL脚本名描述(待定)
    • 多个单词用下划线或空格将单词分开
    • 版本化升级: upgrade
    • BUG修复: hotfix
  • .sql为固定后缀

4. 脚本规范

每条sql语句要给到明确注释, 并标明添加该sql对应时间方便后期维护

• 各sql语句需用分号‘;’结尾
• 已运行脚本文件内sql不可修改
• sql需满足可重复执行: 解决新环境重新部署执行sql问题
• Eg:

-- 新增基础数据-物料主数据表 2022.08.16
CREATE TABLE IF NOT EXISTS `material_test` (
  `id` char(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '主键',
  `code` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '此物料的编码，自然键',
  `name` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '物料名称',
  `specification` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '规格',
  `type` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '物料的类型。',
  `unit` varchar(10) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '默认的计量单位',
  PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci ROW_FORMAT=DYNAMIC COMMENT='基础数据-物料主数据';
-- 添加初始化物料数据 2022.08.17
INSERT IGNORE INTO `material_test` (`id`, `code`, `name`, `specification`, `type`, `unit`) VALUES ('104a3ebc-325e-4d50-8ad4-66e6987d5f82', 'a', 'A物料', NULL, '01', 'kg');
INSERT IGNORE INTO `material_test` (`id`, `code`, `name`, `specification`, `type`, `unit`) VALUES ('104a3ebc-325e-4d50-8ad4-66e6987d5f84', 'b', 'B物料', NULL, '04', 'g');

5. 可重复性

• 建表语句: CREATE TABLE IF NOT EXISTS
• insert语句: INSERT IGNORE INTO
• update/delete数据语句: 默认可重复执行
• 无法重复执行语句,需使用存储过程做判断是否需要执行该语句
• Eg:

-- 通过存储过程满足可重复执行sql
DROP PROCEDURE IF EXISTS initSql;
DELIMITER &&
CREATE PROCEDURE initSql()
   BEGIN
   -- 添加执行sql区域
       -- 物料表添加更新时间字段 2022.08.17
      if not exists(select * from information_schema.COLUMNS where table_name='material_test'and column_name ='update_time')then
        ALTER TABLE `material_test` ADD COLUMN `update_time` datetime NULL COMMENT '更新时间' AFTER `unit`;
      end if;
      -- 物料表删除单位字段 2022.08.18
      if exists(select * from information_schema.COLUMNS where table_name='material_test'and column_name ='unit')then
        alter table `material_test` drop column `unit`;
      end if;
   -- 结束
   END;&&
DELIMITER ;
CALL initSql();
DROP PROCEDURE initSql;

6. 占位符

 配置占位符(可自定义多个占位符) 
# 自定义占位符: myParam
# 自定义参数值: value
spring.flyway.placeholders.myParam=value

• Eg:
  

7. 元数据表

 开启flyway.baseline-on-migrate配置后,启动项目会自动初始化表: flyway_schema_history
# 可通过该配置指定初始化元数据表名, 默认: flyway_schema_history
spring.flyway.tableflyway= 

8. 可能问题

1. V开头脚本,执行后不可修改,修改会导致启动项目时Flyway检测不通过,导致项目启动失败
2. 开发测试阶段需修改已执行脚本,可通过删除相关flyway_schema_history表元数据后,重启项目
3. 脚本命名不规范,导致脚本未被执行
4. 没有使用V(大些)开头
5. 使用V1作为版本号
   (原因: 初始化Flyway元数据表时,也会记录一条记录,已占用版本号V1,个人定义脚本以V1作为版本号会导致该脚本不执行)
6. 脚本文件名版本和描述之间没有使用双下滑线‘__’分割
7. 新增脚本,版本号没有大于已有版本号
   (原因: Flyway执行是通过版本号判断执行顺序,不符合该规则,会导致启动项目时Flyway检测不通过,导致项目启动失败)
8. 各sql语句要以分号‘;’结尾,忘记用分号会导致sql执行失败
9. sql语句不满足可重复执行,新环境执行sql导致失败

9. 问题排查

• 启动日志查看定位报错脚本文件和Message
  
• Flyway元数据表也会记录报错脚本文件名
  

10. 配置说明

flyway.baseline-description对执行迁移时基准版本的描述.
flyway.baseline-on-migrate当迁移时发现目标schema非空，而且带有没有元数据的表时，是否自动执行基准迁移，默认false.
flyway.baseline-version开始执行基准迁移时对现有的schema的版本打标签，默认值为1.
flyway.check-location检查迁移脚本的位置是否存在，默认false.
flyway.clean-on-validation-error当发现校验错误时是否自动调用clean，默认false.
flyway.enabled是否开启flywary，默认true.
flyway.encoding设置迁移时的编码，默认UTF-8.
flyway.ignore-failed-future-migration当读取元数据表时是否忽略错误的迁移，默认false.
flyway.init-sqls当初始化好连接时要执行的SQL.
flyway.locations迁移脚本的位置，默认db/migration.
flyway.out-of-order是否允许无序的迁移，默认false.
flyway.password目标数据库的密码.
flyway.placeholder-prefix设置每个placeholder的前缀，默认${.
flyway.placeholder-replacementplaceholders是否要被替换，默认true.
flyway.placeholder-suffix设置每个placeholder的后缀，默认}.
flyway.placeholders.[placeholder name]设置placeholder的value
flyway.schemas设定需要flywary迁移的schema，大小写敏感，默认为连接默认的schema.
flyway.sql-migration-prefix迁移文件的前缀，默认为V.
flyway.sql-migration-separator迁移脚本的文件名分隔符，默认__.
flyway.sql-migration-suffix迁移脚本的后缀，默认为.sql.
flyway.table使用的元数据表名，默认为flyway_schema_history.
flyway.target迁移时使用的目标版本，默认为latest version.
flyway.url迁移时使用的JDBC URL，如果没有指定的话，将使用配置的主数据源.
flyway.user迁移数据库的用户名.
flyway.validate-on-migrate迁移时是否校验，默认为true.