数据库版本管理框架-Flyway（从入门到精通）

原创

程序员西西o 2024-06-14 07:01:38 ©著作权

文章标签 数据库 sql SQL Flyway 文章分类 JavaScript 前端开发

©著作权归作者所有：来自51CTO博客作者程序员西西o的原创作品，请联系作者获取转载授权，否则将追究法律责任

一、flyway简介

Flyway是一个简单开源数据库版本控制器（约定大于配置），主要提供migrate、clean、info、validate、baseline、repair等命令。它支持SQL（PL/SQL、T-SQL）方式和Java方式，支持命令行客户端等，还提供一系列的插件支持（Maven、Gradle、SBT、ANT等）。

二、使用Flyway背景

部门开发一直是后端人员自行维护新增脚本，所以每次部署项目测试，都需要后端开发人员将 sql脚本在对应环境数据库上执行一遍，这样就造成有时候脚本文件混乱或者忘记执行，导致一些不必要的麻烦，所以就想要使用一款可以记录SQL文件版本迭代的工具。

三、Springboot集成Flyway

废话少说，我们直接开始进行Springboot的集成吧。
首先看一下Flyway执行流程：

1）Flyway 会扫描配置的脚本目录下的脚本文件；
2）如果历史记录表不存在，则新建历史记录表；
3）如果是一次性执行脚本（V），按版本号从小到大执行迁移脚本，与当前历史表中的版本号做对比，大于当前版本号的脚本才会被执行迁移；
4）如果是可重复执行脚本（R），检查脚本是否有变动，有变动的可重复脚本才会被执行迁移；

1.引入依赖
Springboot2.x版本已经对Flyway有所依赖了，我们直接引入，不需要进行版本的申明，有时你写上版本号还可能被项目自动覆盖哦，这块注意检查一下。

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

2.配置文件 yml
要迁移的数据库的 DB url。如果未设置，则使用主要配置的数据源，正常我们的项目都有jdbc的连接信息，我们使用默认就行，无需配置。

pring:
  flyway:
    # 开启 flyway
    enabled: true
    # 检测迁移脚本的路径是否存在，如不存在，则抛出异常
    check-location: true
    # 是否禁用数据库清理
    clean-disabled: true
    # SQL 迁移的编码
    encoding: UTF-8
    # 迁移脚本的位置，默认db/migration.
    locations: classpath:flyway
    # 版本记录信息表
    table: tb_flyway_history
    # SQL 迁移的文件名前缀。
    sql-migration-prefix: V
    # SQL 迁移的文件名分隔符。
    sql-migration-separator: __
    # SQL 迁移的文件名后缀。
    sql-migration-suffixes: .sql
    # 是否在执行迁移时自动调用验证。
    validate-on-migrate: true
    # 迁移时发现目标schema非空，而且带有没有元数据的表时，是否自动执行基准迁移，默认false.
    baseline-on-migrate: true
    #如果不想用元数据的表明，可以更改元表名
    spring.flyway.table=test

3.新建flyway文件夹和sql文件

Flyway 的默认扫描迁移脚本目录在：spring.flyway.locations: classpath:db/migration，用于扫描的迁移脚本目录
Flyway 的默认版本变化记录表名称：spring.flyway.table: flyway_schema_history，用于记录所有的版本变化记录（可在配置文件中进行更改）

3.1 根据第2步配置了迁移脚本目录，我们在 src/main resources 目录下创建flyway目录，如下图：

数据库版本管理框架-Flyway（从入门到精通）_数据库

3.2 下面我们创建两个sql脚本，如上图：

SQL脚本的命名规则(约定大于配置必须遵守)

命名规则主要有两种：

