# flywaydb

**Repository Path**: sunt/flywaydb

## Basic Information

- **Project Name**: flywaydb
- **Description**: flywaydb maven 和git实现数据库脚本持续集成
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2017-06-06
- **Last Updated**: 2025-01-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# flyway maven git数据库持续集成

Flyway是一款开源的数据库版本管理工具，它更倾向于规约优于配置的方式。Flyway可以独立于应用实现管理并跟踪数据库变更，支持数据库版本自动升级，并且有一套默认的规约，不需要复杂的配置，Migrations可以写成SQL脚本，也可以写在Java代码中，不仅支持Command Line和Java API，还支持Build构建工具和Spring Boot等，同时在分布式环境下能够安全可靠地升级数据库，同时也支持失败恢复等。
Flyway主要基于6种基本命令：Migrate, Clean, Info, Validate, Baseline and Repair。目前支持的数据库主要有：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对数据库进行版本管理主要由Metadata表和6种命令完成，Metadata主要用于记录元数据，每种命令功能和解决的问题范围不一样，以下分别对metadata表和这些命令进行阐述，其中的示意图都来自Flyway的官方文档。

### Metadata Table

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


| Field  | Type | Null | Key | Default  |
| --- | --- | --- | --- | --- |
| version_rank | int | NO | MUL | NULL |
| installed_rank | int | 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 | YES |  | NULL |
| installed_by | varchar(100) | NO |  | NULL |
| installed_on | timestamp | NO |  | CURRENT_TIMESTAMP |
| execution_time |  int|NO  | MUL | NULL |

### 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值，不过尽量不要这样操作，否则可能造成其它环境失败。

## 配置


| 参数 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- |
| url | YES |  | 数据库连接 |
| driver | NO | 根据URL自动检测 | 数据连接字符串 |
| serverId | NO | flyway-db | maven setting.xml中的serverid,用来验证权限 |
| user | NO |  | 连接数据库的用户名 |
| password | NO |  | 连接数据库的密码 |
| schamas | NO | url中的默认的schamas | 通过flyway管理的数据库的schamas,区分大小写 |
| table | NO | schema_version | Flyway元数据表名 |
| localtions | NO | filesystem: src/main/resources
/db/migration | 脚本路径，递归扫描 |
| sqlMigrationPrefix | NO | V | sql 迁移脚本名称的前缀 |
| repeatableSqlMigrationPrefix | NO | R | 可重复执行的sql 迁移文件名前缀 |
| sqlMigrationSeparator | NO | __ | sql 迁移脚本名称的分隔符 |
| sqlMigrationSuffix | NO | .sql | sql 迁移脚本名称的文件扩展名 |
| allowMixedMigrations | NO | false | 是否允许在同一迁移脚本中混合事务性和非事务性语句 |
| encoding | NO | UTF-8 | sql迁移脚本文件编码 |
| placeholderReplacement | NO | true | 占位符是否要被替换 |
| placeholders | NO | | sql迁移脚本中的占位符 |
| placeholderPrefix | NO |${ | 占位符前缀 |
| placeholderSuffix | YES |} | 占位符后缀 |
| resolvers | NO | | 自定义MigrationResolver的实现类的完全限定名称 |
| skipDefaultResolvers | NO | false | 是否跳过内置的resolvers（sql, jdbc and spring-jdbc），如果是，则仅仅运行自定义的resolvers |
| callbacks | NO |  | 自定义flywaycallback实现类的完全限定名 |
| skipDefaultCallbacks | NO | false | 是否跳过内置的callbacks（sql） |
| target | NO | lastest version | Flyway 应该迁移的脚本。高于target的迁移不会运行 |
| outOfOrder | NO | false | 是否允许执行乱序的脚本。如果为true,假如你现在已经执行的版本1和3，现在有一个版本V2，也会被应用，而不是被忽略 |
| validateOnMigrate | NO | true | 自定义flywaycallback实现类的完全限定名 |
| cleanOnValidationError | NO | false | 迁移合并失败后是否自动执行clean命令 |
| ignoreMissingMigrations | NO | false | 迁移合并失败后是否自动执行clean命令 |

https://flywaydb.org/documentation/maven/migrate


## maven 集成


### flyway-maven-plugin 插件配置
flyway 与maven集成，需要在pom.xml中引入flyway-maven-plugin插件，代码如下


```xml
 <plugin>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-maven-plugin</artifactId>
        <version>4.0.3</version>
        <configuration>
          <!--禁止执行clean指令-->
          <cleanDisabled>true</cleanDisabled>
          <ignoreFutureMigrations>false</ignoreFutureMigrations>
          <!--当迁移时发现目标schema非空，而且带有没有元数据的表时，是否自动执行基准迁移，默认false-->
          <baselineOnMigrate>true</baselineOnMigrate>
          <!--当发现校验错误时是否自动调用clean-->
          <cleanOnValidationError>false</cleanOnValidationError>
          <!--是否允许无序的迁移-->
          <outOfOrder>true</outOfOrder>
          <baselineVersion>1.0</baselineVersion>
          <driver>com.mysql.jdbc.Driver</driver>
          <url>jdbc:mysql://xxx.xxx.xx.x:3306/xxx</url>
          <user>db_user</user>
          <password>passwd</password>
        </configuration>
      </plugin>
```

另外，configuration标签内配置也可以在在maven变量或者系统环境变量中配置，配置名称为flyway.xxx，如cleanDisabled在变量里的名称为${flyway.cleanDisabled}，以maven配置为例：


```xml
<build>
    <plugins>
      <plugin>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-maven-plugin</artifactId>
        <version>4.0.3</version>
        <configuration>
          <!--禁止执行clean指令-->
          <cleanDisabled>true</cleanDisabled>
          <ignoreFutureMigrations>false</ignoreFutureMigrations>
          <!--当迁移时发现目标schema非空，而且带有没有元数据的表时，是否自动执行基准迁移，默认false-->
          <baselineOnMigrate>true</baselineOnMigrate>
          <!--当发现校验错误时是否自动调用clean-->
          <cleanOnValidationError>false</cleanOnValidationError>
          <!--是否允许无序的迁移-->
          <outOfOrder>true</outOfOrder>
          <baselineVersion>1.0</baselineVersion>
        </configuration>
      </plugin>
    </plugins>
  </build>
 <properties>
    <flyway.driver>com.mysql.jdbc.Driver</flyway.driver>
    <flyway.url>jdbc:mysql://xxx.xx.xxx.x:3306/TABLENAME</flyway.url>
    <flyway.user>root</flyway.user>
    <flyway.password>ccccccc</flyway.password>
    <flyway.skip>false</flyway.skip>
  </properties>
``` 


### 运行

默认运行阶段在pre-integration-test

* 合并/更新：mvn flyway:migrate
* 修复：mvn flyway:repair
* 清理：mvn flyway:clean