Flyway 简单入门教程

秒速五厘米 2022-11-26 06:52 133阅读 0赞

## 一、前言 ##

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

## 二、简单介绍 ##

### \# 2.1 主要特性 ###

1.  `普通 SQL：纯 SQL 脚本(包括占位符替换)没有专有的XML格式，没有锁定`
2.   
3.  `无限制：使用 Java 代码来进行一些高级数据操作`
4.   
5.  `零依赖：只需运行在 Java6(及以上)和数据库所需的 JDBC 驱动`
6.   
7.  `约定优于配置：迁移时，自动查找系统文件和类路径中的 SQL 文件或 Java 类`
8.   
9.  `高可靠性：在集群环境下进行数据库升级是安全可靠的`
10.  
11. `云支持：完全支持 Microsoft SQL Azure, Google Cloud SQL & App Engine、Heroku Postgres 和 Amazon RDS`
12.  
13. `自动迁移：使用 Flyway 提供的 API，让应用启动和迁移同时工作`
14.  
15. `快速失败：损坏的数据库或失败的迁移可以防止应用程序启动`
16.  
17. `数据库清理：在一个数据库中删除所有的表、视图、触发器，而不是删除数据库本身`

### \# 2.2 运行原理 ###

当 Flyway 连接数据库中的 schema 后，会先检查是否已存在 **flyway\_schema\_history** 表，如果没有则创建。该表用于跟踪数据库的状态，如数据迁移的版本，迁移成功状态等信息。

当 **flyway\_schema\_history** 存在后，Flyway 会扫描文件系统或应用中的 classpath 目录的数据迁移文件，然后根据它们的版本号进行按序迁移，如下图：

[![format_png][]][format_png 1]

**flyway\_schema\_history** 表记录的内容如下：

<table> 
 <thead> 
  <tr> 
   <th>installed_rank</th> 
   <th>version</th> 
   <th>description</th> 
   <th>type</th> 
   <th>script</th> 
   <th>checksum</th> 
   <th>installed_by</th> 
   <th>installed_on</th> 
   <th>execution_time</th> 
   <th>success</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>1</td> 
   <td>1</td> 
   <td>Initial Setup</td> 
   <td>SQL</td> 
   <td>V1__Initial_Setup.sql</td> 
   <td>1996767037</td> 
   <td>axel</td> 
   <td>2016-02-04 22:23:00.0</td> 
   <td>546</td> 
   <td>true</td> 
  </tr> 
  <tr> 
   <td>2</td> 
   <td>2</td> 
   <td>First Changes</td> 
   <td>SQL</td> 
   <td>V2__First_Changes.sql</td> 
   <td>1279644856</td> 
   <td>axel</td> 
   <td>2016-02-06 09:18:00.0</td> 
   <td>127</td> 
   <td>true</td> 
  </tr> 
 </tbody> 
</table>

**由于 flyway\_schema\_history 表中记录了迁移的版本号，如果文件的版本号小于或等于标记为当前版本的版本号，则忽略它们不执行。**

上边描述的内容或许对读者来说还不够直观，那么下面我们就开始进行实战演练。

## 三、实战 ##

> 测试环境：Mysql5.7

新建一个 Maven 项目。

### \# 3.1 添加依赖 ###

1.  ``
2.  `<dependency>`
3.  `<groupId>org.flywaydb</groupId>`
4.  `<artifactId>flyway-core</artifactId>`
5.  `<version>5.2.4</version>`
6.  `</dependency>`
7.   
8.  `<dependency>`
9.  `<groupId>mysql</groupId>`
10. `<artifactId>mysql-connector-java</artifactId>`
11. `<version>8.0.15</version>`
12. `</dependency>`

### \# 3.2 配置数据迁移文件 ###

在项目的 src/main/resources 下创建 db/migration 目录，该目录下放置需要数据迁移的文件。

数据迁移文件名称格式为：**V\[version\]\_\_\[name\].sql**。

**注意：名称中\[version\]和\[name\]之间是两个下划线！**

本次测试新建名为 V1\_\_Create\_person\_table.sql 的文件，内容如下:

1.  `create table PERSON (`
2.  `ID int not null,`
3.  `NAME varchar(100) not null`
4.  `);`

版本 1 数据迁移的内容是创建一张 PERSON 表。

### \# 3.3 编码 ###

1.  `public class FlywayTest {`
2.   
3.  `public static void main(String[] args) {`
4.  `String url = "jdbc:mysql://127.0.0.1:3306/flyway?useUnicode=true&characterEncoding=UTF-8&allowMultiQueries=true&rewriteBatchedStatements=true&useSSL=false&serverTimezone=GMT%2B8";`
5.  `String user = "root";`
6.  `String password = "tiger";`
7.  `Flyway flyway = Flyway.configure().dataSource(url, user, password).load();`
8.   
9.  `// 创建 flyway_schema_history 表`
10. `// flyway.baseline();`
11.  
12. `// 删除 flyway_schema_history 表中失败的记录`
13. `// flyway.repair();`
14.  
15. `// 检查 sql 文件`
16. `// flyway.validate();`
17.  
18. `// 执行数据迁移`
19. `flyway.migrate();`
20.  
21. `// 删除当前 schema 下所有表`
22. `// flyway.clean();`
23. `}`
24. `}`

执行结果如下图：

[![aHR0cDovL2ltYWdlcy5leHRsaWdodC5jb20vZmx5d2F5LTAxLmdpZg][]][aHR0cDovL2ltYWdlcy5leHRsaWdodC5jb20vZmx5d2F5LTAxLmdpZg 1]

图中，数据库 flyway 中创建了 **flyway\_schema\_history** 表和 PERSON 表，数据成功迁移到指定数据库中。

