Springboot集成Flyway详解

1、背景

随着项目的增多，各个项目的版本之间存在差异，因此在升级时，维护项目版本和最新版本之间增量的sql脚本成为一个严重的问题，非常耗时耗力，因此引入一个数据库变更管理工具迫在眉睫。目前比较常用的有flyway和liquibase，liquibase使用xml文件来定义和管理数据库脚本，不依赖于具体的数据库，学习成本相对较高，功能丰富，有自己的一套语法规则；flyway是基于sql语句的，依赖于具体的数据库，使用较为简单，容易上手。我们的项目固定是mysql的数据库，且项目开发周期短，因此引入了flyway。

2、Flyway介绍

官方文档地址：DocumentationFlyway 

flyway实现数据变更管理的大致原理如下：使用一张表专门记录每一个sql脚本的执行情况，执行过的脚本不在重复执行，没有执行过的脚本在程序启动时自动执行。因此我们使用springboot集成flyway进行数据库变更管理，只需要如下两步：

• 将sql脚本按命名规则命名
• 将脚本存放到指定位置

2.1、文件命名规则

Flyway的脚本名称有一定的规则，一个完整的脚本名称由五部分组成：前缀+版本+分隔符+描述+文件后缀，前缀、分隔符和文件后缀，都可以通过配置项进行修改。下面介绍的是默认的配置。

前缀：V表示版本迁移，版本号必须唯一，会计算校验和，执行过的文件不允许修改，按版本顺序执行，一个脚本只会执行一次；

U表示撤销迁移，和V开头的版本号相同，表示撤销当前版本的迁移，sql文件编写与版本迁移相反作用的语句即可。

R表示可重复迁移，其没有版本，不是只运行一次，而是每次程序启动，校验发生修改时，就会执行，R始终是在V执行完成后再执行。

版本号：任意的数字版本均可，可以是一个完整的数字或者用点符号分割的数字，版本之间从左到右进行比较大小，遇到点符号进行分割，以0开头的数字会自动移除前面的0后比较大小，如下均是合法的版本：

• 1
• 001
• 6.3
• 1.2.3.4
• 2024.07.30
• 20240730

分割符：默认是两个下划线（__）作为分隔符，分割版本和描述。

描述：官方文档上说明是：下划线或者空格分割单词即可。实际短横线分割单词也可以，理论上只要不和分割符冲突即可。

文件后缀：默认是 .sql

如下均是合法的脚本名称：

详情请参考官方文档地址： 命名规则 

2.2、常用配置项

spring可能因为版本原因部分参数没有，根据实际版本配置

示例截图：

更多详细的配置项使用参考官方文档地址：Flyway配置项

3、项目集成Flyway

3.1、依赖引入

基于SpringBoot搭建的项目，如下引入即可，会自动引入关联的版本

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

3.2、相关配置项

配置项可以使用spring的配置文件设置，也可以通过Java代码进行设置

3.2.1、Spring中的配置项

spring:
  flyway: 
    #数据库存在表时，自动使用设置的基线版本（baseline-version），数据库不存在表时，即使设置了，也会从第一个版本开始执行，默认值为false
    baseline-on-migrate: true
    #基线版本号，baseline-on-migrate为true时小于等于此版本号的脚本不会执行，默认值为1
    baseline-version: 1.0.0
    #设置为false会删除指定schema下所有的表，生产环境务必禁用，spring中该参数默认是false，需要手动设置为true
    clean-disabled: true
    #sql脚本存放位置，允许设置多个location，用英文逗号分割，默认值为classpath:db/migration
    locations: classpath:db/migration,classpath:db/callback
    #是否替换sql脚本中的占位符，占位符默认是${xxx},默认是替换，如果不需要替换，可以设置为false
    placeholder-replacement: false

更多详细的配置，可以参考上面的官方配置文档，或者根据spring的相关参数提示查看。

3.2.2、Java代码实现

下面给出简单的代码示例（以下代码未经过测试，仅供参考）：

@Configuration
public class FlywayConfig {

    @Autowired
    private DataSource dataSource;

    @PostConstruct
    public void config() {
        Flyway flyway = Flyway.configure()
                .dataSource(dataSource)
                .baselineOnMigrate(true)
                .locations("db/migration")
                .baselineVersion("1.0.1")
                .cleanDisabled(true)
                .load();
        flyway.migrate();
    }
}

详细的相关的java方法调用参考：Flyway-Java文档

3.3、sql脚本存放位置

通过配置项spring.flyway.locations设置，默认值是classpath:db/migration，也可以参数配置指定位置(截图就是自定义的location位置)，多个location通过英文逗号分割开

3.4、回调操作

flyway支持在任意操作（migrate、undo、clean、info、validate、baseline和repair）的前后，执行自定义的代码或者脚本，下面给一份支持的事件表格，官网文档：Flyway callback

• 实现Flyway的callback接口

flyway默认是会执行db/callback下的sql脚本，如果不想执行，可以使用参数 flyway.skipDefaultCallbacks跳过，设置为true即可，sping里面的配置参数为：

