SpringBoot使用flyway迁移SQL脚本

谁践踏了优雅 2023-10-02 22:41 1阅读 0赞

## SpringBoot使用flyway迁移SQL脚本 ##

#### 文章目录 ####

*  SpringBoot使用flyway迁移SQL脚本
 *   *  一、简单介绍
     *  二、为什么要使用flyway
     *  三、flyway是如何工作的
     *  四、如何使用flyway
     *   *  1、先要初始化一个SpringBoot项目，引入依赖
         *  2、在application.yml中添加相关配置
         *  3、根据配置文件中填写的脚本存放路径，创建文件夹
         *  4、添加需要运行的sql脚本。sql脚本的命名一定要规范，否则运行flyway会报错
         *  5、启动项目， 通过flyway执行定义好的脚本
         *  6、提示说明
     *  五、maven插件的使用
     *   *  1、配置插件
         *  2、插件命令说明
     *  六、flyway知识补充
     *  七、flyway配置清单
     *  八. 可能问题
     *  九. 问题排查

--------------------

### 一、简单介绍 ###

[Flyway][] 是一款开源的数据库版本管理工具。它可以很方便的在命令行中使用，或者在Java应用程序中引入，用于管理我们的数据库版本。

在项目或产品中，很难一开始就把业务理清楚，把数据库表设计好，因此数据表也会在迭代周期不断迭代。在Java应用程序中使用Flyway，能快速有效地用于迭代数据库表结构，并保证部署到测试环境或生产环境时，数据表都是保持一致的。

