Liquibase：与数据库无关的变更管理

Liquibase 版本管理入门指南

Liquibase 是一款开源的、与数据库无关的变更管理工具。它让你能够用代码描述数据库的结构变更，并把变更像应用的源代码一样进行版本控制、审查和部署。无论你使用 MySQL、PostgreSQL、Oracle 还是 SQL Server，Liquibase 都能以统一的方式管理数据库 Schema 的演进，彻底告别“忘记在生产环境执行那个 ALTER 语句”的噩梦。本教程将从零开始，带你掌握 Liquibase 的核心用法。

为什么需要数据库版本管理？

在传统的开发流程中，数据库修改常常通过临时编写的 SQL 脚本或手动操作完成。这会导致几个严重问题：

1. 环境不同步：开发、测试、生产环境的数据库结构很容易出现差异。
2. 变更不可追溯：无法轻易回答“是谁在什么时候加了这个字段？”
3. 回滚困难：出问题时很难快速、安全地恢复到上一个状态。
4. 自动化受阻：手动变更让持续集成与持续部署 (CI/CD) 难以覆盖数据库部分。

Liquibase 通过将数据库变更定义为代码（ChangeLog），完美解决了上述问题，让数据库版本管理成为自动化流水线中可靠的一环。

核心概念：ChangeLog 与 Changeset

Liquibase 的核心是 ChangeLog 文件。这是一个描述数据库所有变更顺序的主清单。它可以用 XML、YAML、JSON 或纯 SQL 格式编写。一个 ChangeLog 可以包含多个 Changeset，每个 Changeset 代表一次原子性的数据库修改，比如创建表、添加列、插入数据等。

Changeset 的唯一标识

每个 Changeset 都有一个由 id 和 author 组合而成的唯一标识。只要这个组合不变，Liquibase 就能识别哪些变更已经执行过，从而避免重复运行。

ChangeLog 的格式选择

对于初学者，推荐使用 XML 格式，因为它结构清晰且 Liquibase 的内置文档最丰富。若团队偏好 SQL，也可以直接写内嵌注释的 SQL 变更。

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="alice">
        <createTable tableName="department">
            <column name="id" type="int" autoIncrement="true">
                <constraints primaryKey="true" nullable="false"/>
            </column>
            <column name="name" type="varchar(50)">
                <constraints nullable="false" unique="true"/>
            </column>
        </createTable>
    </changeSet>

    <changeSet id="2" author="bob">
        <addColumn tableName="employee">
            <column name="dept_id" type="int"/>
        </addColumn>
    </changeSet>

</databaseChangeLog>

跟踪机制：DATABASECHANGELOG 表

当你第一次运行 Liquibase 更新命令时，它会自动在目标数据库中创建一张名为 DATABASECHANGELOG 的表。这张表是 Liquibase 的“大脑”，记录着每一个已应用的 Changeset 的 id、author、文件名、应用日期和校验和 (MD5)。下次运行时，Liquibase 会：

1. 扫描 ChangeLog 文件中所有未被记录到 DATABASECHANGELOG 表的 Changeset。
2. 按顺序依次执行这些新 Changeset。
3. 每成功执行一个，就在 DATABASECHANGELOG 表中添加一行记录。

这种机制保证了：已运行过的 Changeset 绝不会被重复执行，新添加的 Changeset 则会被精确识别并应用。

快速上手：安装与第一个更新

1. 安装 Liquibase

Liquibase 是一个 Java 工具，可作为命令行客户端使用。确保系统已安装 Java 11 或更高版本。

使用包管理器安装 (推荐)：

• macOS / Linux (SDKMAN!)： sdk install liquibase
• Windows (Chocolatey)： choco install liquibase

也可以直接从 Liquibase 官方下载页 获取压缩包并解压。

验证安装：在终端输入 liquibase --version，应显示版本信息。

2. 准备项目与配置文件

创建一个项目目录 my-liquibase-project，并在其中新建两个文件：

• changelog.xml：存放数据库变更定义。
• liquibase.properties：存放数据源连接配置。

liquibase.properties 示例 (H2 内存数据库快速体验)：

changeLogFile=changelog.xml
driver=org.h2.Driver
url=jdbc:h2:mem:testdb
username=sa
password=

3. 编写第一个 ChangeLog

将前面 XML 格式的示例内容复制到 changelog.xml 中。

4. 执行更新

在项目目录下打开终端，运行以下命令：

liquibase update

Liquibase 会连接数据库，发现 changelog.xml 中的两个 Changeset 尚未执行，于是创建 DATABASECHANGELOG 表，然后依次创建 department 表和添加 employee 表的列。运行完成后，数据库中就会包含你定义的结构。

管理回滚的策略

数据库变更不能只前进不回退。Liquibase 支持多种回滚方式，但需要你在定义 Changeset 时提前规划。

