SpringBoot项目使用Liquibase 数据库版本管理

原创已于 2025-09-11 16:16:57 修改 · 1.2k 阅读

11 ·

CC 4.0 BY-SA版权

文章标签：

#spring boot #数据库 #后端 #spring cloud #java #spring

于 2025-08-28 16:45:11 首次发布

数据库版本管理

一、概述

Liquibase 是一个用于数据库重构、变更管理和版本控制的开源工具。它通过对数据库变更进行版本化管理，支持多人协作开发、多分支合并，并提供多种数据库类型的支持。

二、特点

多数据库支持：MySQL、PostgreSQL、Oracle、SQL Server、DB2、H2等
多格式变更日志：XML、YAML、JSON、SQL
上下文执行逻辑：支持按需运行特定上下文变更
集群安全更新：确保分布式环境下的数据库更新安全
变更文档生成：自动生成数据库修改文档(HTML格式)
数据库对比：使用命令对比两个数据库结构差异
多平台集成：支持命令行、Ant、Maven及应用程序内嵌

三、集成步骤

1. 添加依赖

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

2. 创建目录结构

在项目 resources 目录下创建 liquibase 目录用于存放 liquibase 相关的配置文件，在 liquibase 目录下创建 changelog 目录存放所有 changelog 文件

src/main/resources/
    └── liquibase/
        ├── master.xml
        └── changelog/
            ├── common/
            │   ├── master.xml
            │   └── 20230110_common_init_table.sql
            └── other_module/

3.创建master.xml文件

在 liquibase 目录下的 master.xml 为 liquibase 的入口，通过 include 标签将其它的 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-3.4.xsd">

    <!--
    1：includeAll 标签可以把一个文件夹下的所有 changelog 都加载进来。如果单个加载可以用 include。
    2：includeAll 标签里有两个属性：path 和 relativeToChangelogFile。
        2.1：path （在 include 标签里是 file）：指定要加载的文件或文件夹位置
        2.2：relativeToChangelogFile ：文件位置的路径是否相对于 root changelog 是相对路径，默认 false，即相对于 classpath 是相对路径。
    -->

   <include file="liquibase/changelogs/common/master.xml"/>

</databaseChangeLog>

具体模块的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-3.4.xsd">

    <!--
    1：includeAll 标签可以把一个文件夹下的所有 changelog 都加载进来。如果单个加载可以用 include。
    2：includeAll 标签里有两个属性：path 和 relativeToChangelogFile。
        2.1：path （在 include 标签里是 file）：指定要加载的文件或文件夹位置
        2.2：relativeToChangelogFile ：文件位置的路径是否相对于 root changelog 是相对路径，默认 false，即相对于 classpath 是相对路径。
    -->

   <changeSet id="liquibase/20230110_common_init_table.sql" author="xxxx">
        <sqlFile path="liquibase/20230110_common_init_table.sql"/>
    </changeSet>

</databaseChangeLog>

id：执行id，执行文件名称

4. 应用配置

指定 liquibase 的 changelog文件

spring:
  liquibase:
    enabled: false # 是否启用
    change-log: classpath:/liquibase/master.xml

四、如何让Liquibase 知道这个变更集，跳过

核心原理是：Liquibase 通过在数据库中维护一个名为 DATABASECHANGELOG 的表来记录所有已经执行过的变更集。你需要手动在这个表中插入一条记录，让它认为这个脚本已经成功执行了。

INSERT INTO DATABASECHANGELOG (
    ID, AUTHOR, FILENAME, DATEEXECUTED, ORDEREXECUTED, 
    EXECTYPE, MD5SUM, DESCRIPTION, COMMENTS, LIQUIBASE
)
SELECT 
    'liquibase/data/changelog-test-0.0.3', -- 与 changelog 文件中的 id 属性对应
    'name', -- 与 changelog 文件中的 author 属性对应
    'liquibase/data/master.xml',  -- 注意：这个路径必须与之后Liquibase变更集中指定的路径完全一致
    NOW(), -- 变更集被执行的时间戳
    max_order + 1, -- 一个从 1 开始自增的数字，表示该变更集在本次执行中的顺序
    'EXECUTED', -- 执行类型
    NULL, -- 将MD5SUM设置为NULL，让Liquibase自己计算并更新
    'sqlFile path=liquibase/data/changelog-test-0.0.3.sql',
    '',
    '4.23.0'
FROM (SELECT COALESCE(MAX(ORDEREXECUTED), 0) as max_order FROM DATABASECHANGELOG) as tmp;