README.zh-CN

DBX Agents

[English](README.md) | 简体中文

DBX 的 Agent 驱动 —— 通过 JDBC 和原生数据库驱动支持各种数据库。

每个 agent 作为独立进程运行，通过 stdin/stdout 与 DBX 进行 JSON-RPC 2.0 通信。

支持的数据库

| Agent | 数据库 | 驱动 | |-------|----------|-------------| | access | Microsoft Access | UCanAccess | | dameng | 达梦 DM8 | DM JDBC | | kingbase | 金仓KingbaseES | gokb Go 原生 agent | | vastbase | Vastbase | openGauss Go 原生 agent | | uxdb | 优炫 UXDB | UXDB JDBC | | goldendb | GoldenDB | MySQL Connector/J | | databend | Databend | Databend JDBC | | databricks | Databricks SQL | Databricks JDBC | | saphana | SAP HANA | SAP HANA JDBC | | teradata | Teradata | Teradata JDBC | | vertica | Vertica | Vertica JDBC | | firebird | Firebird | Jaybird JDBC | | exasol | Exasol | Exasol JDBC | | oceanbase-oracle | OceanBase Oracle 模式 | OceanBase JDBC | | gbase8a | GBase 8a | 外部 GBase 8a JDBC | | gbase8s | GBase 8s | 外部 GBase 8s JDBC | | oracle | Oracle 10g+ | go-ora 原生 agent | | h2 | H2 | H2 JDBC | | snowflake | Snowflake | Snowflake JDBC | | trino | Trino (Presto) | Trino JDBC | | hive | Apache Hive | 原生 Go HS2 agent | | transwarp | 星环 Inceptor | 内置官方 JDBC 驱动 Agent | | db2 | IBM DB2 | DB2 JDBC | | informix | IBM Informix | Informix JDBC | | neo4j | Neo4j | 官方 Neo4j Go Driver 原生 Agent | | nebula | NebulaGraph 3.x | 官方 NebulaGraph Go Client 原生 Agent | | cassandra | Apache Cassandra 2.1+ | Apache cassandra-gocql-driver 原生 Agent | | bigquery | Google BigQuery | BigQuery JDBC | | spanner | Google Cloud Spanner | Google Cloud Spanner JDBC | | kylin | Apache Kylin | Kylin JDBC | | ignite | Apache Ignite | Ignite JDBC thin（ignite-core） | | ignite3 | Apache Ignite 3 | Ignite 3 JDBC thin（ignite-jdbc） | | sundb | SunDB | SunDB JDBC | | tdengine | TDengine 2.4+ | taos-connector-rust 原生 WebSocket agent | | yashandb | 崖山 YashanDB | YashanDB JDBC | | xugu | 虚谷 XuguDB | XuguDB Go 原生 agent | | iotdb | Apache IoTDB | Apache IoTDB Go Client 原生 Agent | | etcd | etcd | jetcd | | zookeeper | Apache ZooKeeper | go-zookeeper 原生 Agent | | rabbitmq | RabbitMQ | amqp091-go 原生 agent | | rocketmq | Apache RocketMQ | rocketmq-admin-go 原生 agent | | iris | InterSystems IRIS | InterSystems IRIS JDBC | | cache | InterSystems Caché | InterSystems Caché JDBC (CacheDB) |

多 JRE 支持

多数 Java agent 以 JRE 21 为目标。原生 agent（如 `cassandra`、`duckdb`、`hive`、`iotdb`、`oracle`、`kingbase`、`tdengine`、`xugu`、`rabbitmq`、`rocketmq` 和 `zookeeper`）不需要 JRE。对 Java agent，DBX 会自动下载并管理 JRE 21 安装。

JDBC 连接池

所有多会话 Java JDBC agent 都通过 `AbstractJdbcAgent` 在同一个 Agent 运行时内共享 HikariCP 连接池。普通元数据请求和短查询按请求借还连接；分页游标和显式会话态 SQL 会固定连接，直到游标或逻辑会话关闭。带有会话状态的连接会直接淘汰，不会复用于其他会话。各 Agent 特有的 URL、传输协议兜底、加密文件和原生驱动行为通过共享生命周期钩子保留。

默认每个不可变连接身份最多建立 8 个物理连接，最小空闲连接数为 0。该默认值在限制短查询连接压力的同时，允许最多 8 个分页游标或会话态逻辑会话并发固定连接。可通过 JVM system property 或环境变量覆盖：

