项目在多环境迭代开发过程中,数据库的表结构不断变更,在部署时,往往会出现数据库表结构未及时变更导致出现问题,耗费在表结构上的时间相当多,上线过程持续痛苦,代码有 GIT/SVN 来控制,数据库中的表版本也可以做到版本控制,本文讲解通过 flyway 的方式来管理数据库版本变动。

项目痛点

一个项目单个环境迭代开发的过程中,对于数据库表的修改 DDL,可以通过版本控制工具一起进行控制。只需要在项目上线之前,人工执行新增的 DDL 即可,DDL 的版本是与当前项目迭代版本一致,细致点不至于出现问题。

单个环境版本迭代,数据库的版本号变更流程如下图:

对于偏企业服务的公司而言,同一个项目会同时部署到多套环境当中。随着项目迭代进行,不同环境的项目版本可能并非是同步一致的,甚至因为有的环境需要定制化开发,出现同一个项目多个分支,代码也愈行愈远。

多个环境版本迭代,数据库的版本号变更流程如下图:

于是在这种情况下,上线服务之前就很痛苦,要想起上线环境的当前表版本是多少,想不起来,就要对比线上库里的表,判断是否执行过了增量的 DDL,每个环境的增量 DDL 都可能是不同的,需要针对每个环境写不同的 DDL,发布时战战兢兢地生怕漏了执行哪个版本的 DDL 导致线上 Bug。

那如何解决这种糟糕的情况呢?

理想状态:项目启动时自动维护数据库版本到最新,不需要人工处理 DDL,避免出错。

Flyway 就提供了达到这种理想状态的功能。

先说一下 Flyway 的原理。

开发者将每个版本的 DDL 放到项目中,项目在新环境启动时,会自动创建一张表用于记录 DDL 的版本信息,随后自动执行未执行过的 DDL,同时将执行过的 DDL 信息存入元数据表中。下次再启动时,检测到执行过了,就不会重复执行。

本文环境

  • SpringBoot 2.1.3.RELEASE
  • Flyway 5.2.1

迁移步骤

  1. 引入依赖

    1
    2
    3
    4
    5
    <dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
    <version>6.4.4</version>
    </dependency>

    注:如果 springboot 版本低于 2.0.0,最好使用 5.2.1 版本的 flyway-core

  2. 添加 flyway 配置文件

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    spring:
    flyway: # flyway 数据库 DDL 版本控制
    enabled: true # 正式环境才开启
    clean-disabled: true # 禁用数据库清理
    encoding: UTF-8
    locations: classpath:/db
    # flyway 会在库中创建此名称元数据表,用于记录所有版本演化和状态,同一个库不同项目可能冲突,每个项目一张表来记录
    table: flyway_schema_history_FlywayExample #TODO 值的后缀指定为当前项目名称
    baseline-version: 1 # 基线版本默认开始序号 默认为 1
    baseline-on-migrate: true # 针对非空数据库是否默认调用基线版本,为空的话默认会调用基线版本
    placeholders: # 定义 afterMigrateError.sql 要清理的元数据表表名
    flyway-table: ${spring.flyway.table}

    flyway 在启动的时候会自动创建一张名称为 flyway_schema_history 的元数据表,如果多个项目连接的是同一个数据库,会产生冲突影响,所以需要每个项目都有一张自己的元数据表,指定 spring.flyway.table 的值即可,可以指定为 flyway_schema_history_{项目名称},这样基本可以做到不会发生冲突了。

  3. 项目 resource 目录添加文件夹.

    创建上一步中 spring.flyway.locations 中指定值的目录,本文是创建 db 目录.

  4. 项目 SQL 迁移.

    SQL 迁移这里有两种情况,第一种是当前项目在所有环境都是初次部署,即数据库中尚未有任何当前项目的表,这种情况很好处理,主要讲一下非初次部署的情况 SQL 迁移步骤。

    1. 先 dump 一份所有环境中当前项目最新版本的表结构,在 resources/db目录中创建一个 base_init.sql 文件,将最新版本的 DDL 以及需要初始化的数据放到这个文件中,这个 sql 文件后期就不要做任何修改。

    2. resources/db 目录增加一个名为 V1__init.sql的文件,内容为空,用于占位

    3. 将所有环境的表结构都统一到 base_init.sql这个版本

    4. 如果有新增的 DDL,则创建一个高版本的 sql 文件,如V2__add_table.sql,项目启动的时候会自动执行 sql,但是不会执行 V1 版本的,所以添加了 V1 版本的用于占位。注意如果新增的 DDL 版本没有执行出错,切勿修改!!!

    5. sql 文件的命名具有一定规则,以V开头,接着两个下划线 __,接着可以写注释,然后以 .sql 结尾,如V3__alter_table.sql 版本号支持小版本x.y.z格式,但是为了简单起见,直接用一个数字递增更方便。

    6. 如果需要部署到新的环境,则只需要执行 base_init.sql中 DDL 即可,其他版本的 DDL 交给 flyway 就可以了

    7. Over~

    8. 有时候如果新版本的 DDL 写错了,可能会导致 flyway 执行失败,会在元数据表中增加一条执行 status 为 0 的记录,只要 status 有为 0 的记录,项目就无法启动,这样就很难受,网上解决方式多是手动去数据库删除这条记录,这未免太危险,可以利用 flyway 的 callback 来实现执行失败,自动删除失败记录。在 resources/db目录下添加名为 afterMigrateError.sq文件,文件内容为

      1
      2
      -- SQL 执行失败,清理 flyway 元数据表中失败的执行记录
      DELETE IGNORE FROM `${flyway-table}` WHERE success = 0;

      其中的变量就是当前项目元数据表的表名称。

    9. 如果当前项目在所有环境都是初次部署,那就不需要 base_init.sql,初始化直接放到 V1__init.sql 当中,上线时不再需要手动执行 SQL,全部交由 flyway 来执行即可。如果数据库比如测试环境存在经常手动修改表增加表的情况,需要关闭 flyway,存在 flyway 因为在手动执行 SQL 执行之后再执行导致执行失败的情况,所以某个环境使用了 flyway 控制版本之后,就不要再手动增删改表。

    10. Over~~~

常见问题

  1. 出现 java.sql.SQLException: sql injection violation, comment not allow : CREATE TABLE xxxxxx.flyway_schema_history_xxx
    检查是否使用的是 druid ,错误原因是建表语句中包含了 SQL 注释,druid 默认会拦截包含注释的 SQL 执行,需要修改 druid 配置,允许注释。(不知道 flyway 为什么要把注释写到建表语句中)

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    spring:
    datasource:
    druid:
    # ...... 省略其他
    filter:
    stat:
    enabled: true
    slf4j:
    enabled: true
    wall:
    enabled: true
    config:
    comment-allow: true
    # filters: stat,wall,slf4j 注释此行,filter改成上面的格式

总结

针对多环境迁移流程

  1. 所有环境数据库表版本统一到最新版本
  2. 将最新版本 DDL 放到 base_init.sql
  3. 后续迭代在 resource/db 目录下增加新版本的 DDL 文件
  4. 如果是新环境,先通过 base_init.sql 进行初始化,再启动项目即可,非新环境,直接启动项目即可

示例代码

参考