为什么要使用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的插件：

<!-- 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>

             <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文件配置基本信息：

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文件上配置信息：

<databaseChangeLogxmlns="http://www.liquibase.org/xml/ns/dbchangelog"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangeloghttp://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>下面：

<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（按数量回滚）：

命令：

mvn liquibase:rollback -Dliquibase.rollbackCount=1

建议补充rollback块：

<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（按标签）：

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

建议添加 <rollback> 块

命令：

mvn liquibase:rollback -Dliquibase.rollbackTag=before_status_added

rollbackToDate（按时间）

命令：

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

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

建议添加 <rollback> 块

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

命令：

mvn liquibase:rollbackSQL -Dliquibase.rollbackCount=1

建议添加 <rollback> 块

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

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

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

eg:

<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）

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLogxmlns="http://www.liquibase.org/xml/ns/dbchangelog"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangeloghttp://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）

<?xml version="1.0" encoding="utf-8"?>
<databaseChangeLogxmlns="http://www.liquibase.org/xml/ns/dbchangelog"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangeloghttp://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>