虚谷文档 v1.0.1

适用虚谷数据库版本

v12.9



适用虚谷数据库版本

v12.9


druid 使用手册 ​

📄字数 9.2K
👁️阅读量 加载中...

本文将介绍如何使用 druid v1.1.24 以及同时使用 dynamic-datasource-spring-boot-starter 多数据源连接 XuguDB，并开启 WallFilter 功能测试虚谷 SQL 方言拦截效果以及 StatFilter 仪表盘展示效果。

框架名称适配起始版本官网地址源框架下载地址XuguDB框架下载demo程序地址
druid1.1.9druid 官网druid 源码版本发布xugu-druid-demo

提示

其他支持版本可详见版本发布列表

一、使用说明 ​

1.1 下载源码 ​

  1. 访问虚谷数据库开放源代码仓库，选择所需版本分支。

    虚谷druid仓库分支选择图 1.1 虚谷druid仓库分支选择

  2. 直接下载当前分支源码（本地未安装 Git）。

    虚谷druid仓库分支代码下载图 1.2 虚谷druid仓库分支代码下载

1.2 安装 druid 到本地 Maven 仓库 ​

  1. 推荐使用 JDK-8 和 Maven-3.6.x 运行环境。没有使用过 GPG 密钥，需要在 pom.xml 代码中跳过 GPG 签名或者注释插件。

    跳过gpg签名图 1.3 跳过gpg签名
    maven-gpg-plugin插件注释图 1.4 maven-gpg-plugin插件注释

  2. 使用 Maven 命令 mvn clean install -Dmaven.test.skip=true 安装 druid 到本地 Maven 仓库，出现 BUILD SUCCESS 即安装成功。

    druid本地maven仓库部署图 1.5 druid本地maven仓库部署

二、连接示例 ​

2.1 前提条件 ​

  • 计算机已安装 JDK 1.8 和 Maven。
  • 计算机已安装 IntelliJ IDEA。
  • 计算机已安装 DBManager 或者 xgconsole。
  • 计算机已安装 Apifox 或者 postman
  • 计算机已部署 XuguDB 12.0.0 或有能连接访问的虚谷数据库实例。

提示

本文档示例程序运行使用的软件为 IntelliJ IDEA 2025.1.2 (Community Edition)，也可以按照自己的喜好选择其它开发工具运行此示例程序。

2.2 操作步骤 ​

  • 导入 xugu-druid-demo 项目到 IDEA 中。
  • 修改 xugu-druid-demo 项目中数据库连接信息。
  • 选择 xugu-druid-demo 运行环境。
  • 运行 xugu-druid-demo 项目。

提示

本文是在 Windows 环境中进行操作说明的，如果使用的是其它操作环境，那么与本文中的步骤可能存在不同。

2.2.1 导入 xugu-druid-demo 项目到 IDEA 中 ​

  1. 参考 IntelliJ IDEA 官方文档，导入项目。

    1. 启动 IntelliJ IDEA。 如果欢迎屏幕打开，请选择左侧栏目中项目（Projects）-> 右侧选项打开（Open）。 否则，请转到左上角主菜单的 文件（File）-> 打开（Open）。
    2. 在打开的对话框中，选择下载的源代码、库目录下的二级目录xugu-druid-1.1.24，然后点击 Select Folder 打开。

  2. 项目结构设置

    1. 更改项目 SDK 设置：参考 SDK | IntelliJ IDEA 文档，请点击右上角工具栏上的齿轮⚙设置按钮并选择项目结构按钮（Project Structure...）。 或者，前往 文件（File）-> 项目结构（Project Structure...） 或按 Ctrl+Alt+Shift+S。

      xugu-druid-demo项目JDK设置图 2.1 xugu-druid-demo项目JDK设置

    2. 项目 Maven 设置：参考 Maven | IntelliJ IDEA 文档，文件 -> 设置 -> 构建、执行、部署 -> 构建工具 -> Maven。

      xugu-druid-demo项目Maven设置图 2.2 xugu-druid-demo项目Maven设置

  3. pom.xml 依赖设置

    xugu-druid-demo项目依赖设置图 2.3 xugu-druid-demo项目依赖设置

  4. 仔细阅读xugu-druid-1.1.24/README.md中项目搭建步骤，在其项目根目录中执行以下脚本，将兼容虚谷版的 druid 安装到本地 Maven 仓库，并刷新/重新加载 Maven 项目。

    shell
    mvn install:install-file -Dfile=./lib/druid-1.1.24.jar -DgroupId=com.alibaba -DartifactId=druid -Dversion=1.1.24 -Dpackaging=jar -DgeneratePom=true

    提示

    已执行过步骤 1.2 本地 Maven 仓库部署 不再需要执行此步骤

