使用Liquibase和Spring Boot实现数据库版本控制

Git为代码版本控制提供了有效的解决方案，而Liquibase则有助于防止数据库成为开发过程中带来麻烦的“捣乱者”。

什么是Liquibase？

从本质上讲，Liquibase是一种用于跟踪并执行数据结构变更的工具，它能够确保这些变更以可预测且可重复的方式完成。

与其编写杂乱的SQL脚本，不如使用“迁移文件”（也称为changeSets）来管理数据库变更。Liquibase会读取这些文件，并将其与实际数据库中的跟踪表进行对比，从而确定需要执行哪些操作才能使数据库保持最新状态。

要有效使用Liquibase，只需要了解以下几个概念术语即可：

• changeLog： 主要配置文件。它实际上是一份列表，用于指示Liquibase应按照什么顺序执行哪些迁移文件。

• changeSet： 对数据库进行的单一、原子级的变更。创建一个表属于一种changeSet，添加一列则属于另一种changeSet。

• 迁移历史：Liquibase会在数据库中自动创建一个表格（名为DATABASECHANGELOG），用于记录哪些changeSets已经成功执行过。

• 校验和： 为每个changeSet生成唯一的哈希值。Liquibase利用这些哈希值来检测是否有人在某个文件被执行后偷偷对其进行了修改。

当将Liquibase与Spring Boot集成在一起时，在应用程序启动过程中，迁移操作会完全自动完成。

在启动过程中，Liquibase会先控制数据库系统，直到您的Web服务器被允许接收HTTP请求为止。它会检查数据库中的跟踪表，以确定哪些迁移操作已经完成。如果它在您的本地文件中发现新的迁移任务，就会锁定数据库，从而防止同时发生更新操作；执行这些新的迁移命令后，它会记录下相应的变更历史信息，最后才会解除对数据库的锁定。只有当这一整个过程完全结束后，Spring Boot才会完成启动流程。

由于Liquibase会在Spring Boot完全初始化Web服务器之前运行，因此你的应用程序永远不会使用过时的数据库模式来处理请求。如果迁移操作失败，应用程序将无法启动，从而避免系统进入异常状态。

项目设置

现在你已经了解了相关理论，让我们开始实际操作吧。我们将为员工管理API构建数据库层。

对于这个项目，我们将使用以下技术：

• Java 17+

• Spring Boot 3.x

• Maven

• Liquibase

• H2数据库

我们选择使用H2数据库，是因为它是一种内存数据库，完全不需要进行任何安装。你可以立即运行这个项目，而无需配置Docker容器或安装数据库服务器。不过，在这里学到的所有方法同样适用于PostgreSQL、MySQL、SQL Server或Oracle等数据库。

如果你是通过Spring Initializr生成这个项目的，请选择以下依赖项：Spring Web、Spring Data JPA、Liquibase Migration以及H2 Database。

在你的pom.xml文件中，你会看到那些使该项目能够正常运行的关键依赖项：

<dependencies>
    <dependency>
        org.springframework.boot
        spring-boot-starter-web
    
    org.springframework.boot
        spring-boot-starter-data-jpa
    

    com.h2database
        h2
        runtime
    

    org.liquibase
        liquibase-core
    
</dependencies>

接下来，需要配置Spring Boot以便它能够与H2数据库进行通信，并找到Liquibase相关的文件。打开src/main/resources/application.properties文件，添加以下内容：

# H2数据库配置
spring.datasource.url=jdbc:h2:file:./data/employeedb;DB_CLOSE_DELAY=-1
spring.datasource.driverClassName=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=

# 启用H2控制台，以便在浏览器中查看数据库信息
spring.h2.console.enabled=true
spring.h2.console.path=/h2-console

# Liquibase配置
spring.liquibase.change-log=classpath:db/changelog/db.changelog-master.xml

最后这一行内容最为重要。它告诉Spring Boot应该在哪里找到数据库变更的“主列表”文件。

注意：我们这里使用的是基于文件的H2数据库，而不是内存数据库。因为内存数据库每次重新启动Spring Boot时都会被完全清除掉数据，所以这种配置更为实用。

虽然Liquibase在每次启动时都会从头开始重新构建数据库架构，但对于本教程来说（以及在实际的本地开发环境中），使用基于文件的数据库方式会更为合适。通过这种机制，你的数据——尤其是Liquibase记录的历史变更信息——能够在应用程序重启后依然保持不变。

