快速掌握和使用Flyway的详细教程

什么是flyway?

转载：

flyway is an open-source database migration tool. it strongly favors simplicity and convention over configuration.

flyway是一款开源的数据库版本管理工具，它更倾向于规约优于配置的方式。flyway可以独立于应用实现管理并跟踪数据库变更，支持数据库版本自动升级，并且有一套默认的规约，不需要复杂的配置，migrations可以写成sql脚本，也可以写在java代码中，不仅支持command line和java api，还支持build构建工具和spring boot等，同时在分布式环境下能够安全可靠地升级数据库，同时也支持失败恢复等。

flyway主要基于6种基本命令：migrate,clean,info,validate,baselineandrepair，稍候会逐一分析讲解。目前支持的数据库主要有：oracle, sql server, sql azure, db2, db2 z/os, mysql(including amazon rds), mariadb, google cloud sql, postgresql(including amazon rds and heroku), redshift, vertica, h2, hsql, derby, sqlite, sap hana, soliddb, sybase ase and phoenix.

关于flyway的优势，支持的数据库以及与其他数据库版本工具的对比，可以阅读flyway官网介绍。

为什么使用flyway?

通常在项目开始时会针对数据库进行全局设计，但在开发产品新特性过程中，难免会遇到需要更新数据库schema的情况，比如：添加新表，添加新字段和约束等，这种情况在实际项目中也经常发生。那么，当开发人员完成了对数据库更的sql脚本后，如何快速地在其他开发者机器上同步？并且如何在测试服务器上快速同步？以及如何保证集成测试能够顺利执行并通过呢？

假设以spring boot技术栈项目为例，可能有人会说，本地使用hibernate自动更新数据库schema模式，然后让qa或dev到测试服务器上手动执行sql脚本，同时可以写一个gradle任务自动执行更新。

个人觉得，对于hibernate自动更新数据库，感觉不靠谱，不透明，控制*度不高，而且有时很容易就会犯错，比如：用sql创建的某个字段为varchar类型，而在entity中配置的为char类型，那么在运行集成测试时，自动创建的数据库表中的字段为char类型，而实际sql脚本期望的是varchar类型，虽然测试通过了，但不是期望的行为，并且在本地bootrun或服务器上运行service时都会失败。另外，到各测试服务器上手动执行sql脚本费时费神费力的，干嘛不自动化呢，当然，对于高级别和prod环境，还是需要dba手动执行的。最后，写一段自动化程序来自动执行更新，想法是很好的，那如果已经有了一些插件或库可以帮助你更好地实现这样的功能，为何不好好利用一下呢，当然，如果是为了学习目的，重复造*是无可厚非的。

其实，以上问题可以通过flyway工具来解决，flyway可以实现自动化的数据库版本管理，并且能够记录数据库版本更新记录，flyway官网对why database migrations结合示例进行了详细的阐述，有兴趣可以参阅一下。

flyway如何工作的?

flyway对数据库进行版本管理主要由metadata表和6种命令完成，metadata主要用于记录元数据，每种命令功能和解决的问题范围不一样，以下分别对metadata表和这些命令进行阐述，其中的示意图都来自flyway的官方文档。

metadata table

flyway中最核心的就是用于记录所有版本演化和状态的metadata表，在flyway首次启动时会创建默认名为schema_version的元数据表，其表结构为(以mysql为例)：

field	type	null	key	default
version_rank	int(11)	no	mul	null
installed_rank	int(11)	no	mul	null
version	varchar(50)	no	pri	null
description	varchar(200)	no		null
type	varchar(20)	no		null
script	varchar(1000)	no		null
checksum	int(11)	yes		null
installed_by	varchar(100)	no		null
installed_on	timestamp	no		current_timestamp
execution_time	int(11)	no		null
success	tinyint(1)	no	mul	null

flyway官网上提供了一个很清晰的示例how flyway works，可以参阅一下。

migrate

migrate是指把数据库schema迁移到最新版本，是flyway工作流的核心功能，flyway在migrate时会检查metadata(元数据)表，如果不存在会创建metadata表，metadata表主要用于记录版本变更历史以及checksum之类的。