2.2.2 修改 xugu-druid-demo 项目中数据库连接信息 ​

  1. 执行示例项目中 xugu-druid-1.1.24/sql/wall_test.sql，创建数据库和表结构。

    sql
    ---------------------------------------------- 默认用户 SYSDBA 执行 ----------------------------------------------
CREATE TABLE `usert` (
`id` BIGINT NOT NULL PRIMARY KEY,
`NAME` VARCHAR(255) NOT NULL,
`age` INT NOT NULL
);

-- 删除所有表结构的存储过程
CREATE OR REPLACE
PROCEDURE drop_all_tables() IS
	loop_num INT;
	drop_sql VARCHAR;
BEGIN
	loop_num := 0;
	FOR t IN (SELECT TABLE_NAME FROM  USER_tables) LOOP
		drop_sql := 'DROP TABLE "' || t.table_name || '"';
		loop_num := loop_num + 1;
		EXECUTE IMMEDIATE drop_sql;
	END LOOP;
	SEND_MSG('过程执行完成' || loop_num || '次');
END;


CREATE TABLE tb_top(id INT IDENTITY(1,1),name VARCHAR(20) DEFAULT 'default1',amount int,region VARCHAR(20),parent_id int, CONSTRAINT pk_id PRIMARY KEY(id));

INSERT INTO tb_top VALUES(1,'one',1,'a',0),(2,'two',1,'a',1),(3,'three',1,'b',1),(4,'%four',1,'b',1),(5,'four',1,'b',4),(6,NULL,1,'c',3),(7,NULL,1,'a',3),(8,'TWO',1,'c',2);

CREATE TABLE tb_top1(id INT IDENTITY(1,1),name VARCHAR(20) DEFAULT 'default',CONSTRAINT pk_id PRIMARY KEY(id));
CREATE TABLE tb_top2(id INT IDENTITY(1,1),name VARCHAR(20) DEFAULT 'default',CONSTRAINT pk_id PRIMARY KEY(id));
CREATE TABLE tb_top3(id INT IDENTITY(1,1),name VARCHAR(20) DEFAULT 'default',CONSTRAINT pk_id PRIMARY KEY(id));

CREATE TABLE tb_top_merge(
id INT IDENTITY(1,1),
tid NUMBER NOT NULL,
name VARCHAR(20) DEFAULT 'default',
year NUMBER,
CONSTRAINT pk_id PRIMARY KEY(id))
PARTITION BY RANGE (id) PARTITIONS (
part1 VALUES LESS THAN (1),
part2 VALUES LESS THAN (1000),
part3 VALUES LESS THAN (2000),
part4 VALUES LESS THAN (3000),
part5 VALUES LESS THAN (MAXVALUES))
SUBPARTITION BY HASH (name) SUBPARTITIONS 4;

INSERT INTO tb_top_merge VALUES(1,1,'one-1',10)(222,222,'two-2',20)(3,3,'three-3',30)(400,400,'four-4',40);
---------------------------------------------- 默认用户 SYSSSO 执行 ----------------------------------------------
CREATE ENCRYPTOR 'ENCRYPTOR1' BY '123';

  2. 修改配置文件 xugu-druid-1.1.24/src/main/resources/application-dev.yml
    或 xugu-druid-1.1.24/src/main/resources/application-dynamic.yml 中的数据库连接信息。

2.2.3 选择 xugu-druid-demo 运行环境。 ​

2.2.3.1 原生 druid 数据源 ​

  • application.yml

    yaml
    spring:
  profiles:
    # 选择激活的环境配置
    active:
      - dev # 使用此配置文件，请注释 dynamic-datasource 相关依赖