当系统升级时又需要做数据迁移，我们只需在 db/migration 目录下再放置新版本的 sql 文件即可。

比如，我们再新建一个名为 V2\_\_Add\_people.sql 文件，内容如下：

1.  `insert into PERSON (ID, NAME) values (1, 'Axel');`
2.  `insert into PERSON (ID, NAME) values (2, 'Mr. Foo');`
3.  `insert into PERSON (ID, NAME) values (3, 'Ms. Bar');`

版本 2 的数据迁移内容是往 PERSON 表中插入 3 条数据。

再次执行上边的程序，演示效果图如下：

[![aHR0cDovL2ltYWdlcy5leHRsaWdodC5jb20vZmx5d2F5LTAyLmdpZg][]][aHR0cDovL2ltYWdlcy5leHRsaWdodC5jb20vZmx5d2F5LTAyLmdpZg 1]

## 四、Spring Boot 整合 ##

### \# 4.1 添加依赖 ###

1.  `<dependency>`
2.  `<groupId>org.springframework.boot</groupId>`
3.  `<artifactId>spring-boot-starter-jdbc</artifactId>`
4.  `</dependency>`
5.   
6.  `<dependency>`
7.  `<groupId>mysql</groupId>`
8.  `<artifactId>mysql-connector-java</artifactId>`
9.  `</dependency>`
10.  
11. `<dependency>`
12. `<groupId>org.flywaydb</groupId>`
13. `<artifactId>flyway-core</artifactId>`
14. `</dependency>`

### \# 4.2 application.yml ###

1.  `spring:`
2.  `datasource:`
3.  `url: jdbc:mysql://127.0.0.1:3306/flyway?useUnicode=true&characterEncoding=UTF-8&allowMultiQueries=true&rewriteBatchedStatements=true&useSSL=false&serverTimezone=GMT%2B8`
4.  `username: root`
5.  `password: tiger`
6.  `flyway:`
7.  `enabled: true`
8.  `# 禁止清理数据库表`
9.  `clean-disabled: true`
10. `# 如果数据库不是空表，需要设置成 true，否则启动报错`
11. `baseline-on-migrate: true`
12. `# 与 baseline-on-migrate: true 搭配使用`
13. `baseline-version: 0`
14. `locations:`
15. `- classpath:db/migration/mysql（根据个人情况设置）`

将需数据迁移的 sql 文件放置到 db/migration/mysql 目录中，启动 Spring Boot 项目即可运行 Flyway 进行数据迁移。

测试结果同上，此处不再张贴。

**注意事项：**

如果 flyway 不是项目初期引入，而是在数据库已有表的情况下引入时必须设置 **baseline-on-migrate: true**，设置该配置启动项目后，flyway 就会在数据库中创建 **flyway\_schema\_history** 表，并且会往该表中插入一条 version = 1 的建表记录，如果迁移数据有 V1\_\_ 开头的文件，扫描文件会忽略该文件不执行迁移，进而可能引发其他迁移数据出错的问题。

以上边的 2 个 sql 文件为例进行演示，flyway 库中已有一张 test 表，运行程序结果如下：

[![format_png 2][]][format_png 2 1]

由于忽略了 V1\_\_Create\_person\_table.sql ，库中就不创建 PERSON 表，在迁移 V2\_\_Add\_people.sql 文件中的数据时必然失败。

解决方案先删除**flyway\_schema\_history** 表， 然后配置文件中设置 **baseline-version: 0**，或修改数据迁移文件版本名称，最后再次启动应用即可。

## 五、参考资料 ##

[Flyway 官网][Flyway]

[Spring Boot 文档][Spring Boot]

[https://www.extlight.com/2019/03/22/Flyway-%E7%AE%80%E5%8D%95%E5%85%A5%E9%97%A8%E6%95%99%E7%A8%8B/][https_www.extlight.com_2019_03_22_Flyway-_E7_AE_80_E5_8D_95_E5_85_A5_E9_97_A8_E6_95_99_E7_A8_8B]

[format_png]: /images/20221124/217561f3a1b14f7ba2d6f02384e907d6.png
[format_png 1]: http://images.extlight.com/flyway-03.jpg
[aHR0cDovL2ltYWdlcy5leHRsaWdodC5jb20vZmx5d2F5LTAxLmdpZg]: /images/20221124/e11f3036050b450e9f230dc2a4146ede.png
[aHR0cDovL2ltYWdlcy5leHRsaWdodC5jb20vZmx5d2F5LTAxLmdpZg 1]: http://images.extlight.com/flyway-01.gif
[aHR0cDovL2ltYWdlcy5leHRsaWdodC5jb20vZmx5d2F5LTAyLmdpZg]: /images/20221124/f651464936d04907861e14b2200bed4e.png
[aHR0cDovL2ltYWdlcy5leHRsaWdodC5jb20vZmx5d2F5LTAyLmdpZg 1]: http://images.extlight.com/flyway-02.gif
[format_png 2]: /images/20221124/ad5e3249e4ae45df8b0ce69827651c56.png
[format_png 2 1]: http://images.extlight.com/flyway-04.jpg
[Flyway]: https://flywaydb.org/documentation/api/
[Spring Boot]: https://docs.spring.io/spring-boot/docs/current/reference/html/howto-database-initialization.html#howto-execute-flyway-database-migrations-on-startup
[https_www.extlight.com_2019_03_22_Flyway-_E7_AE_80_E5_8D_95_E5_85_A5_E9_97_A8_E6_95_99_E7_A8_8B]: https://www.extlight.com/2019/03/22/Flyway-%E7%AE%80%E5%8D%95%E5%85%A5%E9%97%A8%E6%95%99%E7%A8%8B/