Flyway 入门教程

最新推荐文章于 2024-05-23 23:35:10 发布

大锅睿

最新推荐文章于 2024-05-23 23:35:10 发布

阅读量1.3k

点赞数 1

分类专栏： Java 数据库文章标签：数据库 java flyway

本文链接：https://blog.csdn.net/cwr452829537/article/details/126958180

版权

Java 同时被 2 个专栏收录

26 篇文章 2 订阅

订阅专栏

数据库

10 篇文章 0 订阅

订阅专栏

一、简单介绍

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

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

Flyway官方文档 https://flywaydb.org/documentation/

二、Flyway使用场景

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

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

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

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

三、Flyway工作原理

Flyway工作流程如下：

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

四、Flyway如何校验文件

Flyway获取 flyway_schema_history 中最新成功记录的版本号（基准version），与项目中db/migration目录中的脚本version进行比对，当脚本version大于基准version则执行。

其实我们在使用Flyway的时候，需要养成这样一个习惯，一旦执行过的sql脚本就不要去修改，如果需要对已有数据表进行增删改的操作，应该新建一个脚本执行。

但是对于修改已经执行过的sql脚本，Flyway也有预防，那就是checksum。每个sql脚本在执行前会将基本信息写入flyway_schema_history中，Flyway会把每个脚本作为输入，通过一系列算法输出一个整数值checksum来判断脚本是否有修改（哪怕是一个空格），Flyway在工作之前，会逐个脚本比对其数据库中的checksum值，如果计算结果不同，则会报mismatch的错误

Caused by: org.flywaydb.core.api.FlywayException: Validate failed: 
Migration checksum mismatch for migration version 20220916
-> Applied to database : -1745562156
-> Resolved locally    : -1169150251

五、使用Flyway

5.1 引入依赖

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

5.2 添加配置

5.2.1 SpringBoot配置

SpringBoot的配置比较方便，我们只需要在配置文件里面配置即可

spring:
  # 数据库连接配置
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/flyway_demo?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

5.2.2 SpringMVC配置

SpringMVC在xml里面配置比较麻烦，所以这里我们直接注入一个Flyway配置类

package net.glt.b2b2c.config;

import lombok.extern.slf4j.Slf4j;
import org.flywaydb.core.Flyway;
import org.flywaydb.core.api.FlywayException;
import org.springframework.context.annotation.Configuration;
import javax.annotation.PostConstruct;
import javax.sql.DataSource;

/**
 * @Description: FlyWay配置类
 * @Author: Very
 * @Date: 2022/9/20 17:04
 */
@Slf4j
@Configuration
public class FlywayConfiguration {

    private final DataSource dataSource;

    public FlywayConfig(DataSource dataSource) {
        this.dataSource = dataSource;
    }

    @PostConstruct
    public void migrate() {
        Flyway flyway = Flyway.configure()
                // 数据库配置
                .dataSource(dataSource)
                // 脚本目录，默认为db/migration（根目录为resources）
                .locations("db/migration")
                // 当迁移时发现目标schema非空，而且带有没有元数据的表时，是否自动执行基准迁移，默认false
                .baselineOnMigrate(true)
                // 迁移时编码
                .encoding("UTF-8")
                // 记录迁移日志表名称（默认为flyway_schema_history）
                .table("flyway_schema_history")
                // 关闭clean
                .cleanDisabled(true)
                .load();
        try {
            flyway.migrate();
        } catch (FlywayException e) {
            log.error("Flyway配置第一次加载出错", e);
            try {
                flyway.repair();//生成版本记录表
                log.info("Flyway配置修复成功");
                flyway.migrate();
                log.info("Flyway配置重新加载成功");
            } catch (Exception e1) {
                log.error("Flyway配置第二次加载出错", e1);
                throw e1;
            }
        }
    }
}

5.3 脚本准备

在配置文件指定目录添加脚本，例如上面脚本目录是resources/db/migration，Flyway只会扫描指定目录以及子目录

脚本的命名一定要规范，否则运行flyway会报错

命名规则主要有两种：

仅需要被执行一次的SQL命名以大写的"V"开头，V + 版本号(版本号的数字间以”.“或”_“分隔开) + 双下划线(用来分隔版本号和描述) + 文件描述 + 后缀名。例如： V20201100__create_user.sql、V2.1.5__create_user_ddl.sql、V4.1_2__add_user_dml.sql 。
可重复运行的SQL，则以大写的“R”开头，后面再以两个下划线分割，其后跟文件名称，最后.sql结尾，比如： R__truncate_user_dml.sql ，但一般不推荐使用。

其中，V开头的SQL执行优先级要比R开头的SQL优先级高

启动项目的时候，Flyway就会执行对应脚本，即执行 Flyway 的 migrate命令，执行的脚本、版本号、结果都会保存在对应的迁移日志表（默认为flyway_schema_history ）中

六、使用Maven插件

以上步骤中，每次想要 migration 都需要运行整个项目，并且只能执行 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&amp;useSSL=false&amp;serverTimezone=Asia/Shanghai
                </url>
                <user>root</user>
                <password>root</password>
                <driver>com.mysql.cj.jdbc.Driver</driver>
            </configuration>
        </plugin>
    </plugins>
</build>

可以使用的命令如下

1.baseline

对已经存在数据库Schema结构的数据库一种解决方案。

实现在非空数据库新建MetaData表，并把Migrations应用到该数据库；也可以在已有表结构的数据库中实现添加Metadata表。

2.clean（非常危险）

清除掉对应数据库Schema中所有的对象，包括表结构，视图，存储过程等，clean操作在dev 和 test阶段很好用，但在生产环境务必禁用。

3.info

用于打印所有的Migrations的详细和状态信息，也是通过MetaData和Migrations完成的，可以快速定位当前的数据库版本。

4.migrate

执行迁移，等同于项目启动执行的内容

5.repair

修复metaData表，该操作在metadata出现错误时很有用。

6.undo(社区版本不支持)

撤销操作

7.validate

验证已经执行的Migrations是否有变更，默认开启的，原理是对比MetaData表与本地Migrations的checkNum值，如果值相同则验证通过，否则失败。

七、特别说明

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

Flyway配置清单

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