spring: 
  flyway: 
    skip-default-callbacks: true

package org.example.config;

import org.flywaydb.core.api.callback.Callback;
import org.flywaydb.core.api.callback.Context;
import org.flywaydb.core.api.callback.Event;
import org.flywaydb.core.api.configuration.Configuration;

import java.sql.Connection;

public class MyFlywayCallback implements Callback {

    @Override
    public boolean supports(Event event, Context context) {
        return false;
    }

    @Override
    public boolean canHandleInTransaction(Event event, Context context) {
        return false;
    }

    /**
     * 根据各种事件来自定义处理逻辑
     */
    @Override
    public void handle(Event event, Context context) {
        //迁移发生错误后的事件
        if (Event.AFTER_MIGRATE_ERROR == event) {
            Configuration configuration = context.getConfiguration();
            Connection connection = context.getConnection();
            //自定义进行逻辑处理，并操作数据库

        } else if (Event.CREATE_SCHEMA == event) {
            //
        }
    }

    @Override
    public String getCallbackName() {
        return null;
    }
}

• 设置回调的sql文件

设置回调的sql文件的默认存放位置在db/callback下，sql文件的名称和上面表格的Migrate函数回调名称命名（beforeMigrate.sql，beforeRepeatables.sql）即可。

例如：清除执行失败的记录，便于我们开发，当sql脚本执行失败后，不需要手动去表中删除失败的记录，可以通过设置错误回调sql，自动删除失败的记录

sql脚本中的语句如下，此处可能因为配置的表名和字段不一样，有一些差别，视实际的表字段编写语句。

delete from flyway_schema_history where success=false;

注：执行失败的记录，如果不清除掉，修改脚本后再次执行就会报错，也可以使用repair指令来修复，repair有以下几个功能：

1. 移除表中执行记录为失败的数据
2. 将已经执行的迁移和可执行的迁移之间的校验和、描述和类型重新对齐
3. 删除数据表中，在当前location文件夹下不存在的迁移记录

• 低版本的flyway是实现FlywayCallback接口（不建议使用），截图如下：

3.5、兼容历史项目

实际环境中不可能总是在项目开始就引入flyway，也可能是在项目中间引入flyway，针对数据库已经存在表和数据的情况，应该如何处理，这里flyway也有对应的解决方案，通过引入基线版本的方式来兼容历史数据，通过两个参数进行控制，baselineOnMigrate=true 和 flyway.baselineVersion=0.0，前者用于开启基线迁移，后者指定基线的版本，如何理解？

假设目前的项目，已经存在了很多表，我们需要在当前的基础上使用flyway，第一步是制作初始化的sql脚本，即将当前项目已有的数据库表结构，整体导出为一个sql文件，命名为V1.0__init.sql，后续如果再新增表或者修改表，则可以按版本号递增命名，如V1.1__add_new_table.sql。

在开启基线迁移且基线版本设置为1.0的情况下：

1. 如果是历史环境升级，flyway会判断数据库非空，则会跳过1.0版本的脚本，从1.1开始执行，避免了1.0脚本执行报错的情况，
2. 如果是新部署的环境，flyway判断数据库为空，会直接从1.0版本顺序往下执行，此时设置的基线迁移和基线版本不会生效（数据库为空的情况下）
3. 如果存在很多个不同的环境，每个环境的数据库表都不一致，例如A环境有1,2两张表，B环境有1,2,3张表，C环境是1,2,4，但是最新的数据库表为1,2,3,4，此时如果你将1,2,3,4定义为基线版本，那么ABC环境就需要手动执行缺失的脚本，将其补齐到和基线脚本相同的位置

编写的脚本可以被反复执行，例如建表前判断表和字段时判断是否已经存在，insert数据时使用replace等等，但是不同的数据库支持的功能不一样，尽量写出可以重复执行的脚本，那么就可以减少手动补齐的工作量。

3.6、程序启动问题

程序的启动有时候会依赖于数据库的表，如果表没有创建完成，此时程序启动会出错，因此需要确保我们的程序中的数据库操作，在flyway处理完成后再执行，此处推荐两种方式避免这个问题：

第一是向spring注入bean时，代码里面会操作数据库，可以使用如下注解，等待flyway初始化完成后再进行

第二是使用ApplicationRunner或者CommandLineRunner的方式来进行程序初始化操作

3.7、其他问题

1、基线迁移有时会失效？

基线迁移生效的必须满足几个前提：

• 开启了基线迁移配置，设置了基线版本
• flyway运行前，数据库中已经存在其他表
• flyway_schema_history表不存在（首次执行）

所以需要确保代码中其他创建表的操作的顺序，有的生成表在flyway之前或者之后，会导致执行不满足预期

遇到一个问题，调试基线版本功能，flyway之前已经执行过，但是本次清除了表中的所有数据，启动程序发现基线迁移未生效，根据测试发现，就是不满足上面第三个条件，必须要把flyway_schema_history删除才可以