1. 显式编写回滚语句

在 XML 的 <changeSet> 内部添加 <rollback> 标签，描述如何撤销该变更。这是最可控的方式。

<changeSet id="3" author="alice">
    <createTable tableName="project">
        <column name="id" type="int" autoIncrement="true"/>
        <column name="title" type="varchar(100)"/>
    </createTable>
    <rollback>
        <dropTable tableName="project"/>
    </rollback>
</changeSet>

2. 利用自动回滚

对于许多简单的 DDL 操作（如 createTable、addColumn、addPrimaryKey），Liquibase 可以自动生成回滚语句。你可以依赖它，但显式自定义回滚总是更安全，因为自动回滚无法处理数据迁移或复杂业务逻辑。

3. 使用回滚命令

• 回滚到指定标签： liquibase rollback example_tag
  你可以在 ChangeLog 中通过 <tagDatabase tag="v1.2"/> 添加标记，用于回滚到该状态。
• 按数量回滚： liquibase rollbackCount 3
  回滚最近应用的 3 个 Changeset。
• 按日期回滚： liquibase rollbackToDate 2025-03-20
  回滚到指定日期时间之前的状态。

在生产环境回滚前，一定先在测试环境验证回滚脚本的正确性。

进阶模式：SQL 格式的 ChangeLog

如果你的团队已经有大量 SQL 脚本，或 SQL 是通用语言，Liquibase 允许你用纯 SQL 写变更，通过在注释中提供元数据来管理版本。

创建一个 db.changelog.sql 文件，并修改 liquidbase.properties 中的 changeLogFile=db.changelog.sql，或通过主 XML ChangeLog 的 <include> 引入 SQL 文件。

--liquibase formatted sql

--changeset alice:4
CREATE TABLE task (
    id INT PRIMARY KEY,
    description VARCHAR(255)
);
--rollback DROP TABLE task;

--changeset bob:5
ALTER TABLE task ADD COLUMN priority INT;
--rollback ALTER TABLE task DROP COLUMN priority;

要点：

• 第一行注释必须为 --liquibase formatted sql。
• 每个 Changeset 以 --changeset author:id 开头。
• 回滚语句放在 --rollback 后面，它们之间不应出现其他 Changeset 声明。

组织大型项目的 ChangeLog

随着项目增长，单个 ChangeLog 文件会变得难以维护。最佳实践是使用主 ChangeLog 按逻辑拆分。

1. 创建一个 master.changelog.xml 作为入口。
2. 利用 <include> 标签引入不同的功能模块或版本文件。

<databaseChangeLog ...>
    <include file="changelogs/001-create-tables.xml"/>
    <include file="changelogs/002-add-indexes.xml"/>
    <include file="changelogs/003-seed-data.xml"/>
    <include file="changelogs/release-1.1/department.xml"/>
</databaseChangeLog>

这样每个文件只包含负责一个小范围的 Changeset，团队协作时冲突更少，也更易理解。

参数化与条件逻辑

Liquibase 支持使用属性 (Property) 和前置条件 (Precondition)，让变更更灵活。

定义属性： 在 liquibase.properties 中定义 schema.name=public，然后在 ChangeLog 中用 ${schema.name} 引用。

前置条件： 在 Changeset 执行前检查条件，如果不满足则跳过或失败。

<changeSet id="6" author="alice">
    <preConditions onFail="MARK_RAN">
        <tableExists tableName="employee"/>
    </preConditions>
    <comment>Only run if employee table exists</comment>
    <addColumn tableName="employee">
        <column name="note" type="text"/>
    </addColumn>
</changeSet>

集成到 CI/CD 流水线

将 Liquibase 集成到构建、部署流水线是现代化的标志。通常的实践是：

• 在应用启动前或测试环境搭建阶段，运行 liquibase update。
• 使用 Maven 或 Gradle 插件（如 liquibase-maven-plugin）在构建过程中触发更新。
• 对于容器化环境，可以制作一个专用的 Init Container 来执行数据库迁移，确保应用启动时数据库已是最新结构。

常见命令速查

最佳实践总结

• 永远不要手动修改 DATABASECHANGELOG 表，否则会导致状态混乱。
• Changeset 是原子性的，一个 Changeset 只做一件事（创建一个表、添加一个列），便于回滚和审查。
• 为每个 Changeset 编写回滚逻辑，即使依赖自动回滚，也至少在文档中说明如何手动回滚。
• 使用版本化主 ChangeLog 和目录拆分，保持变更历史清晰。
• 将 Liquibase 执行作为应用部署流程的强制步骤，杜绝任何人绕过它直接修改数据库。
• 定期测试回滚流程，在非生产环境验证回滚行为的正确性。

通过掌握 Liquibase 的版本管理原则，你的数据库变更将变得可重复、可预测且可信任，真正与应用的代码演进保持同步。