3. Liquibase 安装与配置：Maven/Gradle 集成、Spring Boot 自动配置、命令行 CLI 安装

Liquibase 的安装与配置是数据库迁移工程化的第一步。根据团队技术栈和部署环境的不同，通常有三种主流集成方式：Maven 插件（Java 项目标准）、Gradle 插件（Android/现代 Java 项目）、Spring Boot 自动配置（微服务架构首选）以及命令行 CLI（CI/CD 与运维场景）。本章将逐一拆解每种方式的安装步骤、核心配置项及常见陷阱。

3.1 安装方式对比总览

3.2 Maven 集成：插件配置与生命周期绑定

在 pom.xml 中声明 liquibase-maven-plugin，并绑定到 Maven 生命周期阶段。以下是一个生产级配置示例，包含数据库连接、变更日志路径及回滚参数：

<build>
  <plugins>
    <plugin>
      <groupId>org.liquibase</groupId>
      <artifactId>liquibase-maven-plugin</artifactId>
      <version>4.27.0</version>
      <configuration>
        <propertyFile>src/main/resources/liquibase.properties</propertyFile>
        <propertyFileWillOverride>true</propertyFileWillOverride>
        <changeLogFile>db/changelog/db.changelog-master.xml</changeLogFile>
        <url>${liquibase.url}</url>
        <username>${liquibase.username}</username>
        <password>${liquibase.password}</password>
        <contexts>!test</contexts>
        <promptOnNonLocalDatabase>false</promptOnNonLocalDatabase>
      </configuration>
      <executions>
        <execution>
          <phase>process-resources</phase>
          <goals>
            <goal>update</goal>
          </goals>
        </execution>
        <execution>
          <id>rollback-count</id>
          <phase>none</phase>
          <goals>
            <goal>rollback</goal>
          </goals>
          <configuration>
            <rollbackCount>3</rollbackCount>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

3.3 Gradle 集成：插件声明与任务配置

Gradle 集成需要两步：在 build.gradle 中声明插件，并配置 Liquibase 活动（Activity）。支持多数据源场景：

plugins {
  id 'org.liquibase.gradle' version '2.2.1'
}

liquibase {
  activities {
    main {
      changeLogFile 'src/main/resources/db/changelog/db.changelog-master.xml'
      url 'jdbc:postgresql://localhost:5432/mydb'
      username 'app_user'
      password 'app_pass'
      contexts '!test'
    }
    rollbackActivity {
      changeLogFile 'src/main/resources/db/changelog/db.changelog-master.xml'
      url 'jdbc:postgresql://localhost:5432/mydb'
      username 'app_user'
      password 'app_pass'
      rollbackCount 5
    }
  }
}

// 注册自定义任务：回滚到指定标签
tasks.register('rollbackToTag', LiquibaseTask) {
  dependsOn 'classes'
  activities = ['rollbackActivity']
  command = 'rollback'
  args = ['--tag=release-1.2.0']
}

3.4 Spring Boot 自动配置：零配置启动

Spring Boot 通过 liquibase-core 和 spring-boot-starter-data-jpa 实现自动配置。只需添加依赖，Liquibase 会在应用启动时自动执行 db/changelog/db.changelog-master.xml（默认路径）。

Maven 依赖：

<dependency>
  <groupId>org.liquibase</groupId>
  <artifactId>liquibase-core</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

application.yml 配置（生产级）：

spring:
  liquibase:
    enabled: true
    change-log: classpath:db/changelog/db.changelog-master.xml
    contexts: prod
    default-schema: public
    liquibase-schema: liquibase_admin
    drop-first: false
    test-rollback-on-update: false
  datasource:
    url: jdbc:postgresql://${DB_HOST}:5432/${DB_NAME}
    username: ${DB_USER}
    password: ${DB_PASS}
    hikari:
      maximum-pool-size: 10
      minimum-idle: 2

3.5 命令行 CLI 安装：Docker 与原生包

CLI 方式适合脱离 IDE 和构建工具的场景。推荐两种安装途径：

Docker 执行示例（回滚到指定标签）：

docker run --rm \
  -v $(pwd)/changelog:/liquibase/changelog \
  -e LIQUIBASE_URL=jdbc:postgresql://host.docker.internal:5432/mydb \
  -e LIQUIBASE_USERNAME=admin \
  -e LIQUIBASE_PASSWORD=secret \
  liquibase/liquibase:4.27 \
  --changeLogFile=changelog/db.changelog-master.xml \
  rollback --tag=release-1.0.0

3.6 安装配置架构总览

下图展示了四种安装方式与 Liquibase 核心引擎、数据库以及 CI/CD 流水线之间的交互关系：

3.7 配置验证与常见问题

完成安装后，建议执行以下验证步骤：

1. 检查版本：运行 liquibase --version（CLI）或查看 Maven/Gradle 插件输出日志。
2. 验证数据库连接：执行 liquibase status 查看未应用的变更集数量。
3. 测试回滚：在开发环境执行 liquibase rollbackCount 1 确认回滚功能正常。
4. 检查锁表：查询 SELECT * FROM DATABASECHANGELOGLOCK 确认锁状态正常。