dbx 项目 Apache IoTDB 驱动基准测试全指南：JDBC 与 Go 客户端对比方法、配置与结果解读-创锋一号

dbx 项目 Apache IoTDB 驱动基准测试全指南：JDBC 与 Go 客户端对比方法、配置与结果解读

【免费下载链接】dbx20 MB lightweight cross-platform database client for 90+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具，支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90+ 数据库，提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。项目地址: https://gitcode.com/gh_mirrors/dbx7/dbx

本篇技术指南围绕 dbx 仓库中 agents/drivers/iotdb/bench/README.md 展开，系统讲解这套独立基准测试（benchmark）的设计动机、四种工作负载、完整环境变量配置、运行方式与源码级实现细节，并结合仓库内已有的 macOS arm64 实测数据（iotdb-2.0.8-macos-arm64.json）给出客观解读。读者读完可以自行复现 JDBC 与 Go 客户端在同一 Apache IoTDB 2.0.8 服务器上的对比测试，也能理解为何 dbx 生产环境的 IoTDB Agent 选择了 Go 客户端作为主力实现。

基准测试的背景与定位

dbx 的 IoTDB Agent 模块（agents/drivers/iotdb/）早期基于 JDBC 实现，后来整体迁移到官方 Apache IoTDB Go 客户端。本套基准测试正是那次迁移决策所依赖的对比依据，它被独立保留在 agents/drivers/iotdb/bench/ 目录下，用于回答一个核心问题：

在同样的 Tree 模型服务器与相同测试数据上，Apache IoTDB 官方 2.0.8 的 JDBC 客户端与 Go 客户端，在冷启动、建连、常驻内存和各类查询延迟上分别表现如何？

需要特别强调它的定位：

这是一份客户端驱动的对比（client-side comparison），不是 IoTDB 服务器吞吐量压测；
它只比较驱动本身，不包含dbx 的 JSON-RPC Agent 协议层；
它也不证明功能与版本兼容性完全对齐，那些由 integration_test.go 等生产测试负责。

从源码结构看，基准目录内同时保留了 Java 版 JDBC 基准、Go 版基准、Python 调度器以及实测结果，三者共同构成一套可复现的对比闭环。

测试范围与核心方法论

固定测试数据

基准测试默认在root.dbx_bench.d1设备下准备10,000 行Tree 模型数据，包含三个时间序列（字段）：

时间序列	数据类型	编码方式
`s1`	INT64	RLE
`s2`	DOUBLE	GORILLA
`s3`	TEXT	PLAIN

数据由 JDBC 侧负责灌入（IOTDB_BENCH_MODE=prepare），插入时以批量方式写入，默认每 500 行执行一次executeBatch()（对应源码中的BENCH_INSERT_BATCH_SIZE配置），每行按(time, s1=row*10, s2=row/10.0, s3="row-<n>")生成。

四种工作负载

工作负载	SQL	默认迭代次数	数据规模
`show_databases`	`SHOW DATABASES`	20	元数据查询
`point_query`	`SELECT s1,s2,s3 FROM root.dbx_bench.d1 WHERE time = <rows/2>`	100	1 行单点查询
`range_100`	`SELECT s1,s2,s3 FROM root.dbx_bench.d1 LIMIT 100`	30	100 行范围查询
`scan_all`	`SELECT s1,s2,s3 FROM root.dbx_bench.d1`	5	全表扫描 10,000 行

四个负载恰好覆盖了元数据、精确点查、小范围查询与全量扫描四种典型访问模式，其中scan_all承担最大的服务端工作量和结果解码压力（10,000 行 × 3 列 = 40,000 个单元格）。

两条重要的公平性设计

全量解码每个返回单元格：两种客户端在计时区间内都会逐行逐列调用取值 API——Go 侧是dataset.GetObjectByIndex（见 go/main.go 的executeQuery函数），JDBC 侧是resultSet.getObject(column)（见 JdbcDriverBenchmark.java 的executeQuery方法）。也就是说，测量的是"取回并解码"的完整链路，而不是只下发 SQL 就结束。
结果形状稳定性校验：每次迭代都会记录返回行数与解码单元格数，若同一工作负载不同轮次的结果形状不一致，直接报错终止（Unstable result shape），防止因数据变化导致无效对比。