migrate时会扫描指定文件系统或classpath下的migrations(可以理解为数据库的版本脚本)，并且会逐一比对metadata表中的已存在的版本记录，如果有未应用的migrations，flyway会获取这些migrations并按次序apply到数据库中，否则不需要做任何事情。另外，通常在应用程序启动时应默认执行migrate操作，从而避免程序和数据库的不一致性。

clean

clean相对比较容易理解，即清除掉对应数据库schema中的所有对象，包括表结构，视图，存储过程，函数以及所有的数据等都会被清除。

clean操作在开发和测试阶段是非常有用的，它能够帮助快速有效地更新和重新生成数据库表结构，但特别注意的是：不应在production的数据库上使用！

info

info用于打印所有migrations的详细和状态信息，其实也是通过metadata表和migrations完成的，下图很好地示意了info打印出来的信息。

info能够帮助快速定位当前的数据库版本，以及查看执行成功和失败的migrations。

validate

validate是指验证已经apply的migrations是否有变更，flyway是默认是开启验证的。

validate原理是对比metadata表与本地migrations的checksum值，如果值相同则验证通过，否则验证失败，从而可以防止对已经apply到数据库的本地migrations的无意修改。

baseline

baseline针对已经存在schema结构的数据库的一种解决方案，即实现在非空数据库中新建metadata表，并把migrations应用到该数据库。

baseline可以应用到特定的版本，这样在已有表结构的数据库中也可以实现添加metadata表，从而利用flyway进行新migrations的管理了。

repair

repair操作能够修复metadata表，该操作在metadata表出现错误时是非常有用的。

repair会修复metadata表的错误，通常有两种用途：

• 移除失败的migration记录，该问题只是针对不支持ddl事务的数据库。
• 重新调整已经应用的migratons的checksums值，比如：某个migratinon已经被应用，但本地进行了修改，又期望重新应用并调整checksum值，不过尽量不要这样操作，否则可能造成其它环境失败。

如何使用flyway?

这里将主要关注在gradle和spring boot中集成并使用flyway，数据库通常会采用mysql、postgresql、h2或hsql等。

正确创建migrations

migrations是指flyway在更新数据库时是使用的版本脚本，比如：一个基于sql的migration命名为v1__init_tables.sql，内容即是创建所有表的sql语句，另外，flyway也支持基于java的migration。flyway加载migrations的默认locations为classpath:db/migration，也可以指定filesystem:/project/folder，其加载是在runtime自动递归地执行的。

除了需要指定location外，flyway对migrations的扫描还必须遵从一定的命名模式，migration主要分为两类：versioned和repeatable。

versioned migrations

一般常用的是versioned类型，用于版本升级，每一个版本都有一个唯一的标识并且只能被应用一次，并且不能再修改已经加载过的migrations，因为metadata表会记录其checksum值。其中的version标识版本号，由一个或多个数字构成，数字之间的分隔符可以采用点或下划线，在运行时下划线其实也是被替换成点了，每一部分的前导零会被自动忽略。

repeatable migrations

repeatable是指可重复加载的migrations，其每一次的更新会影响checksum值，然后都会被重新加载，并不用于版本升级。对于管理不稳定的数据库对象的更新时非常有用。repeatable的migrations总是在versioned之后按顺序执行，但开发者必须自己维护脚本并且确保可以重复执行，通常会在sql语句中使用create or replace来保证可重复执行。

默认情况下基于sql的migration文件的命令规则如下图所示：

其中的文件名由以下部分组成，除了使用默认配置外，某些部分还可自定义规则。

• prefix: 可配置，前缀标识，默认值v表示versioned，r表示repeatable
• version: 标识版本号，由一个或多个数字构成，数字之间的分隔符可用点.或下划线_
• separator: 可配置，用于分隔版本标识与描述信息，默认为两个下划线__
• description: 描述信息，文字之间可以用下划线或空格分隔
• suffix: 可配置，后续标识，默认为.sql
  

另外，关于如何使用基于java的migrations，有兴趣可以参考java-based migrations。

