TDengine Java Connector
taos-jdbcdriver
是 TDengine 的官方 Java 语言连接器,Java 开发人员可以通过它开发存取 TDengine 数据库的应用软件。taos-jdbcdriver
实现了 JDBC driver 标准的接口.
info
TDengine 的 JDBC 驱动实现尽可能与关系型数据库驱动保持一致,但 TDengine 与关系对象型数据库的使用场景和技术特征存在差异,所以taos-jdbcdriver
与传统的 JDBC driver 也存在一定差异。在使用时需要 注意以下几点:
- TDengine 目前不支持针对单条数据记录的删除操作。
- 目前不支持事务操作。
连接方式
taos-jdbcdriver
主要提供三种形式的连接器。一般我们推荐使用 Websocket 连接。
- 原生连接,通过 TDengine 客户端驱动程序(taosc)原生连接 TDengine 实例,支持数据写入、查询、数据订阅、schemaless 接口和参数绑定接口等功能。
- REST 连接,通过 taosAdapter 提供的 HTTP 接口连接 TDengine 实例,不支持 schemaless 和数据订阅等特性。
- Websocket 连接,通过 taosAdapter 提供的 Websocket 接口连接 TDengine 实例,WebSocket 连接实现的功能集合和原生连接有少量不同。
连接方式的详细介绍请参考:连接器建立连接的方式
JDBC 和 JRE 兼容性
- JDBC: 支持 JDBC 4.2 版本,部分功能如无模式写入和数据订阅单独提供
- JRE: 支持 JRE 8 及以上版本
支持的平台
原生连接支持的平台和 TDengine 客户端驱动支持的平台一致。 REST 连接支持所有能运行 Java 的平台。
版本历史
taos-jdbcdriver 版本 | 主要变化 | TDengine 版本 |
---|---|---|
3.2.11 | 解决了 Native 连接关闭结果集 bug | - |
3.2.10 | 1. REST/WebSocket 连接支持传输中的数据压缩;2. Websocket 自动重连机制,默认关闭;3. Connection 类提供无模式写入的方法;4. 优化了原生连接的数据拉取性能;5. 修复了一些已知问题;6.元数据获取函数可以返回支持的函数列表。 | - |
3.2.9 | 解决了 Websocket prepareStatement 关闭 bug | - |
3.2.8 | 优化了自动提交, 解决了 websocket 手动提交 bug, 优化 Websocket prepareStatement 使用一个连接, 元数据支持视图 | - |
3.2.7 | 支持 VARBINARY 和 GEOMETRY 类型,增加 native 连接的时区设置支持。增加 websocket 自动重连功能。 | 3.2.0.0 及更高版本 |
3.2.5 | 数据订阅增加 committed()、assignment() 方法 | 3.1.0.3 及更高版本 |
3.2.4 | 数据订阅在 WebSocket 连接下增加 enable.auto.commit 参数,以及 unsubscribe() 方法。 | - |
3.2.3 | 修复 ResultSet 在一些情况数据解析失败 | - |
3.2.2 | 新增功能:数据订阅支持 seek 功能。 | 3.0.5.0 及更高版本 |
3.2.1 | 新增功能:WebSocket 连接支持 schemaless 与 prepareStatement 写入。变更:consumer poll 返回结果集为 ConsumerRecord,可通过 value() 获取指定结果集数据。 | 3.0.3.0 及更高版本 |
3.2.0 | 存在连接问题,不推荐使用 | - |
3.1.0 | WebSocket 连接支持订阅功能 | - |
3.0.1 - 3.0.4 | 修复一些情况下结果集数据解析错误的问题。3.0.1 在 JDK 11 环境编译,JDK 8 环境下建议使用其他版本 | - |
3.0.0 | 支持 TDengine 3.0 | 3.0.0.0 及更高版本 |
2.0.42 | 修复 WebSocket 连接中 wasNull 接口返回值 | - |
2.0.41 | 修复 REST 连接中用户名和密码转码方式 | - |
2.0.39 - 2.0.40 | 增加 REST 连接/请求 超时设置 | - |
2.0.38 | JDBC REST 连接增加批量拉取功能 | - |
2.0.37 | 增加对 json tag 支持 | - |
2.0.36 | 增加对 schemaless 写入支持 | - |
处理异常
在报错后,通过 SQLException 可以获取到错误的信息和错误码:
try (Statement statement = connection.createStatement()) {
// executeQuery
ResultSet tempResultSet = statement.executeQuery(sql);
// print result
printResult(tempResultSet);
} catch (SQLException e) {
System.out.println("ERROR Message: " + e.getMessage());
System.out.println("ERROR Code: " + e.getErrorCode());
e.printStackTrace();
}
JDBC 连接器可能报错的错误码包括 4 种:
- JDBC driver 本身的报错(错误码在 0x2301 到 0x2350 之间)
- 原生连接方法的报错(错误码在 0x2351 到 0x2360 之间)
- 数据订阅的报错(错误码在 0x2371 到 0x2380 之间)
- TDengine 其他功能模块的报错。
具体的错误码请参考:
Error Code | Description | Suggested Actions |
---|---|---|
0x2301 | connection already closed | 连接已经关闭,检查连接情况,或重新创建连 接去执行相关指令。 |
0x2302 | this operation is NOT supported currently! | 当前使用接口不支持,可以更换其他连接方式。 |
0x2303 | invalid variables | 参数不合法,请检查相应接口规范,调整参数类型及大小。 |
0x2304 | statement is closed | statement 已经关闭,请检查 statement 是否关闭后再次使用,或是连接是否正常。 |
0x2305 | resultSet is closed | resultSet 结果集已经释放,请检查 resultSet 是否释放后再次使用。 |
0x2306 | Batch is empty! | prepareStatement 添加参数后再执行 executeBatch。 |
0x2307 | Can not issue data manipulation statements with executeQuery() | 更新操作应该使用 executeUpdate(),而不是 executeQuery()。 |
0x2308 | Can not issue SELECT via executeUpdate() | 查询操作应该使用 executeQuery(),而不是 executeUpdate()。 |
0x230d | parameter index out of range | 参数越界,请检查参数的合理范围。 |
0x230e | connection already closed | 连接已经关闭,请检查 Connection 是否关闭后再次使用,或是连接是否正常。 |
0x230f | unknown sql type in tdengine | 请检查 TDengine 支持的 Data Type 类型。 |
0x2310 | can't register JDBC-JNI driver | 不能注册 JNI 驱动,请检查 url 是否填写正确。 |
0x2312 | url is not set | 请检查 REST 连接 url 是否填写正确。 |
0x2314 | numeric value out of range | 请检查获取结果集中数值类型是否使用了正确的接口。 |
0x2315 | unknown taos type in tdengine | 在 TDengine 数据类型与 JDBC 数据类型转换时,是否指定了正确的 TDengine 数据类型。 |
0x2317 | REST 连接中使用了错误的请求类型。 | |
0x2318 | REST 连接中出现了数据传输异常,请检查网络情况并重试。 | |
0x2319 | user is required | 创建连接时缺少用户名信息 |
0x231a | password is required | 创建连接时缺少密码信息 |
0x231c | httpEntity is null, sql: | REST 连接中执行出现异常 |
0x231d | can't create connection with server within | 通过增加参数 httpConnectTimeout 增加连接耗时,或是请检查与 taosAdapter 之间的连接情况。 |
0x231e | failed to complete the task within the specified time | 通过增加参数 messageWaitTimeout 增加执行耗时,或是请检查与 taosAdapter 之间的连接情况。 |
0x2350 | unknown error | 未知异常,请在 github 反馈给开发人员。 |
0x2352 | Unsupported encoding | 本地连接下指定了不支持的字符编码集 |
0x2353 | internal error of database, please see taoslog for more details | 本地连接执行 prepareStatement 时出现错误,请检查 taos log 进行问题定位。 |
0x2354 | JNI connection is NULL | 本地连接执行命令时,Connection 已经关闭。请检查与 TDengine 的连接情况。 |
0x2355 | JNI result set is NULL | 本地连接获取结果集,结果集异常,请检查连接情况,并重试。 |
0x2356 | invalid num of fields | 本地连接获取结果集的 meta 信息不匹配。 |
0x2357 | empty sql string | 填写正确的 SQL 进行执行。 |
0x2359 | JNI alloc memory failed, please see taoslog for more details | 本地连接分配内存错误,请检查 taos log 进行问题定位。 |
0x2371 | consumer properties must not be null! | 创建订阅时参数为空,请填写正确的参数。 |
0x2372 | configs contain empty key, failed to set consumer property | 参数 key 中包含空值,请填写正确的参数。 |
0x2373 | failed to set consumer property, | 参数 value 中包含空值,请填写正确的参数。 |
0x2375 | topic reference has been destroyed | 创建数据订阅过程中,topic 引用被释放。请检查与 TDengine 的连接情况。 |
0x2376 | failed to set consumer topic, topic name is empty | 创建数据订阅过程中,订阅 topic 名称为空。请检查指定的 topic 名称是否填写正确。 |
0x2377 | consumer reference has been destroyed | 订阅数据传输通道已经关闭,请检查与 TDengine 的连接情况。 |
0x2378 | consumer create error | 创建数据订阅失败,请根据错误信息检查 taos log 进行问题定位。 |
0x2379 | seek offset must not be a negative number | seek 接口参数不能为负值,请使用正确的参数 |
0x237a | vGroup not found in result set | VGroup 没有分配给当前 consumer,由于 Rebalance 机制导致 Consumer 与 VGroup 不是绑定的关系 |
TDengine DataType 和 Java DataType
TDengine 目前支持时间戳、数字、字符、布尔类型,与 Java 对应类型转换 如下:
TDengine DataType | JDBCType |
---|---|
TIMESTAMP | java.sql.Timestamp |
INT | java.lang.Integer |
BIGINT | java.lang.Long |
FLOAT | java.lang.Float |
DOUBLE | java.lang.Double |
SMALLINT | java.lang.Short |
TINYINT | java.lang.Byte |
BOOL | java.lang.Boolean |
BINARY | byte array |
NCHAR | java.lang.String |
JSON | java.lang.String |
VARBINARY | byte[] |
GEOMETRY | byte[] |
注意:JSON 类型仅在 tag 中支持。
由于历史原因,TDengine中的BINARY底层不是真正的二进制数据,已不建议使用。请用VARBINARY类型代替。
GEOMETRY类型是little endian字节序的二进制数据,符合WKB规范。详细信息请参考 数据类型
WKB规范请参考Well-Known Binary (WKB)
对于java连接器,可以使用jts库来方便的创建GEOMETRY类型对象,序列化后写入TDengine,这里有一个样例Geometry示例