理解Liquibase的核心概念

在创建第一个表之前，我们首先需要了解Liquibase是如何组织文件的。Liquibase采用了一种层次结构来管理这些文件。

可以把这种结构想象成一本书：changeLog文件就相当于目录，而changeSets文件则代表具体的章节内容。

1. 主变更日志：这是整个系统的入口点。它本身通常不包含实际的数据库操作指令，而是负责按特定顺序列出其他相关文件。

2. 子变更日志：这些文件用于将相关的变更操作组合在一起。

3. 变更集：它们才是真正的、可执行的数据库命令（比如创建表或添加列）。

下面是一个具体的示意图，展示了这种层次结构在真实的Spring Boot项目中的运作方式：

Liquibase通过层次结构来管理所有的迁移操作。你需要维护一个主文件，这个文件就相当于目录；不过这个主文件本身很少包含实际的SQL命令，而是会明确列出所有子XML文件的执行顺序。每个子文件（比如01-create-employees.xml）都包含一条或多条数据库操作指令，而Liquibase将这些指令称为“变更集”。

一个变更集由以下三个要素唯一标识：

• id：一个唯一的字符串（通常是一个数字或Jira工单编号）。

• 作者：编写该迁移脚本的人。

• 文件路径：该文件所在的路径。

当Liquibase运行时，它会读取一个变更集文件，计算其内容的加密哈希值（即校验和），然后将id、作者和校验和这些信息存储到数据库中。如果在下一次启动时发现数据库中已经存在相同的id、作者和文件路径组合，Liquibase就会直接跳过这个变更集，不会执行其中的操作。

创建初始的员工表结构（版本1）

让我们开始编写第一个版本的数据库脚本吧。我们需要创建一个用于存储员工信息的表。

首先，在src/main/resources/db/changelog/db.changelog-master.xml路径下创建主文件：

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

    <include file="db/changelog/changes/01-create-employees.xml"/>>

</databaseChangeLog>

接下来，在src/main/resources/db/changelog/changes/01-create-employees.xml路径下创建实际的迁移文件：

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

    <changeSet id="1" author="ashutoshkrris">
        <createTable tableName="employees">
            
            
            
            

UPDATE DATABASECHANGELOGLOCK SET LOCKED = FALSE;

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

    <changeSet id="2" author="ashutoshkrris">
        <addColumn tableName="employees">
            
            
        
    

</databaseChangeLog>

<include file="db/changelog/changes/02-add-employee-email.xml"/>

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

    
            
            
            
        
    

    
        

</databaseChangeLog>

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

    <changeSet id="3" author="ashutoshkrris">
        <createTable tableName="departments">
            
    

    
        

</databaseChangeLog>

<column name="given_name" type="VARCHAR(50)"> </column>>

保存文件后，重新启动你的Spring Boot应用程序。

然而，应用程序并不会正常启动，而是会立即崩溃，终端也会显示大量的错误信息。请仔细查看错误日志的顶部，你应该会看到这样一条消息：

原因如下：liquibase.exception.ValidationFailedException：验证失败：
     1个变更集的校验和发生了变化：
          db/changelog/changes/01-create-employees.xml::1::ashutoshkrris 的原始校验和为 9:66e7dcffb2b1902a4e9f01670cb5f192，现在的校验和变为 9:2bd3ef21343d3b5c9448cc50bc35deef

出现这种情况的原因在于：一旦某个变更集在某个环境中被执行，那么这些更改就会成为不可修改的历史记录。你无法改变已经发生的事情。

当Liquibase启动时，它会计算本地XML文件的加密哈希值（即MD5校验和），然后查询DATABASECHANGELOG表，并将新计算出的哈希值与文件最初被执行时记录的哈希值进行比较。

如果你已经执行过某个变更集，而后来又修改了该文件中的任何一个字符，那么哈希值就会发生变化。Liquibase会检测到这种篡改行为，并拒绝继续启动。这样做是为了保护你的数据。例如，如果XML文件中指定列的名称为first_name，但数据库实际上是用fist_name这个名称创建的，那么你的Spring Data JPA应用程序肯定会出错。

正确的解决方法