支持的数据库
目前flyway支持的数据库还是挺多的，包括：oracle, sql server, sql azure, db2, db2 z/os, mysql(including amazon rds), mariadb, google cloud sql, postgresql(including amazon rds and heroku), redshift, vertica, h2, hsql, derby, sqlite, sap hana, soliddb, sybase ase and phoenix。
目前来说，个人用得比较多的数据库是postgresql、mysql、h2和hsql，针对每种数据库的flyway.url示例配置为：

另外，关于如何使用基于java的migrations，有兴趣可以参考java-based migrations。

支持的数据库

目前flyway支持的数据库还是挺多的，包括：oracle, sql server, sql azure, db2, db2 z/os, mysql(including amazon rds), mariadb, google cloud sql, postgresql(including amazon rds and heroku), redshift, vertica, h2, hsql, derby, sqlite, sap hana, soliddb, sybase ase and phoenix。
目前来说，个人用得比较多的数据库是postgresql、mysql、h2和hsql，针对每种数据库的flyway.url示例配置为：

# postgresql
flyway.url = jdbc:postgresql://localhost:5432/postgres?currentschema=myschema
# mysql
flyway.url = jdbc:mysql://localhost:3306/testdb?servertimezone=utc&usessl=true
# h2
flyway.url = jdbc:h2:./.tmp/testdb
# hsql
flyway.url = jdbc:hsqldb:hsql//localhost:1476/testdb

flyway命令行

flyway的命令行工具支持直接在命令行中运行migrate,clean,info,validate,baseline和repair6种命令，不需要借助其他build工具，不需要应用程序运行在jvm中，只需要单纯的命令行即可，但需要根据不同的操作系统并安装该命令行工具。flyway会依次搜索以下配置文件，越靠后的配置会覆盖靠前的配置：

• /conf/flyway.conf
• /flyway.conf
• /flyway.conf

一个典型flyway项目示例目录结构如下：

更多关于flyway命令行使用可以参考flyway command-line。

在gradle中的应用

首先需要在gradle中引入flyway插件，通常有两种方式：

方式一：采用buildscript依赖方式。

buildscript {
repositories {
mavencentral()
}
dependencies {
classpath("org.flywaydb:flyway-gradle-plugin:4.0.3")
}
}
apply plugin: 'org.flywaydb.flyway'

方式二（推荐）：采用dsl方式引用plugins。

plugins {
id "org.flywaydb.flyway" version "4.0.3"
}

而在gradle中配置flyway properties有两种方式：

方式一：在build.gradle中配置flyway properties。

flyway {
url = jdbc:h2:./.tmp/testdb
user = sa
password =
}
# 或者写成：
project.ext['flyway.url'] = 'jdbc:h2:./.tmp/testdb'
project.ext['flyway.user'] = 'sa'
project.ext['flyway.password'] = ''

方式二：在gradle.properties中配置flyway properties。

flyway.url = jdbc:h2:./.tmp/testdb
flyway.user = sa
flyway.password =

如果期望在运行gradle clean/build tasks时自动执行flyway的某些任务，可以设置dependson，若不期望隐式执行flyway任务，可以不配置。

clean.dependson flywayrepair # to repair the flyway metadata table
build.dependson flywaymigrate # to migrate the schema to the latest version

另外，其它tasks：flywayinfo,flywayvalidate,flywaybaseline分别对应到flyway的命令。在使用spring boot时，运行./gradlew bootrun会自动检查并加载最新的db.migration脚本。

特别注意：在production环境中不应执行./gradlew flywayclean，除非你知道自己的行为和目的，因为该命令会清除所有的数据库对象，相当危险。

更多关于flyway在gradle中的使用请参阅flyway gradle plugin。

与spring boot集成

在spring boot中，如果加入flyway的依赖，则会自动引用flyway并使用默认值，但可以修改并配置flywayproperties。

