SpringBoot整合Liquibase提升数据库变更的可控性、安全性、自动化程度（最详细）

为什么要使用liquibase?

- 团队协作与版本管理

当多人（或多个小组）并行开发、对同一数据库结构进行变更时，如果仅靠手写 SQL 脚本，很容易产生冲突或漏掉某些变更。
Liquibase 将所有 DDL/DML 操作以"changeset"形式纳入源码管理（Git、SVN），保证每条变更都有明确记录、能回溯，比单纯的 SQL 文件更具可控性。

- 环境一致性与自动化部署

在开发、测试、预生产、生产等多套环境中，手动执行脚本不仅繁琐，还容易漏执行或顺序错乱。
Liquibase 可在应用启动或 CI/CD 流水线中自动检测并执行"待跑"变更集，确保各环境数据库始终与代码版本保持一致。

- 回滚与容灾能力

手动脚本一旦执行错误，回滚往往要手写"撤销脚本"，既费时又容易出错。
在 Liquibase 中，每个 changeset 都可以定义 rollback 逻辑，部署失败时能够精准回退到前一个健康状态。

- 防止数据库"漂移"

长期演进过程中，数据库实际结构可能与预期文档或代码不同步，导致线上问题排查困难。
Liquibase 通过维护 DATABASECHANGELOG 表，自动对比历史记录与变更脚本，及时发现并修复结构漂移。

- 合规审计需求

某些行业（金融、医疗、政府）对数据库变更有严格审计和备案要求，需要完整的操作记录和执行人信息。
Liquibase 的 DATABASECHANGELOG 表会记录每条变更的执行时间、执行人和执行状态，天然满足审计需求。

等等....这里我们先介绍springboot整合liquibase的配置，数据库版本控制和自动执行和回滚

springboot整合liquibase

将所有建表、修改表结构、插入初始数据等操作都以"changeset"（变更集）的形式记录在 XML、YAML、JSON 或 SQL 文件中，存储在项目源码里，类似于 Git 管理代码的方式。
每次启动应用时，Liquibase 会自动对比当前数据库已执行的变更集与源码中的变更集，确保数据库结构与代码版本一致。
在 Spring Boot 启动阶段，Liquibase 自动扫描并执行未应用的变更集，无需手动在数据库端运行脚本。支持为每条变更集定义回滚（rollback）逻辑，遇到部署错误或回滚需求时，可以精准撤销指定版本的数据库变更。
Liquibase 提供 diff、diffChangeLog 命令，可比对两个数据库之间的结构差异，自动生成变更集脚本，便于团队协作和历史回顾。还能导出数据库的当前快照或变更历史，生成 HTML、JSON 等格式的数据库文档
Liquibase 在数据库中维护一个 DATABASECHANGELOG 表，记录每个变更集的执行时间、执行人等信息，方便事后审计和问题定位。
支持 Oracle、MySQL、PostgreSQL、SQL Server、DB2、H2、SQLite 等主流关系型数据库，跨数据库平台保持统一的变更管理方式。

1、导入liquibase所需的依赖并引入Liquibase的插件：

java 复制代码

<!-- Liquibase 核心引擎 -->
        <dependency>
            <groupId>org.liquibase</groupId>
            <artifactId>liquibase-core</artifactId>
            <version>4.33.0</version>
        </dependency>
        
        <!--Liquibase所需的依赖-->
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
            <version>3.13.0</version>
        </dependency>

java 复制代码

             <plugin>
                <groupId>org.liquibase</groupId>
                <artifactId>liquibase-maven-plugin</artifactId>
                <version>4.33.0</version>
                <configuration>
                    <!-- 指定 changelog 主入口文件，用于 update 等命令 -->
<changeLogFile>src/main/resources/liquibase/changelog/master.xml</changeLogFile>
                    <!-- 指定 generateChangeLog 的输出文件 -->
<outputChangeLogFile>src/main/resources/liquibase/changelog/generated/init-schema.xml</outputChangeLogFile>
                    <!-- 添加数据库连接信息 -->
                    <url>jdbc:mysql://yourhost:3306/yourDbSchema?useUnicode=true&amp;characterEncoding=utf-8&amp;autoReconnect=true&amp;useSSL=false&amp;serverTimezone=Asia/Shanghai</url>
                    <username>yoursqlname</username>
                    <password>yoursqlpassword</password>
                    <driver>com.mysql.cj.jdbc.Driver</driver>
                </configuration>
                <executions>
                    <execution>
                        <phase>process-resources</phase>
                        <goals>
                            <goal>generateChangeLog</goal>
                        </goals>
                    </execution>
                </executions>
                <!-- 添加依赖 -->
                <dependencies>
                    <dependency>
                        <groupId>mysql</groupId>
                        <artifactId>mysql-connector-java</artifactId>
                        <version>8.0.33</version>
                    </dependency>
                </dependencies>
            </plugin>

注意插件的版本要和依赖的一致

2、yml文件配置基本信息：

java 复制代码