此外，每个工作负载在正式采样前都会执行若干次预热（warmup，默认 3 次；scan_all因成本较高预热次数被限制为最多 1 次），以减少缓存与 JIT 等因素对首轮数据的干扰。

环境准备与依赖

运行前需要准备以下环境：

Java：JDK（参考实测环境为 Java 21.0.7），用于构建和运行 JDBC 基准；
Go：1.23+（bench 的 go.mod 声明go 1.23），用于构建 Go 基准；
Apache IoTDB 2.0.8standalone 服务器（Docker 或本地进程均可）；
Python 3：运行调度器run.py；
gradlew：仓库根目录的 Gradle wrapper（gradlew），用于构建 JDBC 基准 JAR。

双方客户端均锁定在2.0.8版本：JDBC 侧通过org.apache.iotdb.jdbc.IoTDBDriver加载，Go 侧通过github.com/apache/iotdb-client-go/v2 v2.0.8引入（见 go.mod），保证同一协议版本下的可比性。

启动 IoTDB 测试服务器

基准测试需要一个可用的 IoTDB 实例。最便捷的方式是使用官方 standalone Docker 镜像，例如：

docker run --rm --name dbx-iotdb-bench -p 6667:6667 apache/iotdb:2.0.8-standalone

容器启动后，必须等待 6667 端口就绪再开始运行基准。调度器run.py内置了端口探测逻辑（wait_for_server），它会以 0.5 秒为间隔重试连接，默认在 60 秒（BENCH_SERVER_TIMEOUT）内等待服务器就绪，超时则抛出IoTDB is not reachable at <host>:<port>错误。

运行基准测试

在仓库根目录执行：

python3 agents/drivers/iotdb/bench/run.py \ > /tmp/dbx-iotdb-driver-benchmark.json

调度器会把完整结果以 JSON 形式输出到 stdout，重定向到文件后即可留存和分析。以下是run.py的内部执行流程（见 run.py）：

探测服务器：等待IOTDB_HOST:IOTDB_PORT可达；
构建两个候选（除非设置BENCH_SKIP_BUILD=true）：
- JDBC：通过仓库根目录的gradlew执行benchmarkJar任务，产物为build/libs/dbx-iotdb-jdbc-benchmark.jar；
- Go：在bench/go目录执行go build -o build/iotdb-go-benchmark .；
重建 fixture（除非BENCH_PREPARE=false）：以IOTDB_BENCH_MODE=prepare运行 JDBC 基准，重建root.dbx_bench数据库并灌入数据；
冷启动采样：交替顺序运行probe模式，采集"进程启动 + 建连"耗时，默认 5 轮；
常驻 RSS 采样：以hold模式启动进程并保持连接，用ps -o rss=读取常驻内存，默认 3 次；
正式基准轮次：以benchmark模式交替运行双方，默认 3 轮，每轮完整跑完四种工作负载。

一个容易被忽视的细节是候选顺序交替：无论是冷启动、RSS 还是正式轮次，每次迭代都会反转执行顺序（names if iteration % 2 == 0 else list(reversed(names))），用于抵消先运行方可能占有的系统缓存优势。

四种运行模式

两份客户端基准通过环境变量IOTDB_BENCH_MODE切换行为，可取值：

模式	行为	用途
`prepare`	重建`root.dbx_bench`数据库并批量插入数据（仅 JDBC 支持）	准备 fixture
`probe`	启动、建连、执行一次`SHOW DATABASES`后立即退出并输出 JSON	测量冷启动
`hold`	启动、建连、执行一次查询后打印`ready`JSON 并休眠（默认 30 秒）	测量常驻 RSS
`benchmark`	完整跑四种工作负载并输出详细结果 JSON	正式对比

这些模式在 JdbcDriverBenchmark.java 的main与 go/main.go 的main中一一对应实现。

配置参数详解

基准的全部行为都由环境变量控制，无需改动任何代码。除原 README 列出的参数外，源码中还定义了若干补充参数，下面一并整理。

