使用 Liquibase 管理数据库版本 - SpringBoot 2.7 .2 实战基础

优雅哥 SpringBoot 2.7 .2 实战基础 - 05 -使用 Liquibase 管理数据库版本

在企业开发中，数据库版本管理好像是一个伪命题，大多项目都是通过 Power Designer 之类的工具建模、生成 SQL 语句，然后去数据库中执行。在开发过程中如果遇到修改表结构，再补充修改表结构的语句，大家依次去执行，在本地及各个环境中同步表结构。但这种模式，在我参与过的项目中或多或少都出现过问题：忘记同步表结构，导致在服务启动或运行时出错。

1 Liquibase 介绍

SpringBoot 官方文档中推荐了两款工具来管理数据库版本：Flyway 和 Liquibase。前者我没有在项目中使用过，所以本文就只讨论 Liquibase。

使用 Liquibase 需要定义一堆 XML 文件，这些 XML 称为 changelog 文件。每个 changelog 文件中又包含多个变化集合 changeSet，每个 changeSet 记录了作者、改变的内容。changeSet 中要修改的内容，通过 createTable 、addColumn 等标签进行操作。通过这种 XML 文件的方式，就可以将代码版本与数据库版本关联在一起。项目启动，会自动执行 changelog XML 文件。Liquibase 具有执行锁，已经执行过的内容不会重复执行。在执行 changeSet 时，由于改动的内容可以通过 Liquibase 提供的标签编写，所以无关具体的数据库产品（MySQL、Oracle 等），Liquibase 底层会根据实际使用的数据库类型转化为对应的 SQL。

通过上面的描述，可以看出 Liquibase 带来的几个好处：

1. 支持多类型的数据库产品，无需维护 SQL 脚本；
2. 项目启动可以自动升级数据库；
3. 代码版本与数据库版本关联在一起。

2 在老项目中使用 Liquibase

在咱们的 demo hero-springboot-demo 中，之前已经手动通过 SQL 语句创建了数据库表 computer，现在想通过 Liquibase 来管理数据库版本和维护表结构，该怎么办呢？本节就通过这个案例来说明已存在的老项目中如何引用 Liquibase。

2.1 配置 Maven 插件

Liquibase 提供了 Maven 插件，使用该插件可以根据数据库逆向生成 changlog 文件。在 pom.xml 的 plugins 下添加 Liquibase 插件：

<plugin>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-maven-plugin</artifactId>
    <version>4.9.1</version>
    <configuration>
        <propertyFileWillOverride>true</propertyFileWillOverride>
        <outputChangeLogFile>temp/temp-changelog.xml</outputChangeLogFile>
        <driver>com.mysql.cj.jdbc.Driver</driver>
        <url>jdbc:mysql://127.0.0.1:3306/hero_springboot_demo?useUnicode=true&amp;characterEncoding=utf8&amp;useSSL=true</url>
        <username>root</username>
        <password>Mysql.123</password>
        <outputFileEncoding>UTF-8</outputFileEncoding>
        <verbose>true</verbose>
        <diffTypes>tables, views, columns, indexs,foreignkeys, primarykeys, uniqueconstraints, data</diffTypes>
    </configuration>
</plugin>

上面配置 Liquibase 的 Maven 插件：数据库连接信息和Liquibase生成规则配置。生成的文件路径为 temp 目录下的 temp-changelog.xml，Liquibase 不会自动生成文件夹，需要手动在项目根目录下创建 temp 目录。

2.2 逆向生成 changelog

在控制台执行 mvn liquibase:generateChangeLog 或者在界面上执行 generateChangeLog：

执行后查看 temp/temp-changelog.xml 文件：

生成的这个文件就是 changelog 文件，该文件中包括两个 changeSet：第一个是创建表结构；第二个初始化数据。

在第一个 changeSet 的 createTable 中，对 id 字段配置了自增属性 autoIncrement：

<column autoIncrement="true" name="id" type="BIGINT">
    <constraints nullable="false" primaryKey="true"/>
</column>

不知道为啥，我这不生效。要使该字段自增，要用 addAutoIncrement 标签。第一个 changeSet 需要添加上该标签，添加后如下：

<changeSet id="T100-20220801-yyg-001" author="yyg">
    <createTable remarks="电脑" tableName="computer">
        <column autoIncrement="true" name="id" type="BIGINT">
            <constraints nullable="false" primaryKey="true"/>
        </column>
        <column name="size" remarks="尺寸" type="DECIMAL(4, 1)"/>
        <column name="operation" remarks="操作系统" type="VARCHAR(32)"/>
        <column name="year" remarks="年份" type="VARCHAR(4)"/>
    </createTable>
    <addAutoIncrement tableName="computer" columnName="id" columnDataType="BIGINT"/>
</changeSet>

获取到历史表结构及数据的 changelog 文件后，接下来的步骤与 SpringBoot 整合 Liquibase 一致。

3 在 SpringBoot 中使用 Liquibase

3.1 添加依赖

在 pom.xml 文件中添加 liquibase 依赖 liquibase-core，该依赖版本号在 spring-boot-dependencies中已定义，直接添加依赖即可。

<dependency>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-core</artifactId>
</dependency>

3.2 添加 changelog

在 src/main/resources 创建目录 db， db 目录用来存放 Liquibase 相关的 changelog 文件。

db 目录下还可以按模块创建其他目录，由于我们这里只有一个 computer 类，属于 demo 演示，故就在 db 目录下创建子目录 demo， db/demo/ 目录就存放 demo 演示的所有 changelog 配置文件。将前面 Liquibase 逆向生成的 temp-changelog.xml 文件移动到 db/demo/ 目录下，并重命名为 demo-changelog-v1.xml。

