flyway 使用手册

📄字数 3.6K

👁️阅读量 加载中...

本文将介绍对 flyway-10.8.0 版本的适配情况以及如何连接 XuguDB ，如何使用 flyway 接入到项目中使用等。

框架名称	适配起始版本	官网地址	源框架下载地址	XuguDB 框架下载	demo程序地址
flyway	7.1.1	flyway 官网	flyway 源码	版本发布	xugu-flyway-demo

提示

其他支持版本可详见版本发布列表

一、使用说明

虚谷对 flyway 提供了两种获取方式，通过源码 install 进行本地 maven 仓库部署和通过 pom 本地引用 jar 包两种方式。

1.1 本地 maven 仓库部署

1.1.1 下载源码

从 flyway-xugu下载源码，获取虚谷适配的 flyway 框架源码。

图 1.1 github获取源码

1.1.2 使用 IDEA 编译工具打开源码

图 1.2 idea打开源码

提示

图 1.2 github 获取源码截图右侧 maven 中有红线报错，是因为 com.github.kornilova203:mongo-jdbc-driver:1.18 没有源码 jar 包所以出现异常提示，可忽略。不影响项目打包 。

1.1.3 模块 install

使用 maven 插件分别对红框中标注的模块进行 install。

图 1.3 maven树

1. flyway-core

图 1.4 flyway-core的install

2. flyway-commandline

图 1.5 flyway-commandline的install

3. flyway-xugu

图 1.6 flyway-xugu的install

4. flyway-maven

图 1.7 flyway-maven的install

1.1.4 添加 pom 依赖

<!-- 执行完install之后，在pom.xml中添加如下依赖 -->
<dependency>
   <groupId>org.flywaydb</groupId>
   <artifactId>flyway-core</artifactId>
   <version>10.8.0</version>
</dependency>
<dependency>
   <groupId>org.flywaydb</groupId>
   <artifactId>flyway-xugu</artifactId>
   <version>10.8.0</version>
</dependency>
<dependency>
   <groupId>org.flywaydb</groupId>
   <artifactId>flyway-commandline</artifactId>
   <version>10.8.0</version>
</dependency>
<plugin>
   <groupId>org.flywaydb</groupId>
   <artifactId>flyway-maven-plugin</artifactId>
   <version>10.8.0</version>
   <configuration>
      <url>jdbc:xugu://localhost:5138/flyway</url>
      <user>SYSDBA</user>
      <password>SYSDBA</password>
      <driver>com.xugu.cloudjdbc.Driver</driver>
      <schemas>test</schemas>
      <cleanDisabled>false</cleanDisabled>
   </configuration>
</plugin>

1.2 pom 本地引用 jar 包

1.2.1 解压文件

通过上方链接下载压缩包，并解压。

图 1.8 flyway的jar包

1.2.2 lib 文件夹

到项目跟路径下创建 lib 包并且把获取的 jar 包放入 lib 包中，然后在 pom.xml 文件中添加依赖。

图 1.9 项目创建lib包

<dependency>
   <groupId>org.flywaydb</groupId>
   <artifactId>flyway-core</artifactId>
   <version>10.8.0</version>
   <scope>system</scope>
   <systemPath>${project.basedir}/lib/flyway-core-10.8.0.jar</systemPath>
</dependency>
<dependency>
   <groupId>org.flywaydb</groupId>
   <artifactId>flyway-xugu</artifactId>
   <version>10.8.0</version>
   <scope>system</scope>
   <systemPath>${project.basedir}/lib/flyway-xugu-10.8.0.jar</systemPath>
</dependency>
<dependency>
   <groupId>org.flywaydb</groupId>
   <artifactId>flyway-commandline</artifactId>
   <version>10.8.0</version>
   <scope>system</scope>
   <systemPath>${project.basedir}/lib/flyway-commandline-10.8.0.jar</systemPath>
</dependency>

1.3 pom 依赖说明

需要导入的 jar 包包含以下：

<!-- 必要jar 包 -->
    <dependency>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-core</artifactId>
        <version>10.8.0</version>
    </dependency>
    <dependency>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-xugu</artifactId>
        <version>10.8.0</version>
    </dependency>

如果需要在开发过程中使用 maven 插件，则需要导入以下依赖：

<!-- 通过lib项目路径导入不能找到的jar包 -->
 <plugin>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-maven-plugin</artifactId>
    <version>10.8.0</version>
    <configuration>
        <url>jdbc:xugu://localhost:5138/flyway</url>
        <user>SYSDBA</user>
        <password>SYSDBA</password>
        <driver>com.xugu.cloudjdbc.Driver</driver>
        <schemas>test</schemas>
        <cleanDisabled>false</cleanDisabled>
    </configuration>
</plugin>

其中 configuration 标签中是所需连接配置信息

执行导包过后 maven 中会出现 flyway 相关插件。

图 1.10 flyway插件信息

注意