服务器连接参数

环境变量	默认值	说明
`IOTDB_HOST`	`127.0.0.1`	IoTDB 服务器地址
`IOTDB_PORT`	`6667`	IoTDB 服务端口
`IOTDB_USERNAME`	`root`	用户名
`IOTDB_PASSWORD`	`root`	密码
`BENCH_CONNECT_TIMEOUT_MS`	`5000`	建连超时（毫秒），Go 侧`session.Open(false, timeout)`使用
`BENCH_QUERY_TIMEOUT_MS`	`30000`	查询超时（毫秒），Go 侧传给`ExecuteQueryStatement(sql, &timeout)`

fixture 与采样规模参数

环境变量	默认值	说明
`BENCH_ROWS`	`10000`	fixture 行数
`BENCH_FETCH_SIZE`	`1024`	每批拉取行数，JDBC 与 Go 双方保持一致
`BENCH_INSERT_BATCH_SIZE`	`500`	灌数据时的 JDBC 批量插入粒度（仅 prepare 阶段）
`BENCH_STARTUPS`	`5`	冷启动采样次数
`BENCH_RSS_SAMPLES`	`3`	常驻 RSS 采样次数
`BENCH_ROUNDS`	`3`	正式基准轮数
`BENCH_ORDER`	`jdbc,go`	候选执行顺序；设`go,jdbc`可检查顺序效应
`BENCH_WARMUPS`	`3`	每个工作负载的预热次数（`scan_all`最多 1 次）
`BENCH_METADATA_ITERATIONS`	`20`	`SHOW DATABASES`采样次数
`BENCH_POINT_ITERATIONS`	`100`	单点查询采样次数
`BENCH_RANGE_ITERATIONS`	`30`	100 行范围查询采样次数
`BENCH_SCAN_ITERATIONS`	`5`	全量扫描采样次数

流程控制参数

环境变量	默认值	说明
`BENCH_PREPARE=false`	`true`	设为`false`时保留已有 fixture，跳过数据重建
`BENCH_SKIP_BUILD=true`	`false`	设为`true`时复用已有的 JAR 与 Go 二进制，跳过构建
`BENCH_HOLD_MS`	`30000`	`hold`模式的保持时长（毫秒）
`BENCH_SERVER_TIMEOUT`	`60.0`	等待服务器就绪的超时（秒）
`BENCH_COMMAND_TIMEOUT`	`180.0`	单个子命令的执行超时（秒）
`BENCH_READY_TIMEOUT`	`30.0`	等待`hold`模式输出`ready`信号的超时（秒）

关键注意事项：两个候选必须连接同一台服务器，且不要在候选之间改动 fixture 或 fetch size，否则对比失去意义。这是一份客户端对比，切勿把它当作 IoTDB 服务端的吞吐能力基准。

输出 JSON 结构解读

run.py最终输出的 JSON 包含以下顶层字段（与 run.py 的output构建逻辑对应）：

server：服务器地址与端口；
config：rows、fetch_size、warmups 等生效配置；
artifact_bytes：两个候选产物体积（JAR 与 Go 二进制字节数）；
startup_ms：冷启动（进程 + 建连）样本的 count/mean/p50/p95/min/max；
connected_rss_kb：常驻内存样本统计（KB）；
results：按候选分组，包含建连耗时（connect_ms）统计与每种工作负载的round_mean_ms、round_p50_ms、round_p95_ms，以及每一轮的原始明细（rounds数组）。

每个工作负载的单轮明细形如：

{ "name": "point_query", "iterations": 100, "rows": 1, "decoded_cells": 4, "mean_ms": 0.565, "p50_ms": 0.538, "p95_ms": 0.788, "min_ms": 0.404, "max_ms": 0.86 }

其中decoded_cells是判断解码成本的关键指标（scan_all 为 40,000）。仓库中已保存一份完整原始数据：iotdb-2.0.8-macos-arm64.json。

参考实测结果（macOS arm64）