如果你是在本地犯了这种错误，你可能会想要直接进入数据库，删除DATABASECHANGELOG表中的相关记录，然后再尝试运行应用程序。但千万不要这样做！如果这个修改被应用到了测试环境或生产环境中，你在生产服务器上是不允许手动删除数据记录的。

纠正架构错误的正确方法是回滚之前的更改。

首先，取消01-create-employees.xml文件中所做的修改，使哈希值再次与数据库中的数据匹配。然后，编写一个新的变更集来应用正确的配置：

<changeSet id="7" author="ashutosh">
    <renameColumn tableName="employees" 
                  oldColumnName="first_name" 
                  newColumnName="given_name" 
                  columnDataType="VARCHAR(50)"/>
</changeSet>>

将这个新的变更集添加到主变更日志中，然后重新启动应用程序，数据库就会自动恢复到正确的状态。

使用初始数据

有时候，进行架构修改后，需要一些初始数据才能使系统正常运行。

例如，在第3个版本中，我们创建了一个departments表。但目前这个表是空的，因此新的开发人员在本地克隆代码库并启动项目时，必须手动编写SQL插入语句来测试API功能。

我们可以通过将初始数据的插入操作纳入迁移策略中来自动化这一过程。

在src/main/resources/db/changelog/changes/05-seed-departments.xml文件中创建一个新的变更集：

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

    <changeSet id="8" author="ashutoshkrris">
        <insert tableName="departments">
            /insert>
    </changeSet>

</databaseChangeLog>

请在您的db.changelog-master.xml文件中添加相应的包含语句。当您重新启动应用程序时，Liquibase会自动插入这些数据，此时您的API就可以立即使用了。

数据迁移带来的风险

虽然导入数据是一项非常强大的功能，但使用它也需要遵循一定的规范。以下是一条实用的工程原则：

适合使用Liquibase的情况包括：

• 用于创建静态查找表（如状态代码表、国家列表、默认部门信息等）。

• 用于存储应用程序启动所需的系统配置信息。

不适合使用Liquibase的情况包括：

• 不要用它来生成大量虚假用户数据进行测试。

• 不要用它来迁移海量事务数据（例如，将500万条记录从一张表转移到另一张表）。

大规模的数据迁移可能会导致数据库表被锁定数小时。如果在部署过程中锁定了核心表，应用程序将会出现严重的运行故障。因此，请确保您的变更操作仅针对数据库的结构和必要的基础数据进行。对于复杂的数据处理任务，应该使用专门的脚本或后台作业来完成。

回滚操作

在理想情况下，代码总是能够正常运行。但在现实中，您有时会部署某些会导致生产环境中的查询语句出错或数据被破坏的数据库变更。在这种情况下，就需要有一种方法来撤销这些变更。

Liquibase支持回滚功能，但您需要了解它是如何执行这些回滚操作的。

自动回滚与手动回滚

许多Liquibase命令都是可以自动恢复到初始状态的。例如，如果您编写了一个或指令，Liquibase会自动理解“删除列”就是这些操作的相反操作，因此您不需要特别指示它如何撤销这些操作。

然而，有些操作本质上具有破坏性，或者其结果存在不确定性。如果您使用了自定义的标签，或者使用了指令，Liquibase就无法知道该如何恢复数据。在这种情况下，您就必须提供明确的回滚指令。

让我们模拟这样一个场景：我们添加了一列临时访问代码，但我们需要确保自己清楚如何安全地移除这一列。

创建文件《06-temporary-access.xml》：

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

    <changeSet id="9" author="ashutosh">
        <addColumn tableName="employees">
            /rollback>
    </changeSet>

</databaseChangeLog>

将这段代码添加到你的主配置文件中，然后运行应用程序。这样就会新增那一列。

如果你是通过CI/CD管道来部署这个应用的，而部署过程中出现了问题，你可以执行Liquibase的Maven命令，来回滚到之前的某个状态（例如：`mvn liquibase:rollback -Dliquibase.rollbackCount=1`），或者回滚到我们之前讨论过的某个特定版本标签。

回滚操作的实际效果

虽然了解回滚机制非常重要，但从后端开发的实际经验来看：在生产环境中，人们经常讨论回滚操作，但实际上很少能够顺利地完成回滚过程。

删除某一列在技术上来说非常简单，但如果你在15分钟的时间内让错误的代码影响了数据库中存储的客户数据，那么恢复这些数据就会变得极其困难。