flyway.baseline-description= # the description to tag an existing schema with when executing baseline.
flyway.baseline-version=1 # version to start migration.
flyway.baseline-on-migrate=false # whether to execute migration against a non-empty schema with no metadata table
flyway.check-location=false # check that migration scripts location exists.
flyway.clean-on-validation-error=false # will clean all objects. warning! do not enable in production!
flyway.enabled=true # enable flyway.
flyway.encoding=utf-8 # the encoding of migrations.
flyway.ignore-failed-future-migration=true # ignore future migrations when reading the metadata table.
flyway.init-sqls= # sql statements to execute to initialize a connection immediately after obtaining it.
flyway.locations=classpath:db/migration # locations of migrations scripts.
flyway.out-of-order=false # allows migrations to be run "out of order".
flyway.placeholder-prefix= # the prefix of every placeholder.
flyway.placeholder-replacement=true # whether placeholders should be replaced.
flyway.placeholder-suffix=} # the suffix of every placeholder.
flyway.placeholders.*= # placeholders to replace in sql migrations.
flyway.schemas= # default schema of the connection and updating
flyway.sql-migration-prefix=v # the file name prefix for sql migrations
flyway.sql-migration-separator=__ # the file name separator for sql migrations
flyway.sql-migration-suffix=.sql # the file name suffix for sql migrations
flyway.table=schema_version # the name of flyway's metadata table.
flyway.url= # jdbc url of the database to migrate. if not set, the primary configured data source is used.
flyway.user= # login user of the database to migrate. if not set, use spring.datasource.username value.
flyway.password= # jdbc password if you want flyway to create its own datasource.
flyway.validate-on-migrate=true # validate sql migration crc32 checksum in classpath.

若使用gradle，通常在build.gradle引入org.flywaydb:flyway-core:4.0.3依赖后即可使用。可能会有以下几种需求：

• 在本地run和tests都会使用内存数据库，其中的spring.jpa.hibernate.ddl-auto都设置为validate，schema不需要hibernate自动生成，并期望使用flyway，而在线上环境会使用真实数据库，并不期望使用flyway，如何实现呢？
• 解决方案：可以在common.properties中配置flyway.enabled=false，然后在local或dev的配置中启用flyway即可。通常推荐使用此模式，毕竟可以对不同的环境进行控制，另外本地run不会依赖真实数据库，又能保证数据库schema是按脚本创建的。
• 在运行tests会使用内存数据库，有单独的配置文件，不使用flyway，而在本地bootrun时会使用真实数据库，使用flyway，毕竟不想每次schema改后都在本地手动去执行脚本，如何实现？

解决方案：设置bootrun.dependson动态添加flyway的依赖即可：

addflywaydenpendency {
dolast {
dependencies {
compile('org.flywaydb:flyway-core:4.0.3')
}
}
}
bootrun.dependson=addflywaydenpendency

若项目有多个团队同时开发不同的功能，需要新建多个分支，并且都会涉及到数据库schema更改，当后期merge时，migration的版本如何控制并且不会产生数据库更改的冲突呢？
解决方案：如果两个分支的数据库更改有冲突，要么最初数据库设计不合理，要么目前数据库更改不合理，所以需要团队进行全局考虑和协调。而针对数据库在同一段时间有修改，但不会造成冲突的情况，通常实际项目中主要存在这样的情况，那可以设置flyway.out-of-order=true，这样允许当v1和v3已经被应用后，v2出现时同样也可以被应用。其实在本地使用内存数据库不会存在该问题，因为数据库所有对象会自动清除掉，而在local或dev中使用真实数据库时可遇到这样的问题，因此需要注意一下了。
另外，值得一提的是flyway的参数ignore-failed-future-migration默认为true，使用情形为：当rollback数据库更改到旧版本，而metadata表中已存在了新版本时，flyway会忽略此错误，只会显示警告信息。

结束语

总得来说，flyway可以有效改善数据库版本管理方式，如果项目中还未使用，不防尝试一下。如果有兴趣，也可以关注mybatis migration，功能支持没有flyway多，属于更轻量级的数据库版本管理工具。如果在使用过程中遇到了问题或坑，欢迎留言一起交流讨论。

references

flyway documentation

gradle plugin: flyway

spring common application properties

execute flyway database migrations on startup

到此这篇关于快速掌握和使用flyway的详细教程的文章就介绍到这了,更多相关使用flyway的技巧内容请搜索以前的文章或继续浏览下面的相关文章希望大家以后多多支持！