spring:
  liquibase:
    change-log: classpath:liquibase/changelog/master.xml  # 指定XML路径
    enabled: true # true-当 Spring Boot 启动时，自动启用 Liquibase，并执行你在 changelog.xml 中定义的数据库变更  false-禁用 Liquibase，不会自动执行任何 changelog 逻辑

3、按照插件的<changeLogFile>标签和<outputChanegLogFile>标签构建文件架构：

4、在master.xml文件上配置信息：

java 复制代码

<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-3.1.xsd">

    <include file="generated/init-schema.xml" relativeToChangelogFile="true"/>
</databaseChangeLog>

5、调用liquibase插件执行 liquibase:generateChangeLog根据数据库生成init-schema.xml：

执行成功后就会生成该文件并生成sql对应的xml代码：

我们可以将它交给git管理，团队成员在拉取我们git分支时就可以通过运行项目自动读取xml文件同步我们的数据库

6、日常应用：

假设开发人员需要在数据库表contracts上新增一个字段status，直接在init-schema.xml上进行维护。

使用<changeSet>标签添加在表的<changeSet>下面：

java 复制代码

<changeSet author="Layux" id="202507251618">
        <addColumn tableName="contracts">
            <column name="status" remarks="状态" type="TINYINT">
                <constraints nullable="false"/>
            </column>
        </addColumn>
    </changeSet>

id可以使用时间的形式，方便后期维护

然后执行mvn liquibase:update，这样在datebasechangelog表上就会记录这次的操作

同时数据库表contracts上也会新增这个status字段

7、回滚（回滚后datebasechangelog表的记录数据会消失，操作表中的变更会退回）

rollbackCount（按数量回滚）：

命令：

java 复制代码

mvn liquibase:rollback -Dliquibase.rollbackCount=1

建议补充rollback块：

java 复制代码

<changeSet author="Layux" id="202507251618">
    <addColumn tableName="contracts">
        <column name="status" remarks="状态" type="TINYINT">
            <constraints nullable="false"/>
        </column>
    </addColumn>
    <rollback>
        <dropColumn tableName="contracts" columnName="status"/>
    </rollback>
</changeSet>

rollbackTag（按标签）：

java 复制代码

<changeSet id="1753429943969-1" author="32452">
    ...
    <tagDatabase tag="before_status_added"/>
</changeSet>

建议添加 <rollback> 块

命令：

java 复制代码

mvn liquibase:rollback -Dliquibase.rollbackTag=before_status_added

rollbackToDate（按时间）

命令：

java 复制代码

mvn liquibase:rollback -Dliquibase.rollbackDate=2025-07-25T16:20:00

该时间点应早于 status 字段添加时间

建议添加 <rollback> 块

生成 SQL 回滚语句（手动执行）

命令：

java 复制代码

mvn liquibase:rollbackSQL -Dliquibase.rollbackCount=1

建议添加 <rollback> 块

8、变更，sql表分文件（可选）

在大型项目中，为例方便维护，常常一表一文件

1、我们可以使用在入口的master.xml文件统一引入：

eg:

java 复制代码

<databaseChangeLog ...>
    <include file="tables/user.xml" relativeToChangelogFile="true"/>
    <include file="tables/dept.xml" relativeToChangelogFile="true"/>
    <include file="tables/contract.xml" relativeToChangelogFile="true"/>
</databaseChangeLog>

2、使用Python脚本自动拆分：

读取 init-schema.xml
每当遇到一个 <changeSet>，分析其中的表名（如 <createTable tableName="users">）
将每个 <changeSet> 写入独立的 users.xml、contracts.xml 等文件
自动生成 changelog-master.xml 并用 <include> 引入

分文件维护：在变更表的过程中，我们常常将每个变更都分xml文件存储，表名可以用日期或者变更备注

eg:

src/main/resources/liquibase/

├── changelog/

│ ├── master.xml # 主 changelog 文件

│ ├── 2024/

│ │ ├── 20240701-add-user-table.xml

│ │ ├── 20240710-add-status-column.xml

│ │ └── ...

│ └── 2025/

│ ├── 20250725-update-contracts-status.xml

│ └── ...

1、配置主changelog文件（master.xml）

java 复制代码

<?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-3.8.xsd">

    <!-- 引用子文件 -->
    <include file="liquibase/changelog/2024/20240701-add-user-table.xml"/>
    <include file="liquibase/changelog/2024/20240710-add-status-column.xml"/>
    <include file="liquibase/changelog/2025/20250725-update-contracts-status.xml"/>

</databaseChangeLog>

2、新建子 changelog 文件（每个文件一个 changeSet）

java 复制代码

<?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-3.8.xsd">

    <changeSet id="20250725-1" author="layux">
        <preConditions onFail="MARK_RAN">
            <not>
                <columnExists tableName="contracts" columnName="status"/>
            </not>
        </preConditions>

        <addColumn tableName="contracts">
            <column name="status" type="TINYINT" defaultValueNumeric="0" remarks="状态"/>
        </addColumn>
    </changeSet>

</databaseChangeLog>