Liquibase Xugudb Adapter

Liquibase 虚谷数据库适配指南

概述

本技能提供 Liquibase 数据库迁移工具适配虚谷数据库(XuguDB)的完整流程。虚谷数据库通过提供专用的 JDBC 驱动和配置支持，可以无缝集成 Liquibase 框架的各种功能，包括数据库版本管理、增量迁移、多环境配置等。

适配流程

在开始适配前，按以下顺序检查和修改：

1. 依赖配置 → 2. 变更日志编写 → 3. Spring Boot 配置 → 4. 多环境配置 → 5. 测试验证 → 6. 生产部署

第一步：配置依赖

Maven 依赖配置

添加 Liquibase 和虚谷 JDBC 驱动依赖：

    org.liquibase
    liquibase-core

    com.xugudb
    xugu-jdbc
    12.3.4

    com.alibaba
    druid-spring-boot-starter
    1.2.6

第二步：编写变更日志

目录结构

src/main/resources/
└── db/
    └── changelog/
        ├── db.changelog-master.xml
        ├── V1__create_tables.xml
        ├── V2__create_indexes.xml
        └── V3__insert_initial_data.xml

主变更日志文件

变更集文件示例

第三步：修改配置文件

application.yml 配置

spring:
  datasource:
    url: jdbc:xugu://127.0.0.1:5138/SYSTEM?current_schema=RY&CHAR_SET=UTF8&COMPATIBLE_MODE=MYSQL
    username: SYSDBA
    password: SYSDBA
    driver-class-name: com.xugu.cloudjdbc.Driver
    type: com.alibaba.druid.pool.DruidDataSource
    druid:
      initialSize: 5
      minIdle: 10
      maxActive: 20
      maxWait: 60000
      validationQuery: SELECT 1
      testWhileIdle: true
      testOnBorrow: false
      testOnReturn: false

  liquibase:
    # 启用 Liquibase
    enabled: true
    # 主变更日志文件路径
    change-log: classpath:db/changelog/db.changelog-master.xml
    # 默认 Schema
    default-schema: RY
    # 上下文（用于环境区分）
    contexts: dev
    # 标签
    labels: ""
    # 迁移时是否清除数据库（慎用）
    drop-first: false
    # 是否测试模式
    test-rollback-on-update: false
    # 数据库变更日志表名
    database-change-log-table: DATABASECHANGELOG
    # 数据库变更日志锁表名
    database-change-log-lock-table: DATABASECHANGELOGLOCK
    # 参数
    parameters:
      schema: RY

关键配置项说明

| 配置项 | 说明 | 推荐值 | |--------|------|--------| | spring.liquibase.enabled | 是否启用 Liquibase | true | | spring.liquibase.change-log | 主变更日志文件路径 | classpath:db/changelog/db.changelog-master.xml | | spring.liquibase.default-schema | 默认 Schema | RY | | spring.liquibase.contexts | 上下文（环境区分） | dev | | spring.liquibase.drop-first | 是否先清除数据库 | false | | spring.liquibase.database-change-log-table | 变更日志表名 | DATABASECHANGELOG |

第四步：多环境配置

使用上下文区分环境

不同环境的配置文件

# application-dev.yml
spring:
  liquibase:
    contexts: dev
    drop-first: true  # 开发环境可以先清除
  datasource:
    url: jdbc:xugu://127.0.0.1:5138/SYSTEM?current_schema=RY_DEV&CHAR_SET=UTF8&COMPATIBLE_MODE=MYSQL
    username: SYSDBA
    password: SYSDBA

# application-prod.yml
spring:
  liquibase:
    contexts: prod
    drop-first: false  # 生产环境禁止清除
    test-rollback-on-update: false
  datasource:
    url: jdbc:xugu://prod-server:5138/SYSTEM?current_schema=RY&CHAR_SET=UTF8&COMPATIBLE_MODE=MYSQL
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}

第五步：测试验证

编译打包

# 设置JAVA_HOME（虚谷JDBC驱动需要Java 17+）
set JAVA_HOME=C:\Program Files\Eclipse Adoptium\jdk-21.0.11.10-hotspot
set PATH=%JAVA_HOME%\bin;%PATH%

# 编译打包
mvn clean package -DskipTests

启动应用

java -jar ruoyi-admin/target/ruoyi-admin.jar

验证迁移

# 执行迁移
mvn liquibase:update

# 查看迁移状态
mvn liquibase:status

# 验证变更日志
mvn liquibase:validate

第六步：生产部署

部署前检查

1. 备份数据库：生产环境迁移前必须备份
2. 测试环境验证：先在测试环境执行迁移
3. 低峰期执行：选择业务低峰期执行迁移
4. 监控准备：准备监控和告警机制

部署步骤

# 1. 备份数据库
# 2. 停止应用服务
# 3. 执行迁移
mvn liquibase:update
# 4. 启动应用服务
# 5. 验证应用功能

常见问题排查

1. 驱动类找不到

现象： 启动时报错 Driver class not found

原因： JDBC 驱动未正确引入

解决： 确保 xugu-jdbc 依赖已正确配置

2. 连接 URL 错误

现象： 连接时报错 Invalid connection URL

原因： URL 参数错误

解决： 确保使用正确的 URL 格式

url: jdbc:xugu://127.0.0.1:5138/SYSTEM?current_schema=RY&CHAR_SET=UTF8&COMPATIBLE_MODE=MYSQL

3. 变更日志文件找不到

现象： 启动时报错 FileNotFoundException

原因： 变更日志文件路径错误

解决：

• 检查 spring.liquibase.change-log 配置
• 确保文件存在于正确位置

4. 变更集执行失败

现象： 迁移失败，报 SQL 语法错误

原因： 虚谷数据库与标准 SQL 语法有差异

解决：

• 检查虚谷数据库 SQL 语法
• 使用虚谷数据库兼容的函数和语法
• 参考虚谷数据库 SQL 语法文档

5. 权限不足

现象： 迁移失败，报权限错误

原因： 数据库用户权限不足

解决：

• 确保用户有创建表、序列、触发器等权限
• 使用 DBA 权限用户执行迁移

6. 变更日志表不存在

现象： 启动时报错 DATABASECHANGELOG 表不存在

原因： 首次运行时需要创建变更日志表

解决：

• Liquibase 会自动创建变更日志表
• 如果失败，手动创建表结构

参考文档

详细的配置和使用说明请参考：

• [Liquibase 配置详解](references/liquibase-configuration.md)
• 虚谷数据库官方文档
• Liquibase 官方文档

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kourou25
• Source: kourou25/xugudb-dev-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.