1、仅需要被执行一次的SQL命名以大写的"V"开头，V+版本号(版本号的数字间以”.“或”_“分隔开)+双下划线(用来分隔版本号和描述)+文件描述+后缀名。例如： V20231100__create_user.sql、V2.1.5__create_user_ddl.sql、V4.1_2__add_user_dml.sql 。
2、可重复运行的SQL，则以大写的“R”开头，后面再以两个下划线分割，其后跟文件名称，最后以.sql结尾。（不推荐使用）比如： R__truncate_user_dml.sql 。
前缀：V用于版本化（可配置）， U用于撤消（可配置）和 R用于可重复迁移（可配置）
版本：带点或下划线的版本可以根据需要分开多个部分（不适用于可重复的迁移）
分隔符：( __两个下划线）（可配置）
描述：下划线或空格分隔单词
后缀：.sql（配置）

-- V1.0.0__user_create.sql 创建标签表
DROP TABLE IF EXISTS tb_user;
CREATE TABLE `tb_user` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT 'ID',
  `user_code` varchar(100) DEFAULT NULL COMMENT '用户code',
  `user_name` varchar(50) DEFAULT NULL COMMENT '用户名称',
  `user_type` int(2) DEFAULT 3 COMMENT '用户类型',
  `update_time` datetime DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `create_time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8mb4 COMMENT='用户表';
 
-- V1.0.1__user_insert.sql 标签表插入数据
INSERT INTO tb_user
(user_code, user_name, user_type)
values("U12345", "张三", 1);

四、启动项目

2022-05-17 16:13:37.912||||[main] INFO  o.f.core.internal.database.base.DatabaseType 49 - Database: jdbc:mysql://localhost:3366/db (MySQL 5.7)
2022-05-17 16:13:37.999||||[main] INFO  org.flywaydb.core.internal.command.DbValidate 49 - Successfully validated 2 migrations (execution time 00:00.048s)
2022-05-17 16:13:38.025||||[main] INFO  org.flywaydb.core.internal.command.DbMigrate 49 - Current version of schema `db`: << Empty Schema >>
2022-05-17 16:13:38.039||||[main] INFO  org.flywaydb.core.internal.command.DbMigrate 49 - Migrating schema `db` to version "1.0.0 - create"
2022-05-17 16:13:38.123||||[main] INFO  org.flywaydb.core.internal.command.DbMigrate 49 - Migrating schema `db` to version "1.0.1 - insert"
2022-05-17 16:13:38.157||||[main] INFO  org.flywaydb.core.internal.command.DbMigrate 49 - Successfully applied 2 migrations to schema `db` (execution time 00:00.153s)

数据库中flyway记录历史信息表如下：

数据库版本管理框架-Flyway（从入门到精通）_Flyway_02

五、开发时注意事项

1.报错后需要删除flyway_schema_history中记录，否则启动失败
2.V的优先级高于R，假如三个V迁移脚本和一个R(无论新建还是修改)一起执行，其中一个V报错，则V会
全部执行完成且记录到flyway_schema_history中，而R不执行且不记录，删除表中报错记录后，查询启
动，则执行原错误V和未执行的R
3.多个要执行的R中，如果出现了其中一个出现了错误，则在其后的R都不执行
4.R的执行顺序根据命名来进行排序
5.一个文件中ddl并不由一个事务管理，比如创建三个表，中间创建表语句报错，则第一个表还是会创建
成功并且提交事务
6.已经执行过的迁移文件(V)不能修改，否则报错。
7.同一个迁移文件下同表内DDL无法回滚，DML可回滚, 从报错点开始不往下执行，Flyway使用数据库锁
机制
8.版本号相同会报错（Found more than one migration with version 1.0.0.9）
9.同一个迁移文件下假设都是dml，那么如果中间出现错误，所有的dml语句都会回滚
10.删除sql文件后启动会报错，报错如下

If you removed this migration intentionally, run repair to mark the migration as
deleted.

六、部署上线时注意事项

如果不手动创建元数据表，则需要进行以下配置，用于自动创建
validate-on-migrate: true
如果数据库不是空表，则需进行以下配置，否则启动报错
baseline-on-migrate: true
clean命令会删除数据库中所有表，包括数据，结构等，这是不合理的，所以需要进行以下配置
clean-disabled: true (该配置由于默认值不合理，所以在V9版本中修改默认值由false为true)
使用flyway要注意版本兼容问题，springboot与flyway，flyway与数据库版本，否则启动报错
如果启动的时候像忽略某些迁移文件，可进行以下参数配置
baseline-version=20230809，以忽略 20230809 版本以及之前的所有 migration
多人开发中，如果一个人提交V2一个人提交V1，而V2先入库执行了，那么V1入库就不会执行，如果需要执行则需进行如下配置，但是不建议这么做
out-of-order=true