#      - dynamic
logging:
  config: classpath:log4j2.xml

  • application-dev.yml

    yaml
    server:
  # 程序的 HTTP 服务器监听的端口号
  port: 8080
spring:
  jackson:
    # JSON 中日期格式
    date-format: yyyy-MM-dd HH:mm:ss
    time-zone: Asia/Shanghai
  datasource:
    # 数据库url连接
    url: jdbc:xugu://127.0.0.1:5135/system?char_set=UTF8
    # 数据库用户名
    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: 6000
      # 间隔多久才进行一次检测，检测需要关闭的空闲连接
      time-between-eviction-runs-millis: 2000
      # 连接在被清理前的最小空闲时间
      # 如果此时minEvictableIdleTimeMillis还没有赋值，则使用默认值1800000
      min-evictable-idle-time-millis: 600000
      max-evictable-idle-time-millis: 1800000
      validationQuery: SELECT 1
      testWhileIdle: true
      # 申请连接时执行validationQuery检测连接是否有效，默认true，开启后会降低性能
      testOnBorrow: false
      # 归还连接时执行validationQuery检测连接是否有效，默认false，开启后会降低性能
      testOnReturn: false
      keep-alive: true
      # 注意预处理语句中事务提交与锁释放时机
      poolPreparedStatements: false
      maxPoolPreparedStatementPerConnectionSize: 0
      # 配置监控统计拦截的filters。stat：监控统计、wall：防御sql注入、log4j：日志记录
#      filters: wall,stat,log4j
      filter:
        slf4j:
          enabled: true
          statement-create-after-log-enabled: false
          statement-close-after-log-enabled: false
          result-set-open-after-log-enabled: false
          result-set-close-after-log-enabled: false
        stat:
          enabled: true
          merge-sql: true
#          slow-sql-millis: 10000
#          log-slow-sql: true
        wall:
          enabled: true
          config:
#            none-base-statement-allow: true
            # 是否进行严格的语法检测，不能覆盖全部sql语法规则时，临时打开