在 db 目录下创建 changelog-master.xml 文件，该文件为主配置文件，作用就是引入所有模块的 changelog 文件：

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
                   xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
                        https://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.1.xsd">

    <includeAll path="demo" relativeToChangelogFile="true"/>
</databaseChangeLog>

除了根节点，里面就一句话，表示将当前路径下 demo 目录中的 changelog 文件都引入。假设 db 目录下还有其他模块（目录），继续通过 <includeAll> 元素引入即可。

src/main/resources 中文件目录结构如下：

src/main/resources/
|- db/
	|- demo/
		|- demo-changelog-v1.xml
	|- changelog-master.xml

3.3 changeSet

回过头来看 demo-changelog-v1.xml 文件，里面的内容是之前生成的，前面讲过包括两个 changeSet。changeSet 用来定义对数据库的表更操作，包括：

表结构的操作：创建表、删除表、修改表结构（添加列、删除列等）

表数据的操作：表中数据的增删改查

视图的操作、索引的操作等

几乎只要是对数据库的操作，都可以写在 changeSet 中。当服务启动的时候，会自动执行主配置文件中包含的所有 changeSet。需要特别注意：changeSet 一经执行，就不能修改！！ 虽然 changeSet 元素有一个属性 runOnChange ，非常不建议乱用。如果要修改 changeSet里面的内容怎么办呢？重新写一个 changeSet，在里面编写要修改的内容。例如在第一个 changeSet 中使用 <createTable> 创建表，表中有一个列名为 field，在该 changeSet 执行后（成功启动过服务），想将该列列名 field 修改为 f，这时候不能直接修改第一个 changeSet，而是要写第二个 changeSet，通过 <renameColumn> 来修改列名，然后重启服务。

changeSet元素有两个必填的属性 author 和 id。author 表示作者，当前的是谁定义的这个changeSet，就填谁的名字，这样便于追溯。 id 要求唯一，我在项目开发中，id一般按照这个规则：[任务ID]-[日期]-[作者]-[序号]，如 T100-20220801-yyg-001。

通常小版本更新（如字段级别的变更），就在同一个文件中追加新的 changeSet 即可。一个 changelog 文件可以包括多个 changeSet，每个 changeSet 中可以包括多个语句，如多个 createTable、insert 等。

大版本更新，就重新编写 changeLog 文件，如 demo-changelog-v2.xml。

按照上面所讲，我们修改一下 demo-changelog-v1.xml 中的两个 changeSet 的 id 和 author：

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
                   xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
                    https://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.1.xsd">
    <!--
    1. id使用[任务ID]-[日期]-[作者]-[序号]，如 T100-20220801-yyg-001
    2. 必须填写author
    3. 所有 表、列 必须加remarks进行注释
    4. 已经执行过的ChangeSet严禁修改
    -->
    <changeSet id="T100-20220801-yyg-001" author="yyg">
        <createTable remarks="电脑" tableName="computer">
				...
				</createTable>
    </changeSet>
    <changeSet id="T100-20220801-yyg-002" author="yyg">
        ...
    </changeSet>
</databaseChangeLog>

3.4 添加配置

在 application.yml 中添加 liquibase 的配置：

spring:
  liquibase:
    enabled: true
    drop-first: false
    change-log: classpath:/db/changelog-master.xml

上述配置开启 liquibase，并指定主文件的路径。

3.5 启动服务测试

现在启动服务，会发现服务启动失败，而且控制台会出现如下提示：

Reason: liquibase.exception.DatabaseException: Table 'computer' already exists

此时需要删除数据库中的表，然后重新启动服务。

服务启动成功后，会自动创建两张 liquibase 相关的表：DATABASECHANGELOG 和 DATABASECHANGELOGLOCK表。

现在尝试在 demo-changelog-v1.xml中编写第三个 changeSet：

<changeSet id="T100-20220801-yyg-003" author="yyg">
    <addColumn tableName="computer">
        <column name="color" type="VARCHAR(8)" defaultValue="red" remarks="颜色"/>
    </addColumn>
</changeSet>

这个 changeSet 为 computer 表新增列 color，默认值为 red。重启服务，服务启动后查看 computer 表：

1. 已新增列 color
2. color 默认值已设置为 red

这样便成功在 SpringBoot 中使用 liquibase。

4 常见问题

4.1 Waiting for changelog lock

如果启动服务时，控制台提示如下信息：

Liquibase - Waiting for changelog lock
Waiting for changelog lock....

通常是由于 Liquibase 在重构数据库时使数据库死锁。解决方法如下：

1 查看锁住数据库的id：

SELECT * FROM DATABASECHANGELOGLOCK where LOCKED = true;

2 解锁：

UPDATE DATABASECHANGELOGLOCK
SET locked=0, lockgranted=null, lockedby=null
WHERE id={id}

{id} 为第一步中查询出来对应记录的id。

4.2 主键自增无效

前面已经谈到，需要配置 addAutoIncrement 标签

<addAutoIncrement tableName="xxx" columnName="xx" columnDataType="BIGINT"/>

4.3 默认值无效

与主键自增无效类似，为 column 设置默认值 defaultValue、defaultValueNumeric也无效。

设置默认值需要使用标签 addDefaultValue：

<addDefaultValue tableName="xxx" columnName="xx" defaultValueNumeric="0"/>

Liquibase 还有很多强大的功能，就留给大家在使用过程中一步一步探索吧。

今日程序员优雅哥（/ youyacoder；heroyyg@126.com）学习到此结束~~~