dbx/agents

DBX Agents

English | 简体中文

Agent drivers for DBX — database support via JDBC and native database drivers.

Each agent runs as a standalone process and communicates with DBX via stdin/stdout JSON-RPC 2.0.

Supported Databases

Agent	Database	Driver
access	Microsoft Access	UCanAccess
dameng	达梦 DM8	DM JDBC
kingbase	人大金仓 KingbaseES	gokb Go native agent
vastbase	Vastbase	openGauss Go native 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 Mode	OceanBase JDBC
gbase8a	GBase 8a	External GBase 8a JDBC
gbase8s	GBase 8s	External GBase 8s JDBC
oracle	Oracle 10g+	go-ora native agent
h2	H2	H2 JDBC
snowflake	Snowflake	Snowflake JDBC
trino	Trino (Presto)	Trino JDBC
hive	Apache Hive	Hive JDBC
db2	IBM DB2	DB2 JDBC
informix	IBM Informix	Informix JDBC
neo4j	Neo4j	Official Neo4j Go Driver native agent
cassandra	Apache Cassandra 2.1+	Apache cassandra-gocql-driver native agent
bigquery	Google BigQuery	BigQuery JDBC
kylin	Apache Kylin	Kylin JDBC
sundb	SunDB	SunDB JDBC
tdengine	TDengine 2.4+	taos-connector-rust native WebSocket agent
yashandb	崖山 YashanDB	YashanDB JDBC
xugu	虚谷 XuguDB	XuguDB Go native agent
iotdb	Apache IoTDB	IoTDB JDBC
etcd	etcd	jetcd
zookeeper	Apache ZooKeeper	Apache Curator
rabbitmq	RabbitMQ	amqp091-go native agent

Multi-JRE Support

Most Java agents target JRE 21. Native agents, such as cassandra, duckdb, oracle, kingbase, tdengine, xugu, and rabbitmq, do not require a JRE. DBX downloads and manages the JRE 21 installation automatically for Java agents.

JDBC Connection Pooling

All multi-session Java JDBC agents share HikariCP pools inside one Agent runtime through AbstractJdbcAgent. Ordinary metadata and short query requests borrow and return a connection, while paged cursors and explicit session-state SQL keep their connection pinned until the cursor or logical session closes. Stateful connections are evicted instead of being reused by another session. Agent-specific URL, transport fallback, encrypted-file, and native-driver behavior is preserved through shared lifecycle hooks.

The default maximum is 8 physical connections per immutable connection identity, with 0 minimum idle connections. This keeps short-query connection pressure bounded while allowing up to 8 concurrently pinned paged cursors or stateful sessions. The defaults can be overridden with JVM system properties or environment variables:

System property	Environment variable	Default
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 is shaded into each pooled Agent JAR. Existing installations already using the managed JRE 21 do not need to reinstall or replace the JRE. Set DBX_AGENT_JDBC_POOL_ENABLED=false for a runtime-level compatibility fallback to the previous one-connection-per-logical-session behavior.

Choosing a Driver Language

For new agents, prefer a native (Go or Rust) driver over a Java/JDBC agent whenever a mature, license-compatible native driver is available. Native agents ship as a single self-contained executable with no JRE, which significantly reduces memory footprint and startup time — the JVM baseline that every Java agent pays even when idle is avoided entirely.

• Native (C++/Go/Rust) — preferred when a usable native driver exists. See drivers/cassandra-go (Apache cassandra-gocql-driver), drivers/duckdb, drivers/oracle-go (go-ora), drivers/kingbase-go (gokb), drivers/vastbase-go (openGauss connector), drivers/tdengine (taos-connector-rust), drivers/xugu, and drivers/rabbitmq (amqp091-go) as reference implementations. No JRE download or management is needed.
• Java/JDBC — the default fallback when only a JDBC driver exists for the database, or when the native driver is immature or unmaintained. Most agents still fall in this category.

Native agents implement the same JSON-RPC contract and versions.json registration as Java agents; they ship an agent executable instead of agent.jar. If both native and Java source implementations exist for the same database, publish only the native artifact unless the Java variant has a separately registered compatibility profile, such as oracle-legacy / oracle-10g.

Build

Requires JDK 21 (Gradle toolchain auto-downloads if needed).

./gradlew shadowJar
(cd drivers/oracle-go && go build -o agent .)
(cd drivers/cassandra-go && 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 .)

Output JARs are in drivers/{module}/build/libs/. Native agents build from drivers/cassandra-go, drivers/oracle-go, drivers/kingbase-go, drivers/vastbase-go, drivers/tdengine, drivers/xugu, and drivers/rabbitmq.

Local DBX Runtime Test

When changing a Java agent under agents/drivers/<db_type>/ or shared Java agent protocol code, rebuild the target agent and replace the runtime JAR used by the local DBX app:

./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

Restart DBX or disconnect and reconnect the database so the new agent process loads the replacement JAR.

Native agents such as cassandra, oracle, kingbase, tdengine, xugu, and rabbitmq use an agent executable instead of agent.jar. TDengine builds target/release/dbx-tdengine-driver from drivers/tdengine/Cargo.toml.

Versioning

Agent module versions are tracked in versions.json.

• Changing an existing driver — do not edit versions.json manually. The release CI diffs each drivers/<module>/ directory against the previous tag and auto-bumps the patch version for every changed module (see bump-agent-versions.mjs). A change to the shared agents/common runtime bumps every module that packages it.
• Adding a new driver — add an entry to versions.json, e.g. "rabbitmq": "0.1.0". The CI only bumps keys already present in the file, so a new module is invisible to versioning until it is registered here. Java modules must also be added to settings.gradle; native modules must be registered in the release version script and workflow. Update the support table in the same change.

Development

• Agent authoring guide: docs/agent-authoring.md
• JDBC agent template: docs/examples/jdbc-agent-template
• Release checklist: docs/release-checklist.md

Architecture

DBX Main Process (Rust/Tauri)
    │ stdin/stdout (JSON-RPC 2.0)
    ▼
agent / java -jar dbx-agent-{type}.jar
    │
    ▼
Native driver / JDBC → Database

License

AGPL-3.0