t8y2--dbx
wehub-resource-sync
115 行
5.2 KiB
Markdown
115 行
5.2 KiB
Markdown
# DBX Agents
|
||
|
||
[English](README.md) | 简体中文
|
||
|
||
DBX 的 Agent 驱动 —— 通过 JDBC 和原生数据库驱动支持各种数据库。
|
||
|
||
每个 agent 作为独立进程运行，通过 stdin/stdout 与 DBX 进行 JSON-RPC 2.0 通信。
|
||
|
||
## 支持的数据库
|
||
|
||
| Agent | 数据库 | JDBC 驱动 |
|
||
|-------|----------|-------------|
|
||
| access | Microsoft Access | UCanAccess |
|
||
| dameng | 达梦 DM8 | DM JDBC |
|
||
| kingbase | 人大金仓 KingbaseES | KingbaseES JDBC |
|
||
| vastbase | Vastbase | Vastbase 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 | Hive JDBC |
|
||
| db2 | IBM DB2 | DB2 JDBC |
|
||
| informix | IBM Informix | Informix JDBC |
|
||
| neo4j | Neo4j | Neo4j JDBC |
|
||
| cassandra | Apache Cassandra | Cassandra JDBC |
|
||
| bigquery | Google BigQuery | BigQuery JDBC |
|
||
| kylin | Apache Kylin | Kylin JDBC |
|
||
| sundb | SunDB | SunDB JDBC |
|
||
| tdengine | TDengine | taos-jdbcdriver（WebSocket，REST 兜底） |
|
||
| yashandb | 崖山 YashanDB | YashanDB JDBC |
|
||
| xugu | 虚谷 XuguDB | XuguDB Go 原生 agent |
|
||
| iotdb | Apache IoTDB | IoTDB JDBC |
|
||
| etcd | etcd | jetcd |
|
||
| zookeeper | Apache ZooKeeper | Apache Curator |
|
||
|
||
|
||
## 多 JRE 支持
|
||
|
||
多数 Java agent 以 JRE 21 为目标。原生 agent（如 `oracle` 和 `xugu`）不需要 JRE。对 Java agent，DBX 会自动下载并管理 JRE 21 安装。
|
||
|
||
## 选择驱动实现语言
|
||
|
||
对于新 agent，只要存在成熟、许可证兼容的原生驱动，优先选择**原生（Go 或 Rust）驱动**而非 Java/JDBC agent。原生 agent 以单一自包含可执行文件发布，无需 JRE，可显著降低内存占用和启动时间 —— 完全避开 Java agent 即便空闲也要付出的 JVM 基线开销。
|
||
|
||
- **原生（Go/Rust）** —— 存在可用原生驱动时首选。参考 `drivers/oracle-go`（go-ora）和 `drivers/xugu`。无需 JRE 下载与管理。
|
||
- **Java/JDBC** —— 当某数据库只有 JDBC 驱动，或原生驱动不成熟、缺乏维护时的默认兜底方案。多数 agent 仍属此类。
|
||
|
||
原生 agent 实现与 Java agent 相同的 JSON-RPC 契约和 `versions.json` 登记；它发布的是 `agent` 可执行文件而非 `agent.jar`。若同一数据库同时存在原生和 Java 路径，DBX 默认使用原生方案，仅将 Java 变体作为兼容兜底保留 —— 参见 `oracle`（go-ora 原生）与 `oracle-legacy` / `oracle-10g` 的共存方式。
|
||
|
||
## 构建
|
||
|
||
需要 JDK 21（Gradle toolchain 会自动下载）。
|
||
|
||
```bash
|
||
./gradlew shadowJar
|
||
(cd drivers/oracle-go && go build -o agent .)
|
||
(cd drivers/xugu && go build -o agent .)
|
||
```
|
||
|
||
产物 JAR 在 `drivers/{module}/build/libs/`。原生 agent 从 `drivers/oracle-go` 和 `drivers/xugu` 构建。
|
||
|
||
### 本地 DBX 运行时测试
|
||
|
||
修改 `agents/drivers/<db_type>/` 下的 Java agent 或共享 Java agent 协议代码后，需重新构建目标 agent 并替换本地 DBX 应用使用的运行时 JAR：
|
||
|
||
```bash
|
||
./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。
|
||
|
||
`oracle` 和 `xugu` 等原生 agent 使用驱动目录下的 `agent` 可执行文件而非 `agent.jar`。
|
||
|
||
## 版本管理
|
||
|
||
Agent 模块的版本记录在 [`versions.json`](versions.json) 中，遵循以下规则：
|
||
|
||
- **修改现有驱动**：无需手动编辑 `versions.json`。发版 CI 会把每个 `drivers/<module>/` 目录与上一个 tag 做对比，对有变更的模块自动 bump patch 版本号（见 [`bump-agent-versions.mjs`](../.github/scripts/bump-agent-versions.mjs)）。若改动的是共享运行时 `agents/common`，所有依赖它的模块会一并 bump。
|
||
- **新增驱动**：在 `versions.json` 中新增一行，例如 `"rabbitmq": "0.1.0"`。CI 只 bump 文件里已存在的 key，所以新模块在登记到这里之前对版本管理完全不可见。同一次改动中，还要把模块加进 `settings.gradle` 并更新上方的支持表 —— `versions.json` 的 key 必须与 `settings.gradle` 声明的 agent 模块一致（不含 `common`、`test-support` 这类基础设施模块）。
|
||
|
||
## 开发
|
||
|
||
- Agent 编写指南：[docs/agent-authoring.md](docs/agent-authoring.md)
|
||
- JDBC agent 模板：[docs/examples/jdbc-agent-template](docs/examples/jdbc-agent-template)
|
||
- 发布检查清单：[docs/release-checklist.md](docs/release-checklist.md)
|
||
|
||
## 架构
|
||
|
||
```
|
||
DBX 主进程 (Rust/Tauri)
|
||
│ stdin/stdout (JSON-RPC 2.0)
|
||
▼
|
||
agent / java -jar dbx-agent-{type}.jar
|
||
│
|
||
▼
|
||
原生驱动 / JDBC → 数据库
|
||
```
|
||
|
||
## 许可证
|
||
|
||
[AGPL-3.0](https://github.com/t8y2/dbx/blob/main/LICENSE)
|