| System property | 环境变量 | 默认值 | |---|---|---:| | `dbx.agent.jdbc.pool.enabled` | `DBX_AGENT_JDBC_POOL_ENABLED` | `true` | | `dbx.agent.jdbc.pool.maximumPoolSize` | `DBX_AGENT_JDBC_POOL_MAXIMUM_POOL_SIZE` | `8` | | `dbx.agent.jdbc.pool.minimumIdle` | `DBX_AGENT_JDBC_POOL_MINIMUM_IDLE` | `0` | | `dbx.agent.jdbc.pool.connectionTimeoutMillis` | `DBX_AGENT_JDBC_POOL_CONNECTION_TIMEOUT_MILLIS` | `30000` | | `dbx.agent.jdbc.pool.validationTimeoutMillis` | `DBX_AGENT_JDBC_POOL_VALIDATION_TIMEOUT_MILLIS` | `5000` | | `dbx.agent.jdbc.pool.idleTimeoutMillis` | `DBX_AGENT_JDBC_POOL_IDLE_TIMEOUT_MILLIS` | `120000` | | `dbx.agent.jdbc.pool.maxLifetimeMillis` | `DBX_AGENT_JDBC_POOL_MAX_LIFETIME_MILLIS` | `1800000` | | `dbx.agent.jdbc.pool.retireMillis` | `DBX_AGENT_JDBC_POOL_RETIRE_MILLIS` | `300000` |

HikariCP 会直接打进启用连接池的 Agent JAR。已经使用 DBX 托管 JRE 21 的安装无需重新安装或替换 JRE。 如遇特定老驱动兼容问题，可设置 `DBX_AGENT_JDBC_POOL_ENABLED=false`，让该运行时回退到原来的“每个逻辑会话一个连接”行为。

选择驱动实现语言

对于新 agent，只要存在成熟、许可证兼容的原生驱动，优先选择**原生（Go 或 Rust）驱动**而非 Java/JDBC agent。原生 agent 以单一自包含可执行文件发布，无需 JRE，可显著降低内存占用和启动时间 —— 完全避开 Java agent 即便空闲也要付出的 JVM 基线开销。

• **原生（Go/Rust）** —— 存在可用原生驱动时首选。参考 `drivers/cassandra-go`（Apache cassandra-gocql-driver）、`drivers/duckdb`、`drivers/hive-go`（原生 HS2）、`drivers/iotdb`（Apache IoTDB Go Client）、`drivers/oracle-go`（go-ora）、`drivers/kingbase-go`（gokb）、`drivers/vastbase-go`（openGauss connector）、`drivers/tdengine`（taos-connector-rust）、`drivers/xugu`、`drivers/rabbitmq`（amqp091-go）、`drivers/rocketmq`（rocketmq-admin-go）和 `drivers/zookeeper`（go-zookeeper）。无需 JRE 下载与管理。
• **Java/JDBC** —— 当某数据库只有 JDBC 驱动，或原生驱动不成熟、缺乏维护时的默认兜底方案。多数 agent 仍属此类。

原生 agent 实现与 Java agent 相同的 JSON-RPC 契约和 `versions.json` 登记；它发布的是 `agent` 可执行文件而非 `agent.jar`。若同一数据库同时保留原生和 Java 源码实现，默认只发布原生产物；只有 Java 变体以独立兼容配置登记时才同时发布，例如 `oracle-legacy` / `oracle-10g`。

构建

需要 JDK 21（Gradle toolchain 会自动下载）。

./gradlew shadowJar
(cd drivers/oracle-go && go build -o agent .)
(cd drivers/cassandra-go && go build -o agent .)
(cd drivers/hive-go && go build -o agent .)
(cd drivers/iotdb && go build -o agent .)
(cd drivers/kingbase-go && go build -o agent .)
(cd drivers/vastbase-go && go build -o agent .)
(cargo build --manifest-path drivers/tdengine/Cargo.toml --release --locked)
(cd drivers/xugu && go build -o agent .)
(cd drivers/rabbitmq && go build -o agent .)
(cd drivers/rocketmq && go build -o agent .)
(cd drivers/zookeeper && go build -o agent .)

产物 JAR 在 `drivers/{module}/build/libs/`。原生 agent 从 `drivers/cassandra-go`、`drivers/duckdb`、`drivers/hive-go`、`drivers/iotdb`、`drivers/oracle-go`、`drivers/kingbase-go`、`drivers/vastbase-go`、`drivers/tdengine`、`drivers/xugu`、`drivers/rabbitmq`、`drivers/rocketmq` 和 `drivers/zookeeper` 构建。

本地 DBX 运行时测试

修改 `agents/drivers/<db_type>/` 下的 Java agent 或共享 Java agent 协议代码后，需重新构建目标 agent 并替换本地 DBX 应用使用的运行时 JAR：

./gradlew :<db_type>:shadowJar
cp ~/.dbx/agents/drivers/<db_type>/agent.jar ~/.dbx/agents/drivers/<db_type>/agent.jar.bak
cp agents/drivers/<db_type>/build/libs/*-all.jar ~/.dbx/agents/drivers/<db_type>/agent.jar

重启 DBX 或断开重连数据库，使新 agent 进程加载替换后的 JAR。

`cassandra`、`hive`、`iotdb`、`oracle`、`kingbase`、`tdengine`、`xugu`、`rabbitmq`、`rocketmq` 和 `zookeeper` 等原生 agent 使用可执行文件而非 `agent.jar`。TDengine 从