在 V9.0.3 版本之后，flyway-maven-plugin 插件中 cleanDisabled 配置项默认为 true ，即默认不会执行 clean 操作，如果需要执行 clean 操作，则需要设置 cleanDisabled 为 false 。即在pom.xml文件添加：<cleanDisabled>false</cleanDisabled>

警告

clean 在生产环境务必禁用。

1.4 flyway 功能支持情况

功能	是否支持	描述
baseline	是	对执行迁移时基准版本的描述
clean	是	清除掉对应数据库Schema中所有的对象，包括表结构，视图，存储过程等，clean操作在dev 和 test阶段很好用，但在生产环境务必禁用。
info	是	于打印所有的Migrations的详细和状态信息，也是通过MetaData和Migrations完成的，可以快速定位当前的数据库版本。
repair	是	repair操作能够修复metaData表，该操作在metadata出现错误时很有用。
validate	是	验证已经apply的Migrations是否有变更，默认开启的，原理是对比MetaData表与本地Migrations的checkNum值，如果值相同则验证通过，否则失败。
migrate	是	执行sql脚本到flyway_schema_history记录的最新版本的数据库文件(V) 以R开头的会每次都执行
undo	否	撤销操作，社区版不支持

提示

1. baseline
   对执行迁移时基准版本的描述。
2. clean
   清除掉对应数据库 Schema 中所有的对象，包括表结构，视图，存储过程等，clean 操作在 dev 和 test 阶段很好用，但在生产环境务必禁用。
3. info
   用于打印所有的 Migrations 的详细和状态信息，也是通过 MetaData 和 Migrations 完成的，可以快速定位当前的数据库版本。
4. repair
   repair 操作能够修复 metaData 表，该操作在 metadata 出现错误时很有用。
5. validate
   验证已经 apply 的 Migrations 是否有变更，默认开启的，原理是对比 MetaData 表与本地 Migrations 的 checkNum 值，如果值相同则验证通过，否则失败。
6. migrate
   执行 sql 脚本到 flyway_schema_history 记录的最新版本的数据库文件( V ) 以 R 开头的会每次都执行。
7. undo
   撤销操作，社区版不支持。

二、连接示例

2.1 前提条件

• 系统环境
• 计算机已安装 JDK 8 和 Maven。
• 计算机已安装 IntelliJ IDEA。
• 计算机已部署 XuguDB 12.0.0 或有能连接访问的虚谷数据库实例。
• 提前备好 flyway-xugu-10.8.0 的 jar 包。

2.2 操作步骤

2.2.1 步骤一：项目准备

通过上方 demo程序地址 ，获取 flyway 连接虚谷数据库的 demo 程序，并使用 idea 打开项目。

图 2.1 使用idea打开项目

2.2.1.1 项目介绍

1. sql 脚本
   db 文件夹下存放的文件均为 demo 程序测试使用，无需初始化。

图 2.2 sql脚本

2. 测试类
   TestFlywayPlugins.java 是单元测试类，测试类存放在 src/test/java 下。测试方式为参照 flyway 提供的接口来执行 flyway 的迁移操作以及其他操作。

图 2.3 测试类

3. 启动类
   FlywayTestDemoApplication.java 是 demo 程序的启动类，存放在 src/main/java 下。
   当项目配置文件application.yml文件中参数 enable=true 时，会自动执行 flyway 的 migrate 操作。

图 2.4 启动类

4. maven 插件
   xml 中配置了 flyway 相关信息过后则会出现 maven 插件提供的 flyway 操作。

图 2.5 maven插件

2.2.2 步骤二： 修改数据库连接信息

application.yml 是该测试 demo 的配置文件，路径为项目路径下的 src/main/resources ，修改配置文件中的 url 、username 、passowrd 为自己的数据库信息。

图 2.6 修改数据库连接信息

2.2.3 步骤三： 运行程序 - 此处以 maven 插件为例

执行一下插件功能，均为鼠标双击。

1. 执行 baseline

图 2.7 baseline执行结果

执行成功过后去数据查看。

图 2.8 验证baseline执行结果

创建了 flyway_schema_history 表 并插入了--基准版本。

2. 执行 info

图 2.9 info执行结果

3. 执行 migrate

图 2.10 migrate执行结果

成功后查看数据库 flyway_schema_history。

图 2.11 验证migrate执行结果

记录着所有的迁移信息。再次执行 info 可以看到信息已经更新。

图 2.12 验证migrate执行结果2

4. 执行 validate

图 2.13 validate执行结果

已验证所有 sql 文件都已执行完毕。

5. 执行 repair
   先随意修改 sql 脚本中的文件模拟文件未修改但是报错的情况，再次执行 validate 发现文件的 checkNum 值和 flyway_schema_history 中的 checkNum 值不一致。

图 2.14 异常场景

这时可执行 repair 修复 checkNum。

图 2.15 repair执行结果

再次执行 validate 验证成功。

图 2.16 验证repair执行结果

三、常见问题&解决办法

1. 尽量不要手动修改 flyway_schema_history 表的数据，会导致程序校验该数据不一致。