TDengine JDBC 基准测试工具 taosdemo 完整实战指南构建、参数详解与源码原理【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengineTDengine 开源仓库中内置了一套基于 JDBC 驱动的性能测试与功能演示工具 taosdemo它面向工业物联网IIoT等海量时序数据写入场景通过命令行参数即可灵活构造超级表、批量创建子表并多线程灌入千万级数据。本文以 taosdemo 官方说明 为主体结合该工具在仓库中的完整 Java 源码系统讲解其构建运行方式、全部命令行参数、两种写入模式以及底层调用链与常见问题排查帮助你快速上手用它验证 TDengine 的写入吞吐与超表建模能力。taosdemo 是什么一个 JDBC 驱动的 TDengine 压测与演示工具taosdemo 位于仓库的 docs/examples/JDBC/taosdemo 目录是一个 Maven 构建的独立 Java 工程artifactId为taosdemo版本2.0.1详见 pom.xml。它通过官方taos-jdbcdriver版本 3.8.3连接 TDengine核心能力包括自动建库按keep / days / replica / cache / blocks / precision等参数创建目标数据库自动建模通过-superTableSQL传入建表语句或按字段数、标签数自动生成超级表结构批量建子表多线程并发创建大量按前缀 序号命名的子表多线程写入支持有序/乱序数据模拟、指定每条 SQL 的表数与行数、控制写入频率查询与清理可执行指定 SQL、退出前可选删除表数据。从源码结构看整个工程采用了典型的 Service / DAO 分层TaosDemoApplication为入口DatabaseService、SuperTableService、SubTableService、QueryService负责业务编排SqlSpeller负责拼接 SQLDataGenerator系列负责构造字段值与标签值JdbcTaosdemoConfig负责解析全部命令行参数。该工具本质上是把一次典型的 TDengine 建模 批量写入流程脚本化、参数化因此它既是一个压测工具也是一份学习 JDBC 写入时序数据的最佳示例。环境准备与构建打包前置条件JDK 17 或更高版本pom.xml 中maven-compiler-plugin配置了source/target 17Maven 3.x可用的 TDengine 服务端以及本机已安装 TDengine 客户端taos 原生驱动依赖客户端动态库。工程目录下已附带 Maven Wrappermvnw/mvnw.cmd在不具备全局 Maven 的环境下也可以直接使用。构建命令进入工程目录后执行cd docs/examples/JDBC/taosdemo mvn clean package -Dmaven.test.skiptrue关键点说明-Dmaven.test.skiptrue跳过单元测试以加快打包。工程在src/test/java下提供了SqlSpellerTest、SuperTableServiceTest、DataGeneratorTest、TimeStampUtilTest等测试类见 test 目录需要验证代码时去掉该参数即可构建产物由maven-assembly-plugin生成jar-with-dependencies形式即target/taosdemo-2.0.1-jar-with-dependencies.jar内含全部第三方依赖可直接java -jar运行打包会拉取taos-jdbcdriver 3.8.3、Spring 6.2.11、HikariCP 5.1.0、fastjson2 与 log4j2 等依赖见 pom.xml请确保网络可达 Maven 中央仓库。快速运行两种写入模式方式一先建表再插入数据java -jar target/taosdemo-2.0.1-jar-with-dependencies.jar \ -host hostname -database db name \ -doCreateTable true \ -superTableSQL create table weather(ts timestamp, f1 int) tags(t1 nchar(4)) \ -numOfTables 1000 \ -numOfRowsPerTable 100000000 \ -numOfThreadsForInsert 10 \ -numOfTablesPerSQL 10 \ -numOfValuesPerSQL 100该模式下工具会依次执行创建数据库 → 根据-superTableSQL创建超级表weather→ 创建t1~t1000共 1000 张子表 → 启动 10 个线程并发插入数据。方式二跳过建表直接写入自动建表java -jar target/taosdemo-2.0.1-jar-with-dependencies.jar \ -host hostname -database db name \ -doCreateTable false \ -superTableSQL create table weather(ts timestamp, f1 int) tags(t1 nchar(4)) \ -numOfTables 1000 \ -numOfRowsPerTable 100000000 \ -numOfThreadsForInsert 10 \ -numOfTablesPerSQL 10 \ -numOfValuesPerSQL 100差别在于-doCreateTable false不再预先批量创建子表而是配合-autoCreateTable使用INSERT INTO ... USING ... TAGS(...) VALUES(...)语法在写入时自动建子表详见下文“自动建表写入”小节。运行流程对应源码从入口 TaosDemoApplication.java 可以看到完整执行链解析参数得到JdbcTaosdemoConfig若指定--help或未提供-host则打印帮助并退出通过DataSourceFactory.getInstance(host, port, user, password)建立连接池若指定了-executeSql则仅执行该 SQL 后退出查询模式否则DatabaseService创建并使用数据库依据-superTableSQL或字段/标签数量生成SuperTableMetaSuperTableService建超级表SubTableService并发建子表计算起始时间戳后SubTableService.insertMultiThreads多线程灌数据并统计影响行数若-dropTable true退出前删除超级表连同子表。命令行参数全解析所有参数均在该工具printHelp()中声明并在构造函数中逐一解析见 JdbcTaosdemoConfig.java。下表按用途分组整理连接参数instance参数说明默认值-host目标 TDengine 主机必填缺失时程序仅打印帮助无-portTCP 连接端口6030-user连接用户名root-password连接密码taosdata数据库参数database参数说明默认值-database目标数据库名不存在则自动创建jdbcdb-keep数据保留天数3650-days库内分文件的时间跨度天30-replica副本数取值范围 1~31-blocks文件块数块缓存相关16-cache内存块缓存大小MB8-precision时间精度ms这些参数最终由 SqlSpeller.createDatabase 拼装成CREATE DATABASE IF NOT EXISTS db keep ... days ...d replica ... cache ... blocks ... precision ...。从该方法可见除上述六个参数外底层 SQL 拼装还预留了minrows / maxrows / comp / walLevel / quorum / fsync / update等建库参数位读者若需自定义更多建库选项可在此扩展。超级表参数super table参数说明默认值-doCreateTable是否创建超级表与子表true-superTable超级表名称weather-prefixOfFields自动生成列名前缀col-numOfFields自动生成列的数量不含 ts未指定时使用默认建表 SQL-prefixOfTags自动生成标签名前缀tag-numOfTags自动生成标签的数量未指定时使用默认建表 SQL-superTableSQL自定义建表 SQL指定后numOfFields与numOfTags失效默认建表 SQL 见下未指定-superTableSQL且numOfFields 0时程序使用默认建表语句create table database.weather (ts timestamp, temperature float, humidity int) tags(location nchar(64), groupId int)在 TaosDemoApplication.java 中超级表元数据有三种来源优先使用-superTableSQL由SuperTableMetaGenerator.generate(sql)解析出库名、表名、列与标签否则若numOfFields 0使用上述默认建表 SQL否则按numOfFields / numOfTags自动生成首列固定为ts timestamp其余列名为col1..colN、标签名为tag1..tagM类型从TaosConstants.DATA_TYPES中循环取值见 SuperTableMetaGenerator.java。子表参数sub table参数说明默认值-prefixOfTable子表名前缀子表名为前缀 序号从 1 开始t-numOfTables子表数量1-numOfThreadsForCreate创建子表时的线程数1子表通过CREATE TABLE IF NOT EXISTS db.table USING db.supertable TAGS(...)语句创建见 SqlSpeller.createTableUsingSuperTable。在 SubTableService.createSubTable 中使用固定线程池按numOfThreadsForCreate并发提交建表任务并awaitTermination等待全部完成。写入任务参数insert task参数说明默认值-autoCreateTable是否使用INSERT ... USING ... TAGS(...)自动建表写入false-numOfRowsPerTable每张子表写入的记录数1-numOfThreadsForInsert写入线程数1-numOfTablesPerSQL每条 INSERT SQL 覆盖的子表数1-numOfValuesPerSQL每条 INSERT SQL 每条子表包含的值行数1-startTime写入起始时间格式yyyy-MM-dd HH:mm:ss.SSS不指定则取当前时间向前回退keep-1天自动计算-timeGap同表相邻两行的时间间隔毫秒1000-frequency每秒写入单表的记录数限速用0 表示不限速0-order写入顺序0有序、1乱序0-rate乱序数据占比仅order1生效0~10010-range乱序数据偏移范围毫秒仅order1生效1000写入执行细节源码视角在 SubTableService.insertMultiThreads 中表区间[startInd, endInd)按线程数均分每个InsertTask内循环“行分片 × 表分片”当numOfRowsPerTable numOfValuesPerSQL时自动将numOfValuesPerSQL收缩到行数表数不足时同理收缩numOfTablesPerSQL每批数据由SubTableValueGenerator.generate构造时间戳按startTime rowCnt * timeGap递增见 SubTableValueGenerator.java若order ! 0则调用SubTableValueGenerator.disrupt(data, rate, range)对时间戳做乱序扰动若autoCreateTable为真走INSERT INTO db.table USING db.super TAGS(...) VALUES(...)否则走普通多表INSERT INTO db.table VALUES(...)SQL 拼装见 SqlSpeller.java最后按行数汇总影响行数并打印耗时与吞吐。查询与清理参数参数说明默认值-executeSql指定要执行的 SQL执行后程序退出不执行建表/写数流程无-dropTable退出前删除超级表级联删子表false--help打印上述全部帮助信息--executeSql对应 TaosDemoApplication.java 中的早退分支单独起线程执行 SQL 后立即结束可用于在压测前后验证数据量或跑聚合查询。连接池与 JDBC 驱动配置连接由 DataSourceFactory.java 以单例方式初始化底层是 HikariCP 连接池配置来自资源文件 application.properties# jdbc.drivercom.taosdata.jdbc.rs.RestfulDriver jdbc.drivercom.taosdata.jdbc.TSDBDriver hikari.maximum-pool-size20 hikari.minimum-idle20 hikari.max-lifetime0要点原生驱动默认com.taosdata.jdbc.TSDBDriverJDBC URL 为jdbc:TAOS://host:port/?charsetUTF-8localeen_US.UTF-8timezoneUTC-8走 6030 端口需要本机安装 TDengine 客户端动态库WebSocket 驱动若将jdbc.driver改为com.taosdata.jdbc.ws.WebSocketDriver可参考被注释的 RestfulDriver 行则连接串切换为jdbc:TAOS-WS://host:6041/?...varcharAsStringtrue走 6041 端口无需本地客户端库连接池规模代码默认maximum-pool-size500、minimum-idle100而application.properties将其覆盖为 20当提高-numOfThreadsForInsert时建议同步调大连接池上限避免写入线程等待连接。常见问题排查官方 readme 特别提示了最典型的运行错误Exception in thread main java.lang.UnsatisfiedLinkError: no taos in java.library.path原因这是使用原生TSDBDriver时的经典报错说明 JVM 加载taos本地动态库失败。请按序排查是否已安装 TDengine 客户端包或本机是否已编译并安装 TDengine动态库通常位于/usr/lib或/usr/local/lib若确认已安装仍报错可在java命令后追加-Djava.library.path/usr/lib显式指定动态库搜索路径java -Djava.library.path/usr/lib -jar target/taosdemo-2.0.1-jar-with-dependencies.jar \ -host hostname -database db name -doCreateTable true \ -superTableSQL create table weather(ts timestamp, f1 int) tags(t1 nchar(4)) \ -numOfTables 1000 -numOfRowsPerTable 100000000 \ -numOfThreadsForInsert 10 -numOfTablesPerSQL 10 -numOfValuesPerSQL 100其他常见问题-rate超出 0~100 会直接抛出IllegalArgumentException见 JdbcTaosdemoConfig.java请确保取值范围大量写入时若观察到连接耗尽异常优先调整application.properties中hikari.maximum-pool-size未提供-host时程序只打印帮助并退出运行前务必确认主机可达、端口放行原生 6030 / WebSocket 6041写入量极大时注意-numOfRowsPerTable、-numOfTables的乘积不要超出磁盘容量并合理设置-keep保留策略。总结从 demo 到压测的正确姿势taosdemo 的价值在于把“建库 → 建超表 → 批量建子表 → 多线程写入 → 查询验证 → 清理”的完整链路参数化。实际使用时的推荐组合验证建模与基础写入-doCreateTable true-superTableSQL自定义结构与标签配合-numOfTablesPerSQL、-numOfValuesPerSQL控制单条 SQL 规模测极限写入吞吐-doCreateTable false-autoCreateTable true用INSERT ... USING ... TAGS(...)边建边写配合加大-numOfThreadsForInsert与连接池模拟乱序数据-order 1 -rate 0-100 -range ms贴近 IIoT 中设备上报乱序的真实场景验证数据完整性写入后使用-executeSql select count(*) from db.weather快速核对影响行数与实际落库行数。若需阅读更完整的工程代码与单测示例可继续在仓库中查看 taosdemo 源码目录 与 test 目录。【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考