#            strictSyntaxCheck: false
            # xugu方言语法stmt
            backup-allow: true
            restore-allow: true
      useGlobalDataSourceStat: true
      # 执行时间超过3000毫秒的sql会被标记为慢sql
      connectionProperties: druid.stat.mergeSql=true;druid.stat.slowSqlMillis=3000
      # 配置过滤器，过滤掉静态文件
      web-stat-filter:
        enabled: true
        url-pattern: /*
        exclusions: /druid/*,*.js,*.css,*.gif,*.jpg,*.bmp,*.png,*.ico
      # 配置可视化控制台页面
      stat-view-servlet:
        enabled: true
        # 访问druid监控页面的地址
        url-pattern: /druid/*
        # IP白名单 没有配置或者为空 则允许所有访问
#        allow: ip地址
        # IP黑名单 若白名单也存在 则优先使用
#        deny: ip地址
        # 禁用重置按钮
        reset-enable: false
        # 登录所用的用户名与密码
#        login-username: admin
#        login-password: 123456

    提示

    官方文档链接：DruidDataSource配置属性列表

2.2.3.2 dynamic-datasource 动态数据源 ​

  • application.yml

    yaml
    spring:
  profiles:
    # 选择激活的环境配置
    active:
#      - dev # 使用此配置文件，请注释 dynamic-datasource 相关依赖
      - dynamic
logging:
  config: classpath:log4j2.xml

  • application-dynamic.yml

    yaml
    server:
  # 程序的 HTTP 服务器监听的端口号
  port: 8080
spring:
  autoconfigure:
    exclude: com.alibaba.druid.spring.boot.autoconfigure.DruidDataSourceAutoConfigure
  jackson:
    # JSON 中日期格式
    date-format: yyyy-MM-dd HH:mm:ss
    # 时区
    time-zone: Asia/Shanghai
  datasource:
    druid:
      # 监控页面
      # 配置过滤器，过滤掉静态文件
      web-stat-filter:
        enabled: true
        url-pattern: /*
        exclusions: /druid/*,*.js,*.css,*.gif,*.jpg,*.bmp,*.png,*.ico
      # 配置可视化控制台页面
      stat-view-servlet:
        enabled: true
        # 访问druid监控页面的地址
        url-pattern: /druid/*
        # IP白名单 没有配置或者为空 则允许所有访问
#        allow: ip地址
        # IP黑名单 若白名单也存在 则优先使用
#        deny: ip地址
        # 禁用重置按钮
        reset-enable: false
        # 登录所用的用户名与密码
#        login-username: admin
#        login-password: 123456
    dynamic:
      # 对每个数据源生效，优先级低
#      druid:
#        # 初始化连接池大小
#        initialSize: 5
#        # 最小连接数
#        minIdle: 10
#        # 最大连接数
#        maxActive: 20
#        # 获取连接时的最大等待时间,超过该时间则抛出异常
#        maxWait: 6000
#        # 间隔多久才进行一次检测，检测需要关闭的空闲连接
#        time-between-eviction-runs-millis: 2000
#        # 连接在被清理前的最小空闲时间
#        # 如果此时minEvictableIdleTimeMillis还没有赋值，则使用默认值1800000
#        min-evictable-idle-time-millis: 600000
#        max-evictable-idle-time-millis: 1800000
#        validationQuery: SELECT 1
#        testWhileIdle: true
#        # 申请连接时执行validationQuery检测连接是否有效，默认true，开启后会降低性能
#        testOnBorrow: false
#        # 归还连接时执行validationQuery检测连接是否有效，默认false，开启后会降低性能
#        testOnReturn: false
#        keep-alive: true
#        # 注意预处理语句中事务提交与锁释放时机
#        poolPreparedStatements: false
#        maxPoolPreparedStatementPerConnectionSize: 0
#        # 配置监控统计拦截的filters。stat：监控统计、wall：防御sql注入、log4j：日志记录
#        filters: wall,stat,log4j
#        useGlobalDataSourceStat: true
#        # 执行时间超过3000毫秒的sql会被标记为慢sql
#        connectionProperties: druid.stat.mergeSql=true;druid.stat.slowSqlMillis=3000
#        slf4j:
#          enabled: true
#          statement-create-after-log-enabled: false
#          statement-close-after-log-enabled: false
#          result-set-open-after-log-enabled: false
#          result-set-close-after-log-enabled: false
#        stat:
#          enabled: true
#          merge-sql: true
##          slow-sql-millis: 10000
##          log-slow-sql: true
#        wall:
##          none-base-statement-allow: true
#          # 是否进行严格的语法检测，不能覆盖全部sql语法规则时，临时打开
##          strictSyntaxCheck: false
#          # xugu方言语法stmt
#          backup-allow: true
#          restore-allow: true

      # 设置默认的数据源或者数据源组,默认值即为master
      primary: master
      # 严格匹配数据源,默认false.
      strict: false
      datasource:
        master:
          # 数据库url连接
          url: jdbc:xugu://127.0.0.1:5135/system?char_set=UTF8
          # 数据库用户名
          username: SYSDBA
          # 数据库密码
          password: SYSDBA
          # 数据库驱动类名
          driver-class-name: com.xugu.cloudjdbc.Driver
          # 当前数据源生效，优先级高
          druid:
            # 初始化连接池大小
            initialSize: 5
            # 最小连接数
            minIdle: 10
            # 最大连接数
            maxActive: 20
            # 获取连接时的最大等待时间,超过该时间则抛出异常
            maxWait: 6000
            # 间隔多久才进行一次检测，检测需要关闭的空闲连接
            time-between-eviction-runs-millis: 2000
            # 连接在被清理前的最小空闲时间
            # 如果此时minEvictableIdleTimeMillis还没有赋值，则使用默认值1800000
            min-evictable-idle-time-millis: 600000
            max-evictable-idle-time-millis: 1800000
            validationQuery: SELECT 1
            testWhileIdle: true
            # 申请连接时执行validationQuery检测连接是否有效，默认true，开启后会降低性能
            testOnBorrow: false
            # 归还连接时执行validationQuery检测连接是否有效，默认false，开启后会降低性能
            testOnReturn: false
            keep-alive: true
            # 注意预处理语句中事务提交与锁释放时机
            poolPreparedStatements: false
            maxPoolPreparedStatementPerConnectionSize: 0
            # 配置监控统计拦截的filters。stat：监控统计、wall：防御sql注入、log4j：日志记录
            filters: wall,stat,log4j2
            useGlobalDataSourceStat: true
            # 执行时间超过3000毫秒的sql会被标记为慢sql
            connectionProperties: druid.stat.mergeSql=true;druid.stat.slowSqlMillis=3000
            log4j2:
              statement-create-after-log-enabled: false
              statement-close-after-log-enabled: false
              result-set-open-after-log-enabled: false
              result-set-close-after-log-enabled: false
            stat:
              enabled: true
              merge-sql: true
            #          slow-sql-millis: 10000
            #          log-slow-sql: true
            wall:
              # none-base-statement-allow: true
              # 是否进行严格的语法检测，不能覆盖全部sql语法规则时，临时打开
              # strictSyntaxCheck: false
              # xugu方言语法stmt
              backup-allow: true
              restore-allow: true

    提示

    官方文档链接：dynamic-datasource

2.2.4 运行 xugu-druid-demo 项目 ​

  1. 在项目路径 xugu-druid-1.1.24/src/main/java/com/xugu/demo/XuguDruidDemoApplication.java 中运行主启动类。

    xugu-druid-demo项目启动入口图 2.4 xugu-druid-demo项目启动入口

  2. 待程序完全启动后访问本地 Druid Monitor。

    druid-monitor页面图 2.5 druid-monitor页面

  3. 测试方法入口存放于 xugu-druid-1.1.24/src/main/java/com/xugu/demo/controller 目录文件中，通过 HTTP 请求调用。

    xugu-druid-demo项目测试入口图 2.6 xugu-druid-demo项目测试入口
    使用Apifox测试xugu-druid-demo图 2.7 使用Apifox测试xugu-druid-demo

  4. 观察控制台日志与 Druid Monitor 内容。

    druid-monitor查看已执行的sql图 2.8 druid-monitor查看已执行的sql

三、常见问题&解决办法 ​

  1. 程序启动报错：Caused by: java.lang.IllegalStateException: dbType not support : xugu, url jdbc:xugu://127.0.0.1:5135/system?char_set=UTF8。

    1. 原因：使用了未兼容虚谷版的 Druid，并且开启了防御 sql 注入的 filter:wall 功能。
    2. 解决办法：未兼容虚谷版只能使用数据源连接池功能，配置文件需关闭 spring.datasource.druid.filter.wall 和 spring.datasource.druid.filters。

  2. 程序运行过程中报错：Caused by: com.alibaba.druid.sql.parser.ParserException: syntax error, error in :。

    1. 原因：报错信息提示当前 SQL 未被适配，无法解析成抽象语法树。
    2. 解决办法：确认当前 SQL 无语法注入风险，可在配置文件中 spring.datasource.druid.filter.wall.config.strictSyntaxCheck 关闭严格语法检测。

  3. 程序运行过程中报错：Cause: java.sql.SQLException: sql injection violation, class com.alibaba.druid.sql.... not allow :。

    1. 原因：报错信息提示当前 SQL 被正确解析，但是出现了 SQL 注入违规。
    2. 解决办法一：确认 SQL 编写合规，配置文件中 spring.datasource.druid.filter.wall.config 查看有无相关关键字用法配置，若有则设置为 true。
    3. 解决办法二：若无需防御 sql 注入的 filter:wall 功能，可关闭此功能。

  4. 使用 druid v1.2.12 以及之后的版本出现连接超时情况。

    1. 现象：使用 druid v1.2.12 以及之后的版本的连接池创建的连接访问数据库时，当一个操作与数据库的连接时间大于 10s 时，即使在 url 的连接信息中设置了 connect_timeout 参数的值大于10s，仍然报错：Caused by: java.sql.SQLException: [E50022]与服务器间的连接已经断开,可能原因:。
    2. 原因：Druid 1.2.12版本中，连接池默认配置了 connectTimeout 和 socketTimeout，默认值为10000，导致 url 设置的 connect_timeout 失效。
    3. 解决办法一: 自定义设置 spring.datasource.druid.connect-timeout 和 spring.datasource.druid.socket-timeout 的值。
    4. 解决办法二: 升级最新版本，最新版本已解决。