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.17if not exists(select * from information_schema.COLUMNS where table_name='material_test'and column_name ='update_time')thenALTER TABLE `material_test` ADD COLUMN `update_time` datetime NULL COMMENT '更新时间' AFTER `unit`;end if;-- 物料表删除单位字段 2022.08.18if exists(select * from information_schema.COLUMNS where table_name='material_test'and column_name ='unit')thenalter table `material_test` drop column `unit`;end if;-- 结束END;&&
DELIMITER ;
CALL initSql();
DROP PROCEDURE initSql;

6. 占位符

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

7. 元数据表

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

- 表字段描述
字段
描述
installed_rank
脚本是第几个执行的，一个顺序自增的整数
version
脚本文件名中版本号
description
脚本文件名中双下划线后的描述内容
type
脚本类型 sql脚本显示为 SQL， java脚本显示为 JDBC
script
配置的脚本文件名，sql有后缀，java没有后缀checksum
校验和。用于检测意外的更改
installed_by
脚本执行人（配置的数据库用户）in

8. 可能问题

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