[flyway官方文档![982cf6c6f3c3c95ed2958cfabaa067dc.png][]https://flywaydb.org/documentation/][Flyway]

### 二、为什么要使用flyway ###

在多人开发的项目中，我们都习惯了使用SVN或者Git来对代码做版本控制，主要的目的就是为了解决多人开发代码冲突和版本回退的问题。

其实，数据库的变更也需要版本控制，在日常开发中，我们经常会遇到下面的问题：

1.  自己写的SQL忘了在所有环境执行。
2.  别人写的SQL我们不能确定是否都在所有环境执行过了。
3.  有人修改了已经执行过的SQL，期望再次执行。
4.  需要新增环境做数据迁移。
5.  每次发版需要手动控制先发DB版本，再发布应用版本。
6.  其它场景。

有了flyway，这些问题都能得到很好的解决。

### 三、flyway是如何工作的 ###

flyway工作流程如下：

1.  项目启动，应用程序完成数据库连接池的建立后，Flyway自动运行。
2.  初次使用时，flyway会创建一个 flyway\_schema\_history 表，用于记录sql执行记录。
3.  Flyway会扫描项目指定路径下(默认是 classpath:db/migration )的所有sql脚本，与 flyway\_schema\_history 表脚本记录进行比对。如果数据库记录执行过的脚本记录，与项目中的sql脚本不一致，Flyway会报错并停止项目执行。
4.  如果校验通过，则根据表中的sql记录最大版本号，忽略所有版本号不大于该版本的脚本。再按照版本号从小到大，逐个执行其余脚本。

### 四、如何使用flyway ###

#### 1、先要初始化一个SpringBoot项目，引入依赖 ####

我使用的版本是2.3.5.RELEASE，引入mysql、mybatis、flyway等依赖，pom.xml文件内容如下：

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

#### 2、在application.yml中添加相关配置 ####

spring:
      # 数据库连接配置
      datasource:
        driver-class-name: com.mysql.cj.jdbc.Driver
        url: jdbc:mysql://localhost:3306/test?characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai
        username: root
        password: root
      flyway:
        # 是否启用flyway
        enabled: true
        # 编码格式，默认UTF-8
        encoding: UTF-8
        # 迁移sql脚本文件存放路径，默认db/migration
        locations: classpath:db/migration
        # 迁移sql脚本文件名称的前缀，默认V
        sql-migration-prefix: V
        # 迁移sql脚本文件名称的分隔符，默认2个下划线__
        sql-migration-separator: __
        # 迁移sql脚本文件名称的后缀
        sql-migration-suffixes: .sql
        # 迁移时是否进行校验，默认true
        validate-on-migrate: true
        # 当迁移发现数据库非空且存在没有元数据的表时，自动执行基准迁移，新建schema_version表
        baseline-on-migrate: true

#### 3、根据配置文件中填写的脚本存放路径，创建文件夹 ####

根据上面配置文件中的脚本存放路径，我们需要在resource目录下建立文件夹 db/migration 。

#### 4、添加需要运行的sql脚本。sql脚本的命名一定要规范，否则运行flyway会报错 ####

命名规则主要有两种：

1.  仅需要被执行一次的SQL命名以大写的"V"开头，V+版本号(版本号的数字间以”.“或”\_“分隔开)+双下划线(用来分隔版本号和描述)+文件描述+后缀名。例如： V20201100\_\_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开头的SQL执行优先级要比R开头的SQL优先级高。

创建完成后，目录应如下所示：

其中2.1.6、2.1.7和every的文件夹不会影响flyway对SQL的识别和运行，可以自行取名和分类。

![image-20221104145146232][]

#### 5、启动项目， 通过flyway执行定义好的脚本 ####

在控制台可以看到相关日志打印，并在数据库中查看到已经创建好的表和相关记录变更。

![0a2ea5b3a10f509a2fe505dc68371390.png][]

![90bfbe8df2c17a85bd079e83aebce2c6.png][]

#### 6、提示说明 ####

如果我们修改`V2__add_user.sql`中的内容，再次执行的话，就会报错，提示信息如下：

\[ERROR\] Migration checksum mismatch for migration version 2

如果我们修改了`R__add_unknown_user.sql`，再次执行的话，该脚本就会再次得到执行，并且flyway的历史记录表中也会增加本次执行的记录。

### 五、maven插件的使用 ###

#### 1、配置插件 ####

以上步骤中，每次想要migration都需要运行整个springboot项目，并且只能执行migrate一种命令，其实flyway还是有很多其它命令的。maven插件给了我们不需要启动项目就能执行flyway各种命令的机会。

在pom.xml中引入flyway的插件，同时配置好对应的数据库连接。

<build>
            <plugins>
                <plugin>
                    <groupId>org.flywaydb</groupId>
                    <artifactId>flyway-maven-plugin</artifactId>
                    <version>5.2.4</version>
                    <configuration>
                        <url>jdbc:mysql://localhost:3306/flyway-demo?characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai
                        </url>
                        <user>root</user>
                        <password>root</password>
                        <driver>com.mysql.cj.jdbc.Driver</driver>
                    </configuration>
                </plugin>
            </plugins>
        </build>

![e10359172a71a471ad73dedeee614519.png][]

#### 2、插件命令说明 ####

此时，我们双击执行上图中的flyway:migrate的效果和启动整个工程执行migrate的效果是一样的。

其它命令的作用如下：

1.  baseline
    
    对已经存在数据库Schema结构的数据库一种解决方案。实现在非空数据库新建MetaData表，并把Migrations应用到该数据库；也可以在已有表结构的数据库中实现添加Metadata表。
2.  clean
    
    清除掉对应数据库Schema中所有的对象，包括表结构，视图，存储过程等，clean操作在dev 和 test阶段很好用，但在生产环境务必禁用。
3.  info
    
    用于打印所有的Migrations的详细和状态信息，也是通过MetaData和Migrations完成的，可以快速定位当前的数据库版本。
4.  repair
    
    repair操作能够修复metaData表，该操作在metadata出现错误时很有用。
5.  undo
    
    撤销操作，社区版不支持。
6.  validate
    
    验证已经apply的Migrations是否有变更，默认开启的，原理是对比MetaData表与本地Migrations的checkNum值，如果值相同则验证通过，否则失败。

### 六、flyway知识补充 ###

*  flyway执行migrate必须在空白的数据库上进行，否则报错。
 *  对于已经有数据的数据库，必须先baseline，然后才能migrate。
 *  clean操作是删除数据库的所有内容，包括baseline之前的内容。
 *  尽量不要修改已经执行过的SQL，即便是R开头的可反复执行的SQL，它们会不利于数据迁移。
 *  当需要做数据迁移的时候，更换一个新的空白数据库，执行下migrate命令，所有的数据库更改都可以一步到位地迁移过去。

### 七、flyway配置清单 ###

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.tableflyway使用的元数据表名，默认为schema_version
    flyway.target迁移时使用的目标版本，默认为latest version
    flyway.url迁移时使用的JDBC URL，如果没有指定的话，将使用配置的主数据源
    flyway.user迁移数据库的用户名
    flyway.validate-on-migrate迁移时是否校验，默认为true

### 八. 可能问题 ###

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导致失败

### 九. 问题排查 ###

*  启动日志查看定位报错脚本文件和Message  
    ![\[图片\]][8c9e85e57fb98a67b42e23867636035a.png]
 *  Flyway元数据表也会记录报错脚本文件名  
    ![在这里插入图片描述][2fc4079f40e2c42641de2c9ffb09a70d.png]

参考文章:

[flyway的快速入门教程][flyway]

[SpringBoot集成Flyway][SpringBoot_Flyway]

[Flyway]: https://flywaydb.org/documentation/
[982cf6c6f3c3c95ed2958cfabaa067dc.png]: https://img-blog.csdnimg.cn/img_convert/982cf6c6f3c3c95ed2958cfabaa067dc.png
[image-20221104145146232]: https://img-blog.csdnimg.cn/img_convert/198e6dac3f022e2570370b406a7da08a.png
[0a2ea5b3a10f509a2fe505dc68371390.png]: https://img-blog.csdnimg.cn/img_convert/0a2ea5b3a10f509a2fe505dc68371390.png
[90bfbe8df2c17a85bd079e83aebce2c6.png]: https://img-blog.csdnimg.cn/img_convert/90bfbe8df2c17a85bd079e83aebce2c6.png
[e10359172a71a471ad73dedeee614519.png]: https://img-blog.csdnimg.cn/img_convert/e10359172a71a471ad73dedeee614519.png
[8c9e85e57fb98a67b42e23867636035a.png]: https://img-blog.csdnimg.cn/img_convert/8c9e85e57fb98a67b42e23867636035a.png
[2fc4079f40e2c42641de2c9ffb09a70d.png]: https://img-blog.csdnimg.cn/img_convert/2fc4079f40e2c42641de2c9ffb09a70d.png
[flyway]: https://blog.csdn.net/qq_41378597/article/details/124134146
[SpringBoot_Flyway]: https://blog.csdn.net/weixin_42384168/article/details/126409985?spm=1001.2101.3001.6650.1&utm_medium=distribute.pc_relevant.none-task-blog-2%7Edefault%7EYuanLiJiHua%7EPosition-1-126409985-blog-79259762.pc_relevant_default&depth_1-utm_source=distribute.pc_relevant.none-task-blog-2%7Edefault%7EYuanLiJiHua%7EPosition-1-126409985-blog-79259762.pc_relevant_default&utm_relevant_index=2