仓库自带的 results/README.md 汇总了一次真实运行结果，环境为：Apple M2 Pro（macOS arm64）、Java 21.0.7、Go 1.26.5、IoTDB 2.0.8 standalone、双方客户端均锁定 2.0.8、10,000 行 Tree 数据、fetch size 1,024、15 次交替冷启动、5 次 RSS 采样、5 轮交替工作负载。

指标	JDBC	Go	Go 相对下降
冷启动（进程 + 建连）p50	172.612 ms	9.315 ms	94.6%
常驻 RSS p50	62,368 KB	7,008 KB	88.8%
产物体积	25,864,492 B	6,475,202 B	75.0%
进程内建连均值	66.061 ms	1.932 ms	97.1%
`SHOW DATABASES`均值	0.775 ms	0.428 ms	44.8%
单点查询均值	0.813 ms	0.595 ms	26.8%
100 行查询均值	1.437 ms	1.010 ms	29.7%
10,000 行全量解码均值	5.455 ms	4.941 ms	9.4%

如何解读这份数据

数据呈现出一个清晰的分层结论：

优势最大的维度是冷启动、内存与产物体积。Go 客户端冷启动快 94.6%（JVM 启动开销消失），常驻内存不到 JDBC 的八分之一（62 MB → 7 MB），单一二进制产物仅 6.5 MB。这三个维度直接决定了 Agent 进程的拉起速度、资源占用和分发成本——这正是 dbx 将生产 IoTDB Agent 迁移到 Go 的主要动因。
建连延迟差距同样显著：进程内建连从约 66 ms 降到约 1.9 ms。需要区分的是，冷启动指标已包含进程拉起，而connect_ms是连接建立本身的开销，两者都被 Go 大幅改善。
热查询差距相对温和，且随工作负载加重而收窄：元数据查询快 44.8%，点查询快 26.8%，100 行查询快 29.7%，而全量扫描解码 40,000 个单元格时仅快 9.4%。这符合预期——服务端处理与结果解码的工作量越大，客户端语言差异在总耗时中的占比就越小。
结论方向：该结果支持以 Go Agent 换取启动、建连、内存与分发体积上的收益；热查询差异小到不足以成为迁移的阻碍。但正如 results/README.md 明确声明的：此基准不包含dbx JSON-RPC Agent 层，也不能证明功能与版本兼容性的完全对齐——那些需要依赖生产 Agent 的功能测试来保证。

生产 Agent 的迁移现状（源码侧佐证）

当前 agents/drivers/iotdb/README.md 明确说明：该模块以官方 Apache IoTDB Go 客户端实现 DBX Agent 协议，默认使用 Tree SQL，可通过sql_dialect=table切换 Table 模型。其连接参数（fetch_size、time_zone、connect_retry_max、ssl、node_urls等）与基准测试中的部分配置一脉相承。

值得注意的实现细节：仓库将上游 Go 客户端 vendored 在 agents/go-common/iotdb-client-go 下并打了一个补丁——上游丢弃了 1.3.x 服务器的ColumnNameIndexMap回退逻辑，会导致聚合结果与 SELECT 列顺序错位；补丁后的客户端在缺少有序索引列表时，通过服务器提供的名称索引映射值列。这说明基准测试只是决策链的一环，真正的兼容性保障来自 integration_test.go 等测试（可通过DBX_IOTDB_LIVE=1 go test -race ./... -count=1针对真实服务器运行）。

局限性与复现注意事项

复现或引用这套基准时，请留意以下边界：

单机单配置：仓库仅保存了 macOS arm64 一组结果，换到 Linux x86_64、不同 JDK/Go 版本或不同磁盘/网络环境下，绝对数值必然变化，相对趋势也未必完全一致；
客户端对比，非服务器压测：不要用这些数值推断 IoTDB 服务器容量；
不含 Agent 协议层：结果不能直接代表 dbx 生产 Agent 端到端性能；
fetch size 一致性：对比双方时务必保持相同 fetch size 与 fixture，否则结论无效；
顺序效应：默认BENCH_ORDER=jdbc,go，建议用BENCH_ORDER=go,jdbc复跑一轮以确认无顺序偏差。

企业官网建设流程全解析