Elgato_dark/TDengine
1
0
Fork 0
mirror of https://github.com/taosdata/TDengine synced 2026-05-24 10:09:01 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
TDengine/docs/zh/14-reference/05-connector/14-java.mdx
She Yanjie 05ba8289a5
docs: jdbc release 3.7.6 (#33293) 
* chore(jdbc): update jdbc version

* docs: jdbc release 3.7.6

* Update docs/en/14-reference/05-connector/14-java.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2025-10-17 16:24:15 +08:00

1470 lines
95 KiB
Text
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
toc_max_heading_level: 4
sidebar_label: Java
title: TDengine TSDB Java Connector
description: TDengine TSDB Java 连接器基于标准 JDBC API 实现，并提供原生连接与 WebSocket 连接两种连接器。
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import RequestId from "./_request_id.mdx";
`taos-jdbcdriver` 是 TDengine TSDB 的官方 Java 语言连接器，Java 开发人员可以通过它开发存取 TDengine TSDB 数据库的应用软件。`taos-jdbcdriver` 实现了 JDBC driver 标准的接口。
:::info
TDengine TSDB 的 JDBC 驱动实现尽可能与关系型数据库驱动保持一致，但 TDengine TSDB 与关系对象型数据库的使用场景和技术特征存在差异，所以`taos-jdbcdriver` 与传统的 JDBC driver 也存在一定差异。在使用时需要注意以下几点：
- TDengine TSDB 目前不支持针对单条数据记录的删除操作。
- 目前不支持事务操作。
:::
## JDBC 和 JRE 版本兼容性
- JDBC：支持 JDBC 4.2 及以上版本。
- JRE：支持 JRE 8 及以上版本。
## 支持的平台
- 原生连接支持的平台和 TDengine TSDB 客户端驱动支持的平台一致。
- WebSocket 连接支持所有能运行 Java 的平台。
## 版本历史
| taos-jdbcdriver 版本 | 主要变化 | TDengine TSDB 版本 |
| ------------------| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| 3.7.6 | 优化了 WebSocket 连接负载均衡实现和参数绑定 setObject 接口 | - |
| 3.7.5 | 1. WebSocket 连接支持负载均衡 <br/> 2. 自动重连支持参数绑定 <br/> 3. 优化了高效写入序列化性能 <br/> 4. 优化了 WebSocket 连接 isValid 性能 | - |
| 3.7.3 | 优化了 WebSocket 和 Native 查询实现 | - |
| 3.7.2 | 解决了 supportsBatchUpdates 问题，提升 Spring JdbcTemplate 参数绑定写入性能 | - |
| 3.7.1 | 1. 使用 Netty 替换 Java-WebSocket 库，提升小查询性能<br/> 2. 兼容 IPv6 网络协议<br/> 3. 支持 BLOB 二进制数据类型<br/> 4. 实现 TDengine 版本兼容性检查<br/> 5. 支持 `varcharAsString` 配置属性<br/> 6. 优化 WebSocket 查询内存使用效率<br/> 7. 修复 WebSocket 连接的时区问题<br/> | - |
| 3.6.3 | 解决了订阅数据库和超级表时的数据类型转换 bug | - |
| 3.6.2 | 1. 支持订阅数据库和超级表（不支持订阅元数据） <br/> 2. 解决了云服务订阅 bug <br/> 3. 优化了 setQueryTimeout 参数为 0 的实现 | - |
| 3.6.1 | 解决 WebSocket 连接在小查询上的性能 bug | - |
| 3.6.0 | 在 WebSocket 连接上支持高效写入和 Decimal 数据类型 | 3.3.6.0 及更高版本 |
| 3.5.3 | 在 WebSocket 连接上支持无符号数据类型 | - |
| 3.5.2 | 解决了 WebSocket 查询结果集释放 bug | - |
| 3.5.1 | 解决了数据订阅获取时间戳对象类型问题 | - |
| 3.5.0 | 1. 优化了 WebSocket 连接参数绑定性能，支持参数绑定查询使用二进制数据 <br/> 2. 优化了 WebSocket 连接在小查询上的性能 <br/> 3. WebSocket 连接上支持设置时区和应用信息 | 3.3.5.0 及更高版本 |
| 3.4.0 | 1. 使用 jackson 库替换 fastjson 库 <br/> 2. WebSocket 采用独立协议标识 <br/> 3. 优化后台拉取线程使用，避免用户误用导致超时 | - |
| 3.3.4 | 解决了 getInt 在数据类型为 float 报错 | - |
| 3.3.3 | 解决了 WebSocket statement 关闭导致的内存泄漏 | - |
| 3.3.2 | 1. 优化 WebSocket 连接下的参数绑定性能 <br/> 2. 优化了对 mybatis 的支持 | - |
| 3.3.0 | 1. 优化 WebSocket 连接下的数据传输性能 <br/> 2. 支持跳过 SSL 验证，默认关闭 | 3.3.2.0 及更高版本 |
| 3.2.11 | 解决了 Native 连接关闭结果集 bug | - |
| 3.2.10 | 1. REST/WebSocket 连接支持传输中的数据压缩 <br/> 2. WebSocket 自动重连机制，默认关闭 <br/> 3. Connection 类提供无模式写入的方法 <br/> 4. 优化了原生连接的数据拉取性能 <br/> 5. 修复了一些已知问题 <br/> 6.元数据获取函数可以返回支持的函数列表 | - |
| 3.2.9 | 解决了 WebSocket prepareStatement 关闭 bug | - |
| 3.2.8 | 1. 优化了自动提交 <br/> 2. 解决了 WebSocket 手动提交 bug <br/> 3.优化 WebSocket prepareStatement 使用一个连接 <br/> 4.元数据支持视图 | - |
| 3.2.7 | 1. 支持 VARBINARY 和 GEOMETRY 类型 <br/> 2. 增加 native 连接的时区设置支持 <br/> 3. 增加 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 | 1. WebSocket 连接支持 schemaless 与 prepareStatement 写入 <br/> 2. 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 TSDB 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 可以获取到错误的信息和错误码：
```java
{{#include docs/examples/java/src/main/java/com/taos/example/JdbcBasicDemo.java:jdbc_exception}}
```
错误码信息请参考 [错误码](../../../reference/error-code)
## 数据类型映射
TDengine TSDB 目前支持时间戳、数字、字符、布尔类型，与 Java 对应类型转换如下：
| TDengine TSDB DataType | JDBCType | 备注|
| ----------------- | -------------------- |-------------------- |
| TIMESTAMP | java.sql.Timestamp ||
| BOOL | java.lang.Boolean ||
| TINYINT | java.lang.Byte ||
| TINYINT UNSIGNED | java.lang.Short |仅在 WebSocket 连接方式支持|
| SMALLINT | java.lang.Short ||
| SMALLINT UNSIGNED | java.lang.Integer |仅在 WebSocket 连接方式支持|
| INT | java.lang.Integer ||
| INT UNSIGNED | java.lang.Long |仅在 WebSocket 连接方式支持|
| BIGINT | java.lang.Long ||
| BIGINT UNSIGNED | java.math.BigInteger |仅在 WebSocket 连接方式支持|
| FLOAT | java.lang.Float ||
| DOUBLE | java.lang.Double ||
| VARCHAR/BINARY | byte[] |在 WebSocket 连接上设置 `varcharAsString` 参数为 `true` 可以映射为 String 类型|
| NCHAR | java.lang.String ||
| JSON | java.lang.String |仅在 tag 中支持|
| VARBINARY | byte[] ||
| GEOMETRY | byte[] ||
| BLOB | byte[] |仅在列中支持|
| DECIMAL | java.math.BigDecimal |仅在 WebSocket 连接方式支持|
**注意**：由于历史原因，TDengine 中的 BINARY 底层不是真正的二进制数据，已不建议使用，请用 VARBINARY 类型代替。
GEOMETRY 类型是 little endian 字节序的二进制数据，符合 WKB 规范。详细信息请参考 [数据类型](../../taos-sql/datatype)
WKB 规范请参考[Well-Known Binary (WKB)](https://libgeos.org/specifications/wkb/)
对于 java 连接器，可以使用 jts 库来方便的创建 GEOMETRY 类型对象，序列化后写入 TDengine TSDB，这里有一个样例[Geometry 示例](https://github.com/taosdata/TDengine/blob/main/docs/examples/java/src/main/java/com/taos/example/GeometryDemo.java)
## 示例程序汇总
示例程序源码位于 `TDengine/docs/examples/JDBC` 下：
- JDBCDemo：JDBC 示例源程序。
- connectionPools：HikariCP, Druid, dbcp, c3p0 等连接池中使用 taos-jdbcdriver。
- SpringJdbcTemplate：Spring JdbcTemplate 中使用 taos-jdbcdriver。
- mybatisplus-demo：Springboot + Mybatis 中使用 taos-jdbcdriver。
- springbootdemo：Springboot 中使用 taos-jdbcdriver。
- consumer-demo：Consumer 消费 TDengine TSDB 数据示例，可通过参数控制消费速度。
请参考：[JDBC example](https://github.com/taosdata/TDengine/tree/main/docs/examples/JDBC)
## 常见问题
1. 使用 Statement 的 `addBatch()` 和 `executeBatch()` 来执行“批量写入/更新”，为什么没有带来性能上的提升？
**原因**：TDengine TSDB 的 JDBC 实现中，通过 `addBatch` 方法提交的 SQL 语句，会按照添加的顺序，依次执行，这种方式没有减少与服务端的交互次数，不会带来性能上的提升。
**解决方法**：1. 在一条 insert 语句中拼接多个 values 值；2. 使用多线程的方式并发插入；3. 使用参数绑定的写入方式
2. java.lang.UnsatisfiedLinkError: no taos in java.library.path
**原因**：程序没有找到依赖的本地函数库 taos。
**解决方法**：Windows 下可以将 C:\TDengine\driver\taos.dll 拷贝到 C:\Windows\System32\ 目录下，Linux 下将建立如下软链 `ln -s /usr/local/taos/driver/libtaos.so.x.x.x.x /usr/lib/libtaos.so` 即可，macOS 下需要建立软链 `ln -s /usr/local/lib/libtaos.dylib /usr/lib/libtaos.dylib`。
3. java.lang.UnsatisfiedLinkError: taos.dll Can't load AMD 64 bit on a IA 32-bit platform
**原因**：目前 TDengine TSDB 只支持 64 位 JDK。
**解决方法**：重新安装 64 位 JDK。
4. java.lang.NoSuchMethodError: setByteArray
**原因**：taos-jdbcdriver 3.\* 版本仅支持 TDengine TSDB 3.0 及以上版本。
**解决方法**：使用 taos-jdbcdriver 2.\* 版本连接 TDengine TSDB 2.\* 版本。
5. java.lang.NoSuchMethodError: java.nio.ByteBuffer.position(I)Ljava/nio/ByteBuffer; ... taos-jdbcdriver-3.0.1.jar
**原因**：taos-jdbcdriver 3.0.1 版本需要在 JDK 11+ 环境使用。
**解决方法**：更换 taos-jdbcdriver 3.0.2+ 版本。
其它问题请参考 [FAQ](../../../train-faq/faq)
## API 参考
### JDBC 驱动
taos-jdbcdriver 实现了 JDBC 标准的 Driver 接口，提供了 2 个实现类。
- WebSocket 连接使用驱动类 `com.taosdata.jdbc.ws.WebSocketDriver`。
- 原生连接使用驱动类 `com.taosdata.jdbc.TSDBDriver`。
#### URL 规范
TDengine TSDB 的 JDBC URL 规范格式为：
`jdbc:[TAOS|TAOS-WS]://[host1:port1,host2:port2,...,hostN:portN]/[database_name]?[user={user}|&password={password}|&charset={charset}|&cfgdir={config_dir}|&locale={locale}|&timezone={timezone}|&batchfetch={batchfetch}]`
- `host` 参数支持合法的域名或 IP 地址。taos-jdbcdriver 同时支持 IPv4 和 IPv6 格式。对于 IPv6 地址，必须使用中括号括起来（例如 `[::1]` 或 `[2001:db8:1234:5678::1]`），以避免端口号解析冲突。
- **仅 WebSocket 连接方式支持多个端点地址**，使用时用英文逗号隔开。多个端点地址在连接时会随机使用，以实现负载均衡。
- JDBC URL 中支持设置 Properties 中所有属性，具体请参考下文 **Properties** 章节。
**原生连接**
`jdbc:TAOS://taosdemo.com:6030/power?user=root&password=taosdata`，使用了 JDBC 原生连接的 TSDBDriver，建立了到 host 为 taosdemo.com，端口为 6030（TDengine TSDB 的默认端口），数据库名为 power 的连接。这个 URL
中指定用户名（user）为 root，密码（password）为 taosdata。
**注意**：使用 JDBC 原生连接，taos-jdbcdriver 需要依赖客户端驱动（Linux 下是 libtaos.so；Windows 下是 taos.dll；macOS 下是 libtaos.dylib）。
对于原生连接 url 中支持的常见配置参数如下（所有参数请参考 Properties 一节）：
- user：登录 TDengine TSDB 用户名，默认值 'root'。
- password：用户登录密码，默认值 'taosdata'。
- cfgdir：客户端配置文件目录路径，Linux OS 上默认值 `/etc/taos`，Windows OS 上默认值 `C:/TDengine/cfg`。
- charset：客户端使用的字符集，默认值为系统字符集。
- locale：客户端语言环境，默认值系统当前 locale。
- timezone：客户端使用的时区，默认值为系统当前时区。
- batchErrorIgnore：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败将继续执行下面的 SQL。false：不再执行失败 SQL 后的任何语句。默认值为：false。
JDBC 原生连接的使用请参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1955.html)。
**使用 TDengine TSDB 客户端驱动配置文件建立连接**
当使用 JDBC 原生连接连接 TDengine TSDB 集群时，可以使用 TDengine TSDB 客户端驱动配置文件，在配置文件中指定集群的 firstEp、secondEp 等参数。此时在 JDBC url 中不指定 `host` 和 `port`。
配置如 `jdbc:TAOS://:/power?user=root&password=taosdata`。
在 TDengine TSDB 客户端驱动配置文件中指定 firstEp 和 secondEp，jdbc 会使用客户端的配置文件，建立连接。当集群中 firstEp 节点失效时，JDBC 会尝试使用 secondEp 连接集群。
TDengine TSDB 中，只要保证 firstEp 和 secondEp 中一个节点有效，就可以正常建立到集群的连接。
> **注意**：这里的配置文件指的是调用 JDBC Connector 的应用程序所在机器上的配置文件，Linux OS 上默认值 /etc/taos/taos.cfg，Windows OS 上默认值 C://TDengine/cfg/taos.cfg。
**WebSocket 连接**
使用 JDBC WebSocket 连接，不需要依赖客户端驱动。这是一个示例： `jdbc:TAOS-WS://taosdemo.com:6041,taosdemo2.com:6041/power?user=root&password=taosdata&varcharAsString=true`。与 JDBC 原生连接相比，仅需要：
1. driverClass 指定为“com.taosdata.jdbc.ws.WebSocketDriver”；
2. jdbcUrl 以“jdbc:TAOS-WS://”开头；
3. 使用 6041 作为连接端口。
4. 支持配置多个端点，连接时随机选择实现负载均衡。
对于 WebSocket 连接，url 中的常见配置参数如下（所有参数请参考 Properties 一节）：
- user：登录 TDengine TSDB 用户名，默认值 'root'。
- password：用户登录密码，默认值 'taosdata'。
- batchErrorIgnore：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 SQL 了。false：不再执行失败 SQL 后的任何语句。默认值为：false。
- httpConnectTimeout：连接超时时间，单位 ms，默认值为 60000。
- messageWaitTimeout：消息超时时间，单位 ms，默认值为 60000。
- useSSL：连接中是否使用 SSL。
- timezone：客户端使用的时区，连接上生效，默认值为系统时区。推荐不设置，使用系统时区性能更好。
- varcharAsString：将 VARCHAR/BINARY 类型映射为 String，仅在使用 WebSocket 连接时生效。默认值为 false。
- connmode：BI模式，仅在 WebSocket 连接时生效，默认 0，可设置为 1。为 1 代表开启 BI 模式，元数据信息不统计子表，主要用在 BI 工具对接场景。
**注意**：部分配置项（比如：locale、charset）在 WebSocket 连接中不生效。WebSocket 连接仅支持 UTF-8 字符集。
#### Properties
除了通过指定的 URL 获取连接，还可以使用 Properties 指定建立连接时的参数。
所有 Properties 配置参数同样可以在 JDBC URL 中指定，方括号中的参数名可以用于 JDBC URL(如 TSDBDriver.PROPERTY_KEY_USER[`user`]，可以在 JDBC URL 中使用 `user=root` 来设置用户名)。
> **注意**：应用中设置的 client parameter 为进程级别的，即如果要更新 client 的参数，需要重启应用。这是因为 client parameter 是全局参数，仅在应用程序的第一次设置生效。
properties 中的配置参数如下：
- TSDBDriver.PROPERTY_KEY_USER [`user`]：登录 TDengine TSDB 用户名，默认值 'root'。
- TSDBDriver.PROPERTY_KEY_PASSWORD [`password`]：用户登录密码，默认值 'taosdata'。
- TSDBDriver.PROPERTY_KEY_BATCH_ERROR_IGNORE [`batchErrorIgnore`]：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 sq 了。false：不再执行失败 SQL 后的任何语句。默认值为：false。
- TSDBDriver.PROPERTY_KEY_CONFIG_DIR [`cfgdir`]：仅在使用 JDBC 原生连接时生效。客户端配置文件目录路径，Linux OS 上默认值 `/etc/taos`，Windows OS 上默认值 `C:/TDengine/cfg`。
- TSDBDriver.PROPERTY_KEY_CHARSET [`charset`]：客户端使用的字符集，默认值为系统字符集。
- TSDBDriver.PROPERTY_KEY_LOCALE [`locale`]：仅在使用 JDBC 原生连接时生效。客户端语言环境，默认值系统当前 locale。
- TSDBDriver.PROPERTY_KEY_TIME_ZONE [`timezone`]：
- 原生连接：客户端使用的时区，默认值为系统当前时区，全局生效。因为历史的原因，我们只支持 POSIX 标准的部分规范，如 UTC-8(代表中国上上海), GMT-8，Asia/Shanghai 这几种形式。
- WebSocket 连接：客户端使用的时区，连接上生效，默认值为系统时区。仅支持 IANA 时区，即 Asia/Shanghai 这种形式。推荐不设置，使用系统时区性能更好。
- TSDBDriver.PROPERTY_KEY_MESSAGE_WAIT_TIMEOUT [`messageWaitTimeout`]：消息超时时间，单位 ms，默认值为 60000。仅 WebSocket 连接下有效。
- TSDBDriver.PROPERTY_KEY_USE_SSL [`useSSL`]：连接中是否使用 SSL。仅在 WebSocket 连接时生效。
- TSDBDriver.PROPERTY_KEY_ENABLE_COMPRESSION [`enableCompression`]：传输过程是否启用压缩。仅在使用 WebSocket 连接时生效。true：启用，false：不启用。默认为 false。
- TSDBDriver.PROPERTY_KEY_ENABLE_AUTO_RECONNECT [`enableAutoReconnect`]：是否启用自动重连。仅在使用 WebSocket 连接时生效。true：启用，false：不启用。默认为 false。
> **注意**：启用自动重连对获取结果集无效。自动重连仅对连接建立时通过参数指定数据库有效，对后面的 `use db` 语句切换数据库无效。
- TSDBDriver.PROPERTY_KEY_RECONNECT_INTERVAL_MS [`reconnectIntervalMs`]：自动重连重试间隔，单位毫秒，默认值 2000。仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。
- TSDBDriver.PROPERTY_KEY_RECONNECT_RETRY_COUNT [`reconnectRetryCount`]：自动重连重试次数，默认值 3，仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。
- TSDBDriver.PROPERTY_KEY_DISABLE_SSL_CERT_VALIDATION [`disableSSLCertValidation`]：关闭 SSL 证书验证。仅在使用 WebSocket 连接时生效。true：启用，false：不启用。默认为 false。
- TSDBDriver.PROPERTY_KEY_CONNECT_MODE [`conmode`]：BI模式，仅在 WebSocket 连接时生效，默认 0，可设置为 1。为 1 代表开启 BI 模式，元数据信息不统计子表，主要用在 BI 工具对接场景。
- TSDBDriver.PROPERTY_KEY_VARCHAR_AS_STRING [`varcharAsString`]：将 VARCHAR/BINARY 类型映射为 String，仅在使用 WebSocket 连接时生效。默认值为 false。
- TSDBDriver.PROPERTY_KEY_APP_NAME [`app_name`]：App 名称，可用于 `show connections` 查询结果显示。仅在使用 WebSocket 连接时生效。默认值为 java。
- TSDBDriver.PROPERTY_KEY_APP_IP [`app_ip`]：App IP，可用于 `show connections` 查询结果显示。仅在使用 WebSocket 连接时生效。默认值为空。
- TSDBDriver.PROPERTY_KEY_WS_KEEP_ALIVE_SECONDS [`wsKeepAlive`]：WebSocket 连接有效时间，单位秒，有效时间内调用 isValid 会直接返回上次结果。默认值为 300。
- TSDBDriver.PROPERTY_KEY_ASYNC_WRITE [`asyncWrite`]：高效写入模式，目前仅支持 `stmt` 方式。仅在使用 WebSocket 连接时生效。默认值为空，即不启用高效写入模式。
- TSDBDriver.PROPERTY_KEY_BACKEND_WRITE_THREAD_NUM [`backendWriteThreadNum`]：高效写入模式下，后台写入线程数。仅在使用 WebSocket 连接时生效。默认值为 10。
- TSDBDriver.PROPERTY_KEY_BATCH_SIZE_BY_ROW [`batchSizeByRow`]：高效写入模式下，写入数据的批大小，单位是行。仅在使用 WebSocket 连接时生效。默认值为 1000。
- TSDBDriver.PROPERTY_KEY_CACHE_SIZE_BY_ROW [`cacheSizeByRow`]：高效写入模式下，缓存的大小，单位是行。仅在使用 WebSocket 连接时生效。默认值为 10000。
- TSDBDriver.PROPERTY_KEY_COPY_DATA [`copyData`]：高效写入模式下，是否拷贝应用通过 addBatch 传入的二进制类型数据。仅在使用 WebSocket 连接时生效。默认值为 false。
- TSDBDriver.PROPERTY_KEY_STRICT_CHECK [`strictCheck`]：高效写入模式下，是否校验表名长度和变长数据类型长度。仅在使用 WebSocket 连接时生效。默认值为 false。
- TSDBDriver.PROPERTY_KEY_RETRY_TIMES [`retryTimes`]：高效写入模式下，写入失败重试次数。仅在使用 WebSocket 连接时生效。默认值为 3。
- TSDBDriver.PROPERTY_KEY_PBS_MODE [`pbsMode`]：参数绑定序列化模式，目前是实验特性，仅支持 `line` 模式，在参数绑定一批绑定的数据中每个子表仅一条数据时可以提升性能。仅在使用 WebSocket 连接时生效，不支持高效写入模式。默认值为空。
**配置参数的优先级**
通过前面三种方式获取连接，如果配置参数在 url、Properties、客户端配置文件中有重复，则参数的`优先级由高到低`分别如下：
1. JDBC URL 参数，如上所述，可以在 JDBC URL 的参数中指定。
2. Properties connProps
3. 使用原生连接时，TDengine TSDB 客户端驱动的配置文件 taos.cfg
例如：在 url 中指定了 password 为 taosdata，在 Properties 中指定了 password 为 taosdemo，那么，JDBC 会使用 url 中的 password 建立连接。
#### 接口说明
- `Connection connect(String url, java.util.Properties info) throws SQLException`
- **接口说明**：连接 TDengine TSDB 数据库。
- **参数说明**：
- `url`：连接地址 url，详见上文 URL 规范。
- `info`：连接属性，详见上文 Properties 章节。
- **返回值**：连接对象。
- **异常**：连接失败抛出 `SQLException` 异常。
- `boolean acceptsURL(String url) throws SQLException`
- **接口说明**：判断驱动是否支持 url。
- **参数说明**：
- `url`：连接地址 url。
- **返回值**：`true`：支持，`false`：不支持。
- **异常**：url 非法抛出 `SQLException` 异常。
- `DriverPropertyInfo[] getPropertyInfo(String url, java.util.Properties info) throws SQLException`
- **接口说明**：获取尝试连接数据库时可能需要的所有属性的详细信息。这些属性信息被封装在 DriverPropertyInfo 对象数组中返回。每个 DriverPropertyInfo 对象包含了一个数据库连接属性的详细信息，比如属性名、属性值、描述等。
- **参数说明**：
- `url`：一个 String 类型的参数，表示数据库的 URL。
- `info`：一个 java.util.Properties 类型的参数，包含了尝试连接时用户可能提供的属性列表。
- **返回值**：返回值类型为 `DriverPropertyInfo[]`，即 `DriverPropertyInfo` 对象的数组。每个 `DriverPropertyInfo` 对象包含了一个特定的数据库连接属性的详细信息。
- **异常**：如果在获取属性信息的过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `int getMajorVersion()`
- **接口说明**：获取 JDBC 驱动程序的主版本号。
- `int getMinorVersion()`
- **接口说明**：获取 JDBC 驱动程序的次版本号。
### 数据库元数据
`DatabaseMetaData` 是 JDBC API 的一部分，它提供了关于数据库的元数据的详细信息，元数据意味着关于数据库数据的数据。通过 `DatabaseMetaData` 接口，可以查询数据库服务器的详细信息，比如数据库产品名称、版本、已安装的功能、表、视图、存储过程的列表等。这对于了解和适应不同数据库的特性非常有用。
- `String getURL() throws SQLException`
- **接口说明**：获取用于连接数据库的 URL。
- **返回值**：连接数据库的 URL。
- **异常**：获取失败将抛出 `SQLException` 异常。
- `String getUserName() throws SQLException`
- **接口说明**：获取用于连接获取数据库的用户名。
- **返回值**：连接数据库的用户名。
- **异常**：获取失败将抛出 `SQLException` 异常。
- `String getDriverName() throws SQLException`
- **接口说明**：获取 JDBC 驱动程序的名称。
- **返回值**：驱动名称字符串。
- **异常**：获取失败将抛出 `SQLException` 异常。
- `String getDriverVersion() throws SQLException`
- **接口说明**：获取 JDBC 驱动版本。
- **返回值**：驱动版本字符串。
- **异常**：获取失败将抛出 `SQLException` 异常。
- `int getDriverMajorVersion()`
- **接口说明**：获取 JDBC 驱动主版本号。
- `int getDriverMinorVersion()`
- **接口说明**：获取 JDBC 驱动次版本号。
- `String getDatabaseProductName() throws SQLException`
- **接口说明**：获取数据库产品的名称。
- `String getDatabaseProductVersion() throws SQLException`
- **接口说明**：获取数据库产品的版本号。
- `String getIdentifierQuoteString() throws SQLException`
- **接口说明**：获取用于引用 SQL 标识符的字符串。
- `String getSQLKeywords() throws SQLException`
- **接口说明**：获取数据库特有的 SQL 关键字列表。
- `String getNumericFunctions() throws SQLException`
- **接口说明**：获取数据库支持的数值函数名称列表。
- `String getStringFunctions() throws SQLException`
- **接口说明**：获取数据库支持的字符串函数名称列表。
- `String getSystemFunctions() throws SQLException`
- **接口说明**：获取数据库支持的系统函数名称列表。
- `String getTimeDateFunctions() throws SQLException`
- **接口说明**：获取数据库支持的时间日期函数名称列表。
- `String getCatalogTerm() throws SQLException`
- **接口说明**：获取数据库中目录的术语。
- `String getCatalogSeparator() throws SQLException`
- **接口说明**：获取用于分隔目录和表名的分隔符。
- `int getDefaultTransactionIsolation() throws SQLException`
- **接口说明**：获取数据库的默认事务隔离级别。
- `boolean supportsTransactionIsolationLevel(int level) throws SQLException`
- **接口说明**：判断数据库是否支持给定的事务隔离级别。
- **参数说明**：
- `level`：事务隔离级别。
- **返回值**：`true`：支持，`false`：不支持。
- **异常**：操作失败抛出 `SQLException` 异常。
- `ResultSet getTables(String catalog, String schemaPattern, String tableNamePattern, String[] types) throws SQLException`
- **接口说明**：获取数据库中匹配指定模式的表信息。
- **参数说明**：
- `catalog`：目录名称；`null` 表示不指定目录。
- `schemaPattern`：模式名称的模式；null 表示不指定模式。
- `tableNamePattern`：表名称的模式。
- `types`：表类型列表，返回指定类型的表。
- **返回值**：包含表信息的 `ResultSet`。
- **异常**：操作失败抛出 `SQLException` 异常。
- `ResultSet getCatalogs() throws SQLException`
- **接口说明**：获取数据库中所有目录的信息。
- **返回值**：包含目录信息的 `ResultSet`。
- **异常**：操作失败抛出 `SQLException` 异常。
- `ResultSet getTableTypes() throws SQLException`
- **接口说明**：获取数据库支持的表类型。
- **返回值**：包含表类型的 `ResultSet`。
- **异常**：操作失败抛出 `SQLException` 异常。
- `ResultSet getColumns(String catalog, String schemaPattern, String tableNamePattern, String columnNamePattern) throws SQLException`
- **接口说明**：获取指定表中匹配指定模式的列信息。
- **参数说明**：
- `catalog`：目录名称；`null` 表示不指定目录。
- `schemaPattern`：模式名称的模式；`null` 表示不指定模式。
- `tableNamePattern`：表名称的模式。
- `columnNamePattern`：列名称的模式。
- **返回值**：包含列信息的 `ResultSet`。
- **异常**：操作失败抛出 `SQLException` 异常。
- `ResultSet getPrimaryKeys(String catalog, String schema, String table) throws SQLException`
- **接口说明**：获取指定表的主键信息。
- **参数说明**：
- `catalog`：目录名称；`null` 表示不指定目录。
- `schema`：模式名称；`null` 表示不指定模式。
- `table`：表名称。
- **返回值**：包含主键信息的 `ResultSet`。
- **异常**：操作失败抛出 `SQLException` 异常。
- `Connection getConnection() throws SQLException`
- **接口说明**：获取数据库连接。
- **返回值**：数据库连接 `Connection` 对象。
- **异常**：获取连接失败抛出 `SQLException` 异常。
- `ResultSet getSuperTables(String catalog, String schemaPattern, String tableNamePattern) throws SQLException`
- **接口说明**：获取指定表的父表信息。
- **参数说明**：
- `catalog`：目录名称；`null` 表示不指定目录。
- `schemaPattern`：模式名称的模式；`null` 表示不指定模式。
- `tableNamePattern`：表名称的模式。
- **返回值**：包含父表信息的 `ResultSet`。
- **异常**：操作失败抛出 `SQLException` 异常。
- `boolean supportsResultSetHoldability(int holdability) throws SQLException`
- **接口说明**：判断数据库是否支持给定的 `ResultSet` 持有性。
- **参数说明**：
- `holdability`：`ResultSet` 的持有性。
- **返回值**：`true`：支持，`false`：不支持。
- **异常**：操作失败抛出 `SQLException` 异常。
- `int getSQLStateType() throws SQLException`
- **接口说明**：获取数据库使用的 SQLSTATE 类型。
- **返回值**：SQLSTATE 类型代码。
- **异常**：操作失败抛出 `SQLException` 异常。
支持类接口返回 `true` 的接口列表，其余返回 `false` 的接口不再赘述。
| 接口方法 | 说明 |
|--------------------------------------------|--------------------------------------------|
| `boolean nullsAreSortedAtStart()` | 判断 `NULL` 值是否被排序在前 |
| `boolean storesLowerCaseIdentifiers()` | 判断数据库是否将标识符存储为小写 |
| `boolean supportsAlterTableWithAddColumn()` | 判断数据库是否支持使用 `ALTER TABLE` 添加列 |
| `boolean supportsAlterTableWithDropColumn()` | 判断数据库是否支持使用 `ALTER TABLE` 删除列 |
| `boolean supportsColumnAliasing()` | 判断数据库是否支持列别名 |
| `boolean supportsGroupBy()` | 判断数据库是否支持 `GROUP BY` 语句 |
| `boolean isCatalogAtStart()` | 判断在数据库中目录名是否出现在完全限定名的开头 |
| `boolean supportsCatalogsInDataManipulation()` | 判断数据库在数据操作语句中是否支持目录名 |
### 连接功能
JDBC 驱动支持创建连接，返回支持 JDBC 标准的 `Connection` 接口的对象，还提供了 `AbstractConnection` 接口，扩充了一些无模式写入接口。
#### 标准接口
- `Statement createStatement() throws SQLException`
- **接口说明**：创建一个 `Statement` 对象来执行 SQL 语句。`Statement` 接口详细说明见下文`执行 SQL`。
- **返回值**：创建的 `Statement` 对象。
- **异常**：操作失败抛出 `SQLException` 异常。
- `PreparedStatement prepareStatement(String sql) throws SQLException`
- **接口说明**：创建一个 `PreparedStatement` 对象来执行给定的 SQL 语句，`PreparedStatement` 接口详细说明见下文`执行 SQL`。
- **参数说明**：
- `sql`：预编译的 SQL 语句。
- **返回值**：创建的 `PreparedStatement` 对象。
- **异常**：操作失败抛出 `SQLException` 异常。
- `String nativeSQL(String sql) throws SQLException`
- **接口说明**：将 SQL 语句转换为数据库特定的 SQL 语法。
- **参数说明**：
- `sql`：要转换的 SQL 语句。
- **返回值**：转换后的 SQL 语句。
- **异常**：操作失败抛出 `SQLException` 异常。
- `void close() throws SQLException`
- **接口说明**：关闭数据库连接。
- **异常**：操作失败抛出 `SQLException` 异常。
- `boolean isClosed() throws SQLException`
- **接口说明**：判断数据库连接是否已关闭。
- **返回值**：`true`：已关闭，`false`：未关闭。
- **异常**：操作失败抛出 `SQLException` 异常。
- `DatabaseMetaData getMetaData() throws SQLException`
- **接口说明**：获取数据库的元数据。
- **返回值**：数据库的元数据。
- **异常**：操作失败抛出 `SQLException` 异常。
- `void setCatalog(String catalog) throws SQLException`
- **接口说明**：设置当前连接的默认数据库。
- **参数说明**：
- `catalog`：要设置的数据库名称。
- **异常**：操作失败抛出 `SQLException` 异常。
- `String getCatalog() throws SQLException`
- **接口说明**：获取当前连接的默认数据库。
- **返回值**：当前连接的目录名称。
- **异常**：操作失败抛出 `SQLException` 异常。
- `Statement createStatement(int resultSetType, int resultSetConcurrency) throws SQLException`
- **接口说明**：创建一个 `Statement` 对象，指定 `ResultSet` 类型和并发模式。
- **参数说明**：
- `resultSetType`：`ResultSet` 类型。
- `resultSetConcurrency`：并发模式。
- **返回值**：创建的 `Statement` 对象。
- **异常**：操作失败抛出 `SQLException` 异常。
- `Statement createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException`
- **接口说明**：创建一个 `Statement` 对象，指定 `ResultSet` 类型、并发模式和持有性。
- **参数说明**：
- `resultSetType`：`ResultSet` 类型。
- `resultSetConcurrency`：并发模式。
- `resultSetHoldability`：持有性。
- **返回值**：创建的 `Statement` 对象。
- **异常**：操作失败抛出 `SQLException` 异常。
- `PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency) throws SQLException`
- **接口说明**：创建一个 `PreparedStatement` 对象，指定 SQL、`ResultSet` 类型和并发模式。
- **参数说明**：
- `sql`：预编译的 SQL 语句。
- `resultSetType`：`ResultSet` 类型。
- `resultSetConcurrency`：并发模式。
- **返回值**：创建的 `PreparedStatement` 对象。
- **异常**：操作失败抛出 `SQLException` 异常。
- `PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException`
- **接口说明**：创建一个 `PreparedStatement` 对象，指定 SQL、`ResultSet` 类型、并发模式和持有性。
- **参数说明**：
- `sql`：预编译的 SQL 语句。
- `resultSetType`：`ResultSet` 类型。
- `resultSetConcurrency`：并发模式。
- `resultSetHoldability`：持有性。
- **返回值**：创建的 `PreparedStatement` 对象。
- **异常**：操作失败抛出 `SQLException` 异常。
- `PreparedStatement prepareStatement(String sql, int autoGeneratedKeys) throws SQLException`
- **接口说明**：创建一个 `PreparedStatement` 对象，指定 SQL 语句和自动生成键的标志。
- **参数说明**：
- `sql`：预编译的 SQL 语句。
- `autoGeneratedKeys`：指示是否应生成自动键的标志。
- **返回值**：创建的 `PreparedStatement` 对象。
- **异常**：操作失败抛出 `SQLException` 异常。
- `void setHoldability(int holdability) throws SQLException`
- **接口说明**：设置 `ResultSet` 对象的默认持有性。
- **参数说明**：
- `holdability`：`ResultSet` 的持有性。
- **异常**：操作失败抛出 `SQLException` 异常。
- `int getHoldability() throws SQLException`
- **接口说明**：获取 `ResultSet` 对象的默认持有性。
- **返回值**：`ResultSet` 的持有性。
- **异常**：操作失败抛出 `SQLException` 异常。
- `boolean isValid(int timeout) throws SQLException`
- **接口说明**：检测数据库连接是否有效。
- **参数说明**：
- `timeout`：等待有效性检查的超时时间，单位秒。
- **返回值**：`true`：连接有效，`false`：连接无效。
- **异常**：操作失败抛出 `SQLException` 异常。
- `void setClientInfo(String name, String value) throws SQLClientInfoException`
- **接口说明**：设置客户端信息属性。
- **参数说明**：
- `name`：属性名。
- `value`：属性值。
- **异常**：设置失败抛出 `SQLClientInfoException` 异常。
- `void setClientInfo(Properties properties) throws SQLClientInfoException`
- **接口说明**：设置一组客户端信息属性。
- **参数说明**：
- `properties`：属性集合。
- **异常**：设置失败抛出 `SQLClientInfoException` 异常。
- `String getClientInfo(String name) throws SQLException`
- **接口说明**：获取指定的客户端信息属性值。
- **参数说明**：
- `name`：属性名。
- **返回值**：属性值。
- **异常**：操作失败抛出 `SQLException` 异常。
- `Properties getClientInfo() throws SQLException`
- **接口说明**：获取所有客户端信息属性。
- **返回值**：包含所有客户端信息属性的 `Properties` 对象。
- **异常**：操作失败抛出 `SQLException` 异常。
#### 无模式写入
注：下面 abstract 类型接口会被具体实现类实现，因此建立连接后得到连接对象可以直接调用。
- `abstract void write(String[] lines, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType, Integer ttl, Long reqId) throws SQLException`
- **接口说明**：以指定的协议类型、时间戳类型、TTL（生存时间）和请求 ID 写入多行数据。
- **参数说明**：
- `lines`：待写入的数据行数组。
- `protocolType`：协议类型：支持 InfluxDB `LINE`，OpenTSDB `TELNET`，OpenTSDB `JSON` 三种。
- `timestampType`：时间戳类型，支持 HOURS，MINUTES，SECONDS，MILLI_SECONDS，MICRO_SECONDS 和 NANO_SECONDS。
- `ttl`：数据的生存时间，单位天。
- `reqId`：请求 ID。
- **异常**：操作失败抛出 SQLException 异常。
- `void write(String[] lines, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType) throws SQLException`
- **接口说明**：以指定的协议类型和时间戳类型写入多行数据。
- **参数说明**：
- `lines`：待写入的数据行数组。
- `protocolType`：协议类型：支持 InfluxDB `LINE`，OpenTSDB `TELNET`，OpenTSDB `JSON` 三种。
- `timestampType`：时间戳类型，支持 HOURS，MINUTES，SECONDS，MILLI_SECONDS，MICRO_SECONDS 和 NANO_SECONDS。
- **异常**：操作失败抛出 SQLException 异常。
- `void write(String line, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType) throws SQLException`
- **接口说明**：以指定的协议类型和时间戳类型写入单行数据。
- **参数说明**：
- `line`：待写入的数据行。
- `protocolType`：协议类型：支持 InfluxDB `LINE`，OpenTSDB `TELNET`，OpenTSDB `JSON` 三种。
- `timestampType`：时间戳类型，支持 HOURS，MINUTES，SECONDS，MILLI_SECONDS，MICRO_SECONDS 和 NANO_SECONDS。
- **异常**：操作失败抛出 SQLException 异常。
- `void write(List<String> lines, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType) throws SQLException`
- **接口说明**：以指定的协议类型和时间戳类型写入多行数据（使用列表）。
- **参数说明**：
- `lines`：待写入的数据行列表。
- `protocolType`：协议类型：支持 InfluxDB `LINE`，OpenTSDB `TELNET`，OpenTSDB `JSON` 三种。
- `timestampType`：时间戳类型，支持 HOURS，MINUTES，SECONDS，MILLI_SECONDS，MICRO_SECONDS 和 NANO_SECONDS。
- **异常**：操作失败抛出 SQLException 异常。
- `int writeRaw(String line, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType) throws SQLException`
- **接口说明**：以指定的协议类型和时间戳类型写入多行回车符分割的原始数据，回车符分割，并返回操作结果。
- **参数说明**：
- `line`：待写入的原始数据。
- `protocolType`：协议类型：支持 InfluxDB `LINE`，OpenTSDB `TELNET`，OpenTSDB `JSON` 三种。
- `timestampType`：时间戳类型，支持 HOURS，MINUTES，SECONDS，MILLI_SECONDS，MICRO_SECONDS 和 NANO_SECONDS。
- **返回值**：操作结果。
- **异常**：操作失败抛出 SQLException 异常。
- `abstract int writeRaw(String line, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType, Integer ttl, Long reqId) throws SQLException`
- **接口说明**：以指定的协议类型、时间戳类型、TTL（生存时间）和请求 ID 写入多行回车符分割的原始数据，并返回操作结果。
- **参数说明**：
- `line`：待写入的原始数据。
- `protocolType`：协议类型：支持 InfluxDB `LINE`，OpenTSDB `TELNET`，OpenTSDB `JSON` 三种。
- `timestampType`：时间戳类型，支持 HOURS，MINUTES，SECONDS，MILLI_SECONDS，MICRO_SECONDS 和 NANO_SECONDS。
- `ttl`：数据的生存时间，单位天。
- `reqId`：请求 ID。
- **返回值**：操作结果。
- **异常**：操作失败抛出 SQLException 异常。
### 执行 SQL
JDBC 驱动提供了符合 JDBC 标准的 `Statement` 接口，支持以下功能：
1. **执行 SQL 语句**：`Statement` 接口主要用于执行静态 SQL 语句，并返回其生成的结果对象。
2. **查询执行**：可以执行返回数据集的查询（`SELECT` 语句）。
3. **更新执行**：可以执行影响行数的 SQL 语句，如 `INSERT`、`UPDATE`、`DELETE` 等。
4. **批量执行**：支持批量执行多个 SQL 语句，以提高应用程序运行效率。
5. **获取结果**：可以获取查询执行后返回的结果集（`ResultSet` 对象），并遍历查询返回的数据。
6. **获取更新计数**：对于非查询 SQL 语句，可以获取执行后影响的行数。
7. **关闭资源**：提供了关闭 `Statement` 对象的方法，以释放数据库资源。
另外 JDBC 驱动还提供了用于请求链路跟踪的扩展接口。
#### 标准接口
- `ResultSet executeQuery(String sql) throws SQLException`
- **接口说明**：执行给定的 SQL 语句，该语句返回单个 `ResultSet` 对象。
- **参数说明**：
- `sql`：要执行的 SQL 查询语句。
- **返回值**：查询结果集 `ResultSet`。
- **异常**：执行查询过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `int executeUpdate(String sql) throws SQLException`
- **接口说明**：执行给定的 SQL 语句，可以是 `INSERT` 或 `DELETE` 语句，或不返回任何内容的 SQL 语句。
- **参数说明**：
- `sql`：要执行的 SQL 更新语句。
- **返回值**：受影响的行数。
- **异常**：执行更新过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `void close() throws SQLException`
- **接口说明**：立即释放此 `Statement` 对象的数据库和 JDBC 资源。
- **异常**：关闭过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `int getMaxFieldSize() throws SQLException`
- **接口说明**：获取可以在 `ResultSet` 对象中读取的最大字符和二进制列值的字节数。
- **返回值**：最大列大小。
- **异常**：获取过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `int getQueryTimeout() throws SQLException`
- **接口说明**：获取当前 `Statement` 对象的查询超时时间。
- **返回值**：查询超时时间（以秒为单位）。
- **异常**：获取过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `void setQueryTimeout(int seconds) throws SQLException`
- **接口说明**：设置当前 `Statement` 对象的查询超时时间。
- **参数说明**：
- `seconds`：查询超时时间（以秒为单位）。
- **异常**：设置过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `boolean execute(String sql) throws SQLException`
- **接口说明**：执行给定的 SQL 语句，该语句可能返回多个结果。
- **参数说明**：
- `sql`：要执行的 SQL 语句。
- **返回值**：`true` 表示返回的是 `ResultSet` 对象；`false` 表示返回的是更新计数或没有结果。
- **异常**：执行过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `ResultSet getResultSet() throws SQLException`
- **接口说明**：获取当前 `Statement` 对象生成的 `ResultSet` 对象。
- **返回值**：当前 `Statement` 对象生成的结果集。
- **异常**：获取过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `int getUpdateCount() throws SQLException`
- **接口说明**：获取当前 `Statement` 对象执行的更新计数。
- **返回值**：受影响的行数；如果当前结果是 `ResultSet` 对象或没有结果，则返回 -1。
- **异常**：获取过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `boolean getMoreResults() throws SQLException`
- **接口说明**：移动到当前 `Statement` 对象的下一个结果，检查它是否为 `ResultSet` 对象。
- **返回值**：`true` 表示下一个结果是 `ResultSet` 对象；`false` 表示下一个结果是更新计数或没有更多结果。
- **异常**：移动过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `int getFetchDirection() throws SQLException`
- **接口说明**：获取 `Statement` 对象从数据库中获取行的方向。
- **返回值**：获取行的方向，TDengine TSDB 只支持 `FETCH_FORWARD` 方向。
- **异常**：获取过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `void setFetchSize(int rows) throws SQLException`
- **接口说明**：提示 JDBC 驱动程序每次从数据库中获取多少行。
- **参数说明**：
- `rows`：每次获取的行数。
- **异常**：设置过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `int getFetchSize() throws SQLException`
- **接口说明**：获取 `Statement` 对象的默认获取大小。
- **返回值**：默认的获取大小。
- **异常**：获取过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `int getResultSetConcurrency() throws SQLException`
- **接口说明**：获取 `ResultSet` 对象的并发模式。
- **返回值**：`ResultSet` 对象的并发模式。
- **异常**：获取过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `int getResultSetType() throws SQLException`
- **接口说明**：获取 `ResultSet` 对象的类型。
- **返回值**：`ResultSet` 对象的类型。
- **异常**：获取过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `void addBatch(String sql) throws SQLException`
- **接口说明**：将给定的 SQL 语句添加到当前 `Statement` 对象的批处理中。
- **参数说明**：
- `sql`：要添加到批处理中的 SQL 语句。
- **异常**：添加过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `void clearBatch() throws SQLException`
- **接口说明**：清空当前 `Statement` 对象的批处理。
- **异常**：清空过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `int[] executeBatch() throws SQLException`
- **接口说明**：执行批处理中的所有 SQL 语句。
- **返回值**：批处理中每个 SQL 语句影响的行数。
- **异常**：执行过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `Connection getConnection() throws SQLException`
- **接口说明**：获取产生此 `Statement` 对象的 `Connection` 对象。
- **返回值**：产生此 `Statement` 对象的数据库连接。
- **异常**：获取过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `int getResultSetHoldability() throws SQLException`
- **接口说明**：获取 `ResultSet` 对象的可保持性。
- **返回值**：`ResultSet` 对象的可保持性。
- **异常**：获取过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
- `boolean isClosed() throws SQLException`
- **接口说明**：检查此 `Statement` 对象是否已关闭。
- **返回值**：`true` 表示此 `Statement` 对象已关闭；`false` 表示未关闭。
- **异常**：检查过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。
#### 扩展接口
扩展接口主要用于请求链路跟踪。
- `ResultSet executeQuery(String sql, Long reqId) throws SQLException`
- **接口说明**：执行给定的 SQL 查询语句
- **参数说明**：
- `sql`：要执行的 SQL 查询语句
- `reqId`：请求 id
- **返回值**：包含查询结果的 `ResultSet` 对象
- **异常**：执行查询失败抛出 `SQLException` 异常
- `int executeUpdate(String sql, Long reqId) throws SQLException`
- **接口说明**：执行给定的 SQL 更新语句
- **参数说明**：
- `sql`：要执行的 SQL 更新语句
- `reqId`：请求 id
- **返回值**：表示受影响的行数
- **异常**：执行更新失败抛出 `SQLException` 异常
- `boolean execute(String sql, Long reqId) throws SQLException`
- **接口说明**：执行给定的 SQL 语句，该语句可能是 INSERT、UPDATE、DELETE 或者 DDL 语句
- **参数说明**：
- `sql`：要执行的 SQL 语句
- `reqId`：请求 id
- **返回值**：如果第一个结果是 `ResultSet` 对象，则返回 `true`；如果是更新计数或者没有结果，则返回 `false`
- **异常**：执行语句失败抛出 `SQLException` 异常
### 结果获取
JDBC 驱动支持标准的 ResultSet 接口，以及对应的结果集元数据 ResultSetMetaData 接口，提供了用于读取结果集中元数据和数据的方法。
#### 结果集
JDBC 驱动支持标准的 ResultSet 接口，提供了用于读取结果集中元数据和数据的方法。
- `ResultSetMetaData getMetaData() throws SQLException`
- **接口说明**：获取此 ResultSet 对象的列的数量、类型和属性。
- **返回值**：此 ResultSet 对象的数据的 ResultSetMetaData 对象。
- **异常**：如果发生数据库访问错误，将抛出 SQLException 异常。
- `boolean next() throws SQLException`
- **接口说明**：将游标从当前位置向前移动一行。用于遍历查询结果集。
- **返回值**：如果新的当前行有效，则返回 true；如果结果集中没有更多行，则返回 false。
- **异常**：如果发生数据库访问错误，将抛出 SQLException 异常。
- `void close() throws SQLException`
- **接口说明**：立即释放此 ResultSet 对象的数据库和 JDBC 资源，而不是等待该对象自动关闭时的资源释放。
- **异常**：如果发生数据库访问错误，将抛出 SQLException 异常。
- `boolean wasNull() throws SQLException`
- **接口说明**：报告上一次读取的列值是否为 NULL。
- **返回值**：如果上一次读取的列值是 NULL，则返回 true；否则返回 false。
- **异常**：如果发生数据库访问错误，将抛出 SQLException 异常。
- `String getString(int columnIndex) throws SQLException`
- **接口说明**：以 Java String 的形式获取指定列的值。
- **参数说明**：
- `columnIndex`：列的编号，第一列是 1，第二列是 2，以此类推。
- **返回值**：返回指定列的值；如果值是 NULL，则返回 null。
- **异常**：如果发生数据库访问错误，将抛出 SQLException 异常。
- `boolean getBoolean(int columnIndex) throws SQLException`
- **接口说明**：获取指定列的值作为 Java boolean。
- **参数说明**：
- `columnIndex`：列的编号。
- **返回值**：如果指定列的值为 true，则返回 true；如果值为 false 或 NULL，则返回 false。
- **异常**：如果发生数据库访问错误，将抛出 SQLException 异常。
- `byte getByte(int columnIndex) throws SQLException`
- **接口说明**：以 Java byte 的形式获取指定列的值。
- **参数说明**：
- `columnIndex`：列的编号。
- **返回值**：返回指定列的值；如果值是 NULL，则返回 0。
- **异常**：如果发生数据库访问错误，将抛出 SQLException 异常。
- `short getShort(int columnIndex) throws SQLException`
- **接口说明**：以 Java short 的形式获取指定列的值。
- **参数说明**：
- `columnIndex`：列的编号。
- **返回值**：返回指定列的值；如果值是 NULL，则返回 0。
- **异常**：如果发生数据库访问错误，将抛出 SQLException 异常。
- `int getInt(int columnIndex) throws SQLException`
- **接口说明**：以 Java int 的形式获取指定列的值。
- **参数说明**：
- `columnIndex`：列的编号。
- **返回值**：返回指定列的值；如果值是 NULL，则返回 0。
- **异常**：如果发生数据库访问错误，将抛出 SQLException 异常。
- `long getLong(int columnIndex) throws SQLException`
- **接口说明**：以 Java long 的形式获取指定列的值。
- **参数说明**：
- `columnIndex`：列的编号。
- **返回值**：返回指定列的值；如果值是 NULL，则返回 0L。
- **异常**：如果发生数据库访问错误，将抛出 SQLException 异常。
- `float getFloat(int columnIndex) throws SQLException`
- **接口说明**：以 Java float 的形式获取指定列的值。
- **参数说明**：
- `columnIndex`：列的编号。
- **返回值**：返回指定列的值；如果值是 NULL，则返回 0.0f。
- **异常**：如果发生数据库访问错误，将抛出 SQLException 异常。
- `double getDouble(int columnIndex) throws SQLException`
- **接口说明**：以 Java double 的形式获取指定列的值。
- **参数说明**：
- `columnIndex`：列的编号。
- **返回值**：返回指定列的值；如果值是 NULL，则返回 0.0d。
- **异常**：如果发生数据库访问错误，将抛出 SQLException 异常。
- `byte[] getBytes(int columnIndex) throws SQLException`
- **接口说明**：以字节数组的形式获取指定列的值。
- **参数说明**：
- `columnIndex`：列的编号。
- **返回值**：返回指定列的值作为字节数组；如果值是 NULL，则返回 null。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `Date getDate(int columnIndex) throws SQLException`
- **接口说明**：获取指定列的值作为 `java.sql.Date` 对象。
- **参数说明**：
- `columnIndex`：列的编号。
- **返回值**：返回指定列的日期值；如果值是 NULL，则返回 null。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `Time getTime(int columnIndex) throws SQLException`
- **接口说明**：获取指定列的值作为 `java.sql.Time` 对象。
- **参数说明**：
- `columnIndex`：列的编号。
- **返回值**：返回指定列的时间值；如果值是 NULL，则返回 null。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `Timestamp getTimestamp(int columnIndex) throws SQLException`
- **接口说明**：以 `java.sql.Timestamp` 的形式获取指定列的值。
- **参数说明**：
- `columnIndex`：列的编号。
- **返回值**：返回指定列的时间戳值；如果值是 NULL，则返回 null。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `String getNString(int columnIndex) throws SQLException`
- **接口说明**：获取指定列的值作为 Java String。此方法用于读取 NCHAR、NVARCHAR 和 LONGNVARCHAR 类型的列，以支持国际化字符集。
- **参数说明**：
- `columnIndex`：要获取其值的列的编号（从 1 开始）。
- **返回值**：指定列的值；如果值是 NULL，则返回 null。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `Object getObject(int columnIndex) throws SQLException`
- **接口说明**：以 Java Object 的形式获取指定列的值。
- **参数说明**：
- `columnIndex`：列的编号。
- **返回值**：返回指定列的值；如果值是 NULL，则返回 null。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `String getString(String columnLabel) throws SQLException`
- **接口说明**：以 Java String 的形式获取指定列名的值。
- **参数说明**：
- `columnLabel`：列的标签名。
- **返回值**：返回指定列名的值；如果值是 NULL，则返回 null。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `boolean getBoolean(String columnLabel) throws SQLException`
- **接口说明**：获取指定列名的值作为 Java boolean。
- **参数说明**：
- `columnLabel`：列的标签名。
- **返回值**：如果指定列名的值为 true，则返回 true；如果值为 false 或 NULL，则返回 false。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `byte getByte(String columnLabel) throws SQLException`
- **接口说明**：以 Java byte 的形式获取指定列名的值。
- **参数说明**：
- `columnLabel`：列的标签名。
- **返回值**：返回指定列名的值；如果值是 NULL，则返回 0。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `short getShort(String columnLabel) throws SQLException`
- **接口说明**：以 Java short 的形式获取指定列名的值。
- **参数说明**：
- `columnLabel`：列的标签名。
- **返回值**：返回指定列名的值；如果值是 NULL，则返回 0。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `int getInt(String columnLabel) throws SQLException`
- **接口说明**：以 Java int 的形式获取指定列名的值。
- **参数说明**：
- `columnLabel`：列的标签名。
- **返回值**：返回指定列名的值；如果值是 NULL，则返回 0。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `long getLong(String columnLabel) throws SQLException`
- **接口说明**：以 Java long 的形式获取指定列名的值。
- **参数说明**：
- `columnLabel`：列的标签名。
- **返回值**：返回指定列名的值；如果值是 NULL，则返回 0L。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `float getFloat(String columnLabel) throws SQLException`
- **接口说明**：以 Java float 的形式获取指定列名的值。
- **参数说明**：
- `columnLabel`：列的标签名。
- **返回值**：返回指定列名的值；如果值是 NULL，则返回 0.0f。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `double getDouble(String columnLabel) throws SQLException`
- **接口说明**：以 Java double 的形式获取指定列名的值。
- **参数说明**：
- `columnLabel`：列的标签名。
- **返回值**：返回指定列名的值；如果值是 NULL，则返回 0.0d。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `byte[] getBytes(String columnLabel) throws SQLException`
- **接口说明**：以字节数组的形式获取指定列名的值。
- **参数说明**：
- `columnLabel`：列的标签名。
- **返回值**：返回指定列名的值作为字节数组；如果值是 NULL，则返回 null。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `Date getDate(String columnLabel) throws SQLException`
- **接口说明**：获取指定列名的值作为 `java.sql.Date` 对象。
- **参数说明**：
- `columnLabel`：列的标签名。
- **返回值**：返回指定列名的日期值；如果值是 NULL，则返回 null。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `Time getTime(String columnLabel) throws SQLException`
- **接口说明**：获取指定列名的值作为 `java.sql.Time` 对象。
- **参数说明**：
- `columnLabel`：列的标签名。
- **返回值**：返回指定列名的时间值；如果值是 NULL，则返回 null。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `Timestamp getTimestamp(String columnLabel) throws SQLException`
- **接口说明**：以 `java.sql.Timestamp` 的形式获取指定列名的值。
- **参数说明**：
- `columnLabel`：列的标签名。
- **返回值**：返回指定列名的时间戳值；如果值是 NULL，则返回 null。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `String getNString(String columnLabel) throws SQLException`
- **接口说明**：获取指定列名的值作为 Java String。此方法用于读取 NCHAR、NVARCHAR 和 LONGNVARCHAR 类型的列，以支持国际化字符集。
- **参数说明**：
- `columnLabel`：要获取其值的列的标签名。
- **返回值**：指定列名的值；如果值是 NULL，则返回 null。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `Object getObject(String columnLabel) throws SQLException`
- **接口说明**：以 Java Object 的形式获取指定列名的值。
- **参数说明**：
- `columnLabel`：列的标签名。
- **返回值**：返回指定列名的值；如果值是 NULL，则返回 null。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `int findColumn(String columnLabel) throws SQLException`
- **接口说明**：获取给定列名的列编号。
- **参数说明**：
- `columnLabel`：列的标签名。
- **返回值**：给定列名的列编号。
- **异常**：如果列名不存在或发生数据库访问错误，将抛出 `SQLException` 异常。
- `boolean isBeforeFirst() throws SQLException`
- **接口说明**：判断游标是否在第一行之前。
- **返回值**：如果游标在第一行之前，则返回 true；否则返回 false。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `boolean isAfterLast() throws SQLException`
- **接口说明**：判断游标是否在最后一行之后。
- **返回值**：如果游标在最后一行之后，则返回 true；否则返回 false。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `boolean isFirst() throws SQLException`
- **接口说明**：判断游标是否在第一行。
- **返回值**：如果游标在第一行，则返回 true；否则返回 false。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `boolean isLast() throws SQLException`
- **接口说明**：判断游标是否在最后一行。
- **返回值**：如果游标在最后一行，则返回 true；否则返回 false。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `int getRow() throws SQLException`
- **接口说明**：获取当前游标所在行的行号。
- **返回值**：当前游标所在行的行号；如果游标在结果集外，则返回 0。
- **异常**：如果发生数据库访问错误，将抛出 `SQLException` 异常。
- `void setFetchSize(int rows) throws SQLException`
- **接口说明**：设置数据库返回结果集的行数大小。此方法用于指导数据库驱动程序每次从数据库服务器获取的行数，以减少通信次数或限制内存使用。
- **参数说明**：
- `rows`：指定的获取行数大小。如果设置为 0，则表示使用驱动程序的默认值。
- **异常**：如果结果集已关闭 或 rows 参数小于 0，将抛出 `SQLException` 异常。
- `int getFetchSize() throws SQLException`
- **接口说明**：获取当前结果集的 fetch size。
- **返回值**：当前结果集的 fetch size。
- **异常**：如果结果集已关闭，将抛出 `SQLException` 异常。
- `int getType() throws SQLException`
- **接口说明**：获取 `ResultSet` 的类型。
- **返回值**：`ResultSet` 的类型。总是返回 `ResultSet.TYPE_FORWARD_ONLY`，表示结果集的游标只能向前移动。
- **异常**：如果结果集已关闭，将抛出 `SQLException` 异常。
- `int getConcurrency() throws SQLException`
- **接口说明**：获取 `ResultSet` 的并发模式。
- **返回值**：`ResultSet` 的并发模式。总是返回 `ResultSet.CONCUR_READ_ONLY`，表示结果集不能被更新。
- **异常**：如果结果集已关闭，将抛出 `SQLException` 异常。
- `<T> T getObject(String columnLabel, Class<T> type) throws SQLException`
- **接口说明**：根据列标签和返回类型的 Class 对象，获取指定列的值。这允许用户以更灵活的方式，根据需要将列值直接转换为相应的类型。
- **参数说明**：
- `columnLabel`：要获取其值的列的标签名。
- `type`：期望返回值的 Java 类型的 Class 对象。
- **返回值**：指定列的值，以指定的类型返回；如果值是 NULL，则返回 null。
- **异常**：如果发生数据库访问错误，或者指定的类型转换不支持，将抛出 `SQLException` 异常。
#### 结果集元数据
`ResultSetMetaData` 提供了获取结果集元数据的接口。`ResultSetMetaData` 类型的对象通过 `ResultSet` 类型对象的 `getMetaData` 接口获取。
- `int getColumnCount() throws SQLException`
- **接口说明**：获取结果集中列的总数。
- **返回值**：结果集中列的数量。
- `boolean isSearchable(int column) throws SQLException`
- **接口说明**：判断指定列是否可以用于 WHERE 子句中。
- **参数说明**：
- `column`：列的编号（从 1 开始）。
- **返回值**：如果指定列可以用于搜索，则返回 true；否则返回 false。
- `int isNullable(int column) throws SQLException`
- **接口说明**：判断指定列的值是否可以为 null。
- **参数说明**：
- `column`：列的编号（从 1 开始）。
- **返回值**：列值是否可为 null 的情况，会返回 `ResultSetMetaData.columnNoNulls`、`ResultSetMetaData.columnNullable` 或 `ResultSetMetaData.columnNullableUnknown`。
- `boolean isSigned(int column) throws SQLException`
- **接口说明**：判断指定列的值是否为有符号数。
- **参数说明**：
- `column`：列的编号（从 1 开始）。
- **返回值**：如果列值为有符号数，则返回 true；否则返回 false。
- `int getColumnDisplaySize(int column) throws SQLException`
- **接口说明**：获取指定列的最大标准宽度，以字符为单位。
- **参数说明**：
- `column`：列的编号（从 1 开始）。
- **返回值**：列的最大宽度。
- **异常**：如果列索引超出范围，将抛出 `SQLException` 异常。
- `String getColumnLabel(int column) throws SQLException`
- **接口说明**：获取指定列的建议标题，用于打印输出和显示用途。
- **参数说明**：
- `column`：列的编号（从 1 开始）。
- **返回值**：列的建议标题。
- **异常**：如果列索引超出范围，将抛出 `SQLException` 异常。
- `String getColumnName(int column) throws SQLException`
- **接口说明**：获取指定列的名称。
- **参数说明**：
- `column`：列的编号（从 1 开始）。
- **返回值**：列的名称。
- **异常**：如果列索引超出范围，将抛出 `SQLException` 异常。
- `int getPrecision(int column) throws SQLException`
- **接口说明**：获取指定列的最大精度。
- **参数说明**：
- `column`：列的编号（从 1 开始）。
- **返回值**：列的最大精度。
- **异常**：如果列索引超出范围，将抛出 `SQLException` 异常。
- `int getScale(int column) throws SQLException`
- **接口说明**：获取指定列的小数点右侧的位数。
- **参数说明**：
- `column`：列的编号（从 1 开始）。
- **返回值**：列的小数位数。
- **异常**：如果列索引超出范围，将抛出 `SQLException` 异常。
- `String getTableName(int column) throws SQLException`
- **接口说明**：获取指定列所在的表名。
- **参数说明**：
- `column`：列的编号（从 1 开始）。
- **返回值**：列所在的表名。
- `String getCatalogName(int column) throws SQLException`
- **接口说明**：获取指定列所在的数据库名。
- **参数说明**：
- `column`：列的编号（从 1 开始）。
- **返回值**：列所在数据库名。
- `int getColumnType(int column) throws SQLException`
- **接口说明**：获取指定列的 SQL 类型。
- **参数说明**：
- `column`：列的编号（从 1 开始）。
- **返回值**：SQL 类型，来自 `java.sql.Types`。
- `String getColumnTypeName(int column) throws SQLException`
- **接口说明**：获取指定列的数据库特定的类型名称。
- **参数说明**：
- `column`：列的编号（从 1 开始）。
- **返回值**：数据库特定的类型名称。
- `boolean isReadOnly(int column) throws SQLException`
- **接口说明**：判断指定列是否为只读。
- **参数说明**：
- `column`：列的编号（从 1 开始）。
- **返回值**：如果列为只读，则返回 true；否则返回 false。
- `String getColumnClassName(int column) throws SQLException`
- **接口说明**：获取指定列的 Java 类名。
- **参数说明**：
- `column`：列的编号（从 1 开始）。
- **返回值**：列值在 Java 中对应的类名。
### 参数绑定
PreparedStatement 允许使用预编译的 SQL 语句，这可以提高性能并提供参数化查询的能力，从而增加安全性。
JDBC 驱动提供了实现 PreparedStatement 接口的两个类：
1. 对应原生连接的 TSDBPreparedStatement
2. 对应 WebSocket 连接的 TSWSPreparedStatement
因 JDBC 标准没有高性能绑定数据的接口，TSDBPreparedStatement 和 TSWSPreparedStatement 都新增了一些方法，用来扩展参数绑定能力。
> **注意**：由于 PreparedStatement 继承了 Statement 接口，因此对于这部分重复的接口不再赘述，请参考 Statement 接口中对应描述。
#### 标准接口
- `void setNull(int parameterIndex, int sqlType) throws SQLException`
- **接口说明**：设置指定参数的 SQL 类型为 NULL。
- **参数说明**：
- `parameterIndex`：一个 int 类型的参数，表示预编译语句中的参数索引位置。
- `sqlType`：一个 int 类型的参数，表示要设置为 NULL 的 SQL 类型。
- **异常**：如果发生数据库访问错误，将抛出 SQLException 异常。
- `void setBoolean(int parameterIndex, boolean x) throws SQLException`
- **接口说明**：设置指定参数的值为一个 Java boolean。
- **参数说明**：
- `parameterIndex`：一个 int 类型的参数，表示预编译语句中的参数索引位置。
- `x`：一个 boolean 类型的参数，表示要设置的值。
- **异常**：如果发生数据库访问错误，将抛出 SQLException 异常。
- 下面接口除了要设置的值类型不同外，其余同 setBoolean，不再赘述：
- `void setByte(int parameterIndex, byte x) throws SQLException`
- `void setShort(int parameterIndex, short x) throws SQLException`
- `void setInt(int parameterIndex, int x) throws SQLException`
- `void setLong(int parameterIndex, long x) throws SQLException`
- `void setFloat(int parameterIndex, float x) throws SQLException`
- `void setDouble(int parameterIndex, double x) throws SQLException`
- `void setBigDecimal(int parameterIndex, BigDecimal x) throws SQLException`
- `void setString(int parameterIndex, String x) throws SQLException`
- `void setBytes(int parameterIndex, byte[] x) throws SQLException`
- `void setDate(int parameterIndex, Date x) throws SQLException`
- `void setTime(int parameterIndex, Time x) throws SQLException`
- `void setTimestamp(int parameterIndex, Timestamp x) throws SQLException`
- `void clearParameters() throws SQLException`
- **接口说明**：清除当前所有已设置的参数值。
- **异常**：如果预编译语句已关闭，将抛出 SQLException 异常。
- `void setObject(int parameterIndex, Object x, int targetSqlType) throws SQLException`
- **接口说明**：使用给定对象设置指定参数的值，对象的类型由 targetSqlType 指定。
- **参数说明**：
- `parameterIndex`：一个 int 类型的参数，表示预编译语句中的参数索引位置。
- `x`：一个 Object 类型的参数，表示要设置的值。
- `targetSqlType`：一个 int 类型的参数，表示 x 参数的 SQL 类型。
- **异常**：如果预编译语句已关闭，将抛出 SQLException 异常。
- `void setObject(int parameterIndex, Object x) throws SQLException`
- **接口说明**：使用给定对象设置指定参数的值，对象的类型由对象本身决定。
- **参数说明**：
- `parameterIndex`：一个 int 类型的参数，表示预编译语句中的参数索引位置。
- `x`：一个 Object 类型的参数，表示要设置的值。
- **异常**：如果预编译语句已关闭或者参数索引超出范围，将抛出 SQLException 异常。
- `ResultSetMetaData getMetaData() throws SQLException`
- **接口说明**：获取与此 PreparedStatement 对象生成的 ResultSet 对象相关的元数据。
- **返回值**：如果此 PreparedStatement 对象尚未执行任何生成 ResultSet 对象的操作，则返回 null；否则，返回此 ResultSet 对象的元数据。
- **异常**：如果发生数据库访问错误，将抛出 SQLException 异常。
- `ParameterMetaData getParameterMetaData() throws SQLException`
- **接口说明**：获取此 PreparedStatement 对象中每个参数的类型和属性信息。ParameterMetaData 说明见下文 参数元数据 章节。
- **返回值**：此 PreparedStatement 对象的参数的元数据。
- **异常**：如果预编译语句已关闭，将抛出 SQLException 异常。
#### 参数元数据
ParameterMetaData 提供了参数元数据接口：
- `int getParameterCount() throws SQLException`
- **接口说明**：获取预编译语句中参数的数量。
- **返回值**：参数的数量，类型为 `int`。
- **异常**：如果在获取参数数量的过程中发生错误，将抛出 `SQLException` 异常。
- `boolean isSigned(int param) throws SQLException`
- **接口说明**：判断指定参数是否为有符号数。
- **参数说明**：
- `param`：参数的索引，类型为 `int`。
- **返回值**：如果参数为有符号数，则返回 `true`；否则返回 `false`。
- **异常**：如果在判断过程中发生错误，将抛出 `SQLException` 异常。
- `int getPrecision(int param) throws SQLException`
- **接口说明**：获取指定参数的精度。
- **参数说明**：
- `param`：参数的索引，类型为 `int`。
- **返回值**：参数的精度，类型为 `int`。
- **异常**：如果在获取精度的过程中发生错误，将抛出 `SQLException` 异常。
- `int getScale(int param) throws SQLException`
- **接口说明**：获取指定参数的小数位数。
- **参数说明**：
- `param`：参数的索引，类型为 `int`。
- **返回值**：参数的小数位数，类型为 `int`。
- **异常**：如果在获取小数位数的过程中发生错误，将抛出 `SQLException` 异常。
- `int getParameterType(int param) throws SQLException`
- **接口说明**：获取指定参数的 SQL 类型。
- **参数说明**：
- `param`：参数的索引，类型为 `int`。
- **返回值**：参数的 SQL 类型，类型为 `int`。
- **异常**：如果在获取 SQL 类型的过程中发生错误，将抛出 `SQLException` 异常。
- `String getParameterTypeName(int param) throws SQLException`
- **接口说明**：获取指定参数的 SQL 类型名称。
- **参数说明**：
- `param`：参数的索引，类型为 `int`。
- **返回值**：参数的 SQL 类型名称，类型为 `String`。
- **异常**：如果在获取 SQL 类型名称的过程中发生错误，将抛出 `SQLException` 异常。
- `String getParameterClassName(int param) throws SQLException`
- **接口说明**：获取指定参数的 Java 类型名称。
- **参数说明**：
- `param`：参数的索引，类型为 `int`。
- **返回值**：参数的 Java 类型名称，类型为 `String`。
- **异常**：如果在获取 Java 类型名称的过程中发生错误，将抛出 `SQLException` 异常。
- `int getParameterMode(int param) throws SQLException`
- **接口说明**：获取指定参数的模式（例如，IN、OUT、INOUT）。
- **参数说明**：
- `param`：参数的索引，类型为 `int`。
- **返回值**：参数的模式，类型为 `int`。
- **异常**：如果在获取参数模式的过程中发生错误，将抛出 `SQLException` 异常。
#### 扩展接口
- `void setTableName(String name) throws SQLException`
- **接口说明**：设置当前操作的表名。
- **参数说明**：
- `name`：一个 String 类型的参数，表示要绑定的表名。
- `void setTagNull(int index, int type)`
- **接口说明**：为指定索引的标签设置 null 值。
- **参数说明**：
- `index`：标签的索引位置。
- `type`：标签的数据类型。
- `void setTagBoolean(int index, boolean value)`
- **接口说明**：为指定索引的标签设置布尔值。
- **参数说明**：
- `index`：标签的索引位置。
- `value`：要设置的布尔值。
- 下面接口除了要设置的值类型不同外，其余同 setTagBoolean，不再赘述：
- `void setTagInt(int index, int value)`
- `void setTagByte(int index, byte value)`
- `void setTagShort(int index, short value)`
- `void setTagLong(int index, long value)`
- `void setTagTimestamp(int index, long value)`
- `void setTagFloat(int index, float value)`
- `void setTagDouble(int index, double value)`
- `void setTagString(int index, String value)`
- `void setTagNString(int index, String value)`
- `void setTagJson(int index, String value)`
- `void setTagVarbinary(int index, byte[] value)`
- `void setTagGeometry(int index, byte[] value)`
- `void setInt(int columnIndex, ArrayList<Integer> list) throws SQLException`
- **接口说明**：为指定列索引设置批量整型值。
- **参数说明**：
- `columnIndex`：列的索引位置。
- `list`：包含整型值的列表。
- **异常**：
- 如果操作过程中发生错误，将抛出 SQLException 异常。
- 下面接口除了要设置的值类型不同外，其余同 setInt：
- `void setFloat(int columnIndex, ArrayList<Float> list) throws SQLException`
- `void setTimestamp(int columnIndex, ArrayList<Long> list) throws SQLException`
- `void setLong(int columnIndex, ArrayList<Long> list) throws SQLException`
- `void setDouble(int columnIndex, ArrayList<Double> list) throws SQLException`
- `void setBoolean(int columnIndex, ArrayList<Boolean> list) throws SQLException`
- `void setByte(int columnIndex, ArrayList<Byte> list) throws SQLException`
- `void setShort(int columnIndex, ArrayList<Short> list) throws SQLException`
- `void setString(int columnIndex, ArrayList<String> list, int size) throws SQLException`
- **接口说明**：为指定列索引设置字符串值列表。
- **参数说明**：
- `columnIndex`：列的索引位置。
- `list`：包含字符串值的列表。
- `size`：所有字符串的最大长度，一般为建表语句的限制值。
- **异常**：
- 如果操作过程中发生错误，将抛出 SQLException 异常。
- 下面接口除了要设置的值类型不同外，其余同 setString：
- `void setVarbinary(int columnIndex, ArrayList<byte[]> list, int size) throws SQLException`
- `void setGeometry(int columnIndex, ArrayList<byte[]> list, int size) throws SQLException`
- `void setNString(int columnIndex, ArrayList<String> list, int size) throws SQLException`
- `void columnDataAddBatch() throws SQLException`
- **接口说明**：将 `setInt（int columnIndex， ArrayList<Integer> list）` 等数组形式接口设置的数据添加到当前 PrepareStatement 对象的批处理中。
- **异常**：
- 如果操作过程中发生错误，将抛出 SQLException 异常。
- `void columnDataExecuteBatch() throws SQLException`
- **接口说明**：执行当前 PrepareStatement 对象的批处理操作。
- **异常**：如果操作过程中发生错误，将抛出 SQLException 异常。
### 数据订阅
JDBC 标准不支持数据订阅，因此本章所有接口都是扩展接口。TaosConsumer 类提供了消费者相关接口，ConsumerRecord 提供了消费记录相关接口，TopicPartition 和 OffsetAndMetadata 提供了分区信息以及偏移量元数据接口。最后 ReferenceDeserializer 和 MapDeserializer 提供了反序列化的支持。
#### 消费者
- `TaosConsumer(Properties properties) throws SQLException`
- **接口说明**：消费者构造函数
- **参数说明**：
- `properties`：一组属性，详细支持的属性见下文。
- **返回值**：消费者对象
- **异常**：如果创建失败，抛出 SQLException 异常。
创建消费者支持属性列表：
- td.connect.type：连接方式。jni：表示使用动态库连接的方式，ws/WebSocket：表示使用 WebSocket 进行数据通信。默认为 jni 方式。
- bootstrap.servers：
1. 如果使用 WebSocket 连接，则为 taosAdapter 所在的`ip:port`。支持多个端点，逗号分割，如 `ip1:port1,ip2:port2`，若 poll 过程中连接断开可以切换到其他节点（需设置自动重连参数 `TSDBDriver.PROPERTY_KEY_ENABLE_AUTO_RECONNECT` 为 `true`）。
2. 如果使用 Native 连接，则为 TDengine TSDB 服务端所在的`ip:port`，Native 连接不支持多个端点。
- enable.auto.commit：是否允许自动提交。
- group.id：consumer：所在的 group。
- value.deserializer：结果集反序列化方法，可以继承 `com.taosdata.jdbc.tmq.ReferenceDeserializer`，并指定结果集 bean，实现反序列化。也可以继承 `com.taosdata.jdbc.tmq.Deserializer`，根据 SQL 的 resultSet 自定义反序列化方式。如果订阅数据库，需要在创建消费者时设置 `value.deserializer` 为 `com.taosdata.jdbc.tmq.MapEnhanceDeserializer`，然后创建 `TaosConsumer<TMQEnhMap>` 类型的消费者。这样每行数据就可以反序列化为表名和一个 `Map`。
- httpConnectTimeout：创建连接超时参数，单位 ms，默认为 5000 ms。仅在 WebSocket 连接下有效。
- messageWaitTimeout：数据传输超时参数，单位 ms，默认为 10000 ms。仅在 WebSocket 连接下有效。
- httpPoolSize：同一个连接下最大并行请求数。仅在 WebSocket 连接下有效。
- TSDBDriver.PROPERTY_KEY_ENABLE_COMPRESSION：传输过程是否启用压缩。仅在使用 WebSocket 连接时生效。true：启用，false：不启用。默认为 false。
- TSDBDriver.PROPERTY_KEY_ENABLE_AUTO_RECONNECT：是否启用自动重连。仅在使用 WebSocket 连接时生效。true：启用，false：不启用。默认为 false。
- TSDBDriver.PROPERTY_KEY_RECONNECT_INTERVAL_MS：自动重连重试间隔，单位毫秒，默认值 2000。仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。
- TSDBDriver.PROPERTY_KEY_RECONNECT_RETRY_COUNT：自动重连重试次数，默认值 3，仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。
其他参数请参考：[Consumer 参数列表](../../../develop/tmq/#创建参数)，注意 TDengine TSDB 服务端自 3.2.0.0 版本开始消息订阅中的 auto.offset.reset 默认值发生变化。
- `void subscribe(Collection<String> topics) throws SQLException`
- **接口说明**：订阅一组主题。
- **参数说明**：
- `topics`：一个 `Collection<String>` 类型的参数，表示要订阅的主题列表。
- **异常**：如果在订阅过程中发生错误，将抛出 SQLException 异常。
- `void unsubscribe() throws SQLException`
- **接口说明**：取消订阅所有主题。
- **异常**：如果在取消订阅过程中发生错误，将抛出 SQLException 异常。
- `Set<String> subscription() throws SQLException`
- **接口说明**：获取当前订阅的所有主题。
- **返回值**：返回值类型为 `Set<String>`，即当前订阅的所有主题集合。
- **异常**：如果在获取订阅信息过程中发生错误，将抛出 SQLException 异常。
- `ConsumerRecords<V> poll(Duration timeout) throws SQLException`
- **接口说明**：轮询消息。
- **参数说明**：
- `timeout`：一个 `Duration` 类型的参数，表示轮询的超时时间。
- **返回值**：返回值类型为 `ConsumerRecords<V>`，即轮询到的消息记录。
- **异常**：如果在轮询过程中发生错误，将抛出 SQLException 异常。
- `void commitAsync() throws SQLException`
- **接口说明**：异步提交当前处理的消息的偏移量。
- **异常**：如果在提交过程中发生错误，将抛出 SQLException 异常。
- `void commitSync() throws SQLException`
- **接口说明**：同步提交当前处理的消息的偏移量。
- **异常**：如果在提交过程中发生错误，将抛出 SQLException 异常。
- `void close() throws SQLException`
- **接口说明**：关闭消费者，释放资源。
- **异常**：如果在关闭过程中发生错误，将抛出 SQLException 异常。
- `void seek(TopicPartition partition, long offset) throws SQLException`
- **接口说明**：将给定分区的偏移量设置到指定的位置。
- **参数说明**：
- `partition`：一个 `TopicPartition` 类型的参数，表示要操作的分区。
- `offset`：一个 `long` 类型的参数，表示要设置的偏移量。
- **异常**：如果在设置偏移量过程中发生错误，将抛出 SQLException 异常。
- `long position(TopicPartition tp) throws SQLException`
- **接口说明**：获取给定分区当前的偏移量。
- **参数说明**：
- `tp`：一个 `TopicPartition` 类型的参数，表示要查询的分区。
- **返回值**：返回值类型为 `long`，即给定分区当前的偏移量。
- **异常**：如果在获取偏移量过程中发生错误，将抛出 SQLException 异常。
- `Map<TopicPartition, Long> beginningOffsets(String topic) throws SQLException`
- **接口说明**：获取指定主题的每个分区的最早偏移量。
- **参数说明**：
- `topic`：一个 `String` 类型的参数，表示要查询的主题。
- **返回值**：返回值类型为 `Map<TopicPartition, Long>`，即指定主题的每个分区的最早偏移量。
- **异常**：如果在获取最早偏移量过程中发生错误，将抛出 SQLException 异常。
- `Map<TopicPartition, Long> endOffsets(String topic) throws SQLException`
- **接口说明**：获取指定主题的每个分区的最新偏移量。
- **参数说明**：
- `topic`：一个 `String` 类型的参数，表示要查询的主题。
- **返回值**：返回值类型为 `Map<TopicPartition, Long>`，即指定主题的每个分区的最新偏移量。
- **异常**：如果在获取最新偏移量过程中发生错误，将抛出 SQLException 异常。
- `void seekToBeginning(Collection<TopicPartition> partitions) throws SQLException`
- **接口说明**：将一组分区的偏移量设置到最早的偏移量。
- **参数说明**：
- `partitions`：一个 `Collection<TopicPartition>` 类型的参数，表示要操作的分区集合。
- **异常**：如果在设置偏移量过程中发生错误，将抛出 SQLException 异常。
- `void seekToEnd(Collection<TopicPartition> partitions) throws SQLException`
- **接口说明**：将一组分区的偏移量设置到最新的偏移量。
- **参数说明**：
- `partitions`：一个 `Collection<TopicPartition>` 类型的参数，表示要操作的分区集合。
- **异常**：如果在设置偏移量过程中发生错误，将抛出 SQLException 异常。
- `Set<TopicPartition> assignment() throws SQLException`
- **接口说明**：获取消费者当前分配的所有分区。
- **返回值**：返回值类型为 `Set<TopicPartition>`，即消费者当前分配的所有分区。
- **异常**：如果在获取分配的分区过程中发生错误，将抛出 SQLException 异常。
- `OffsetAndMetadata committed(TopicPartition partition) throws SQLException`
- **接口说明**：获取指定分区最后提交的偏移量。
- **参数说明**：
- `partition`：一个 `TopicPartition` 类型的参数，表示要查询的分区。
- **返回值**：返回值类型为 `OffsetAndMetadata`，即指定分区最后提交的偏移量。
- **异常**：如果在获取提交的偏移量过程中发生错误，将抛出 SQLException 异常。
- `Map<TopicPartition, OffsetAndMetadata> committed(Set<TopicPartition> partitions) throws SQLException`
- **接口说明**：获取一组分区最后提交的偏移量。
- **参数说明**：
- `partitions`：一个 `Set<TopicPartition>` 类型的参数，表示要查询的分区集合。
- **返回值**：返回值类型为 `Map<TopicPartition, OffsetAndMetadata>`，即一组分区最后提交的偏移量。
- **异常**：如果在获取提交的偏移量过程中发生错误，将抛出 SQLException 异常。
#### 消费记录
ConsumerRecords 类提供了消费记录信息，可以迭代 ConsumerRecord 对象。
ConsumerRecord 提供的接口：
- `String getTopic()`
- **接口说明**：获取消息的主题。
- **返回值**：返回值类型为 `String`，即消息的主题。
- `String getDbName()`
- **接口说明**：获取数据库名称。
- **返回值**：返回值类型为 `String`，即数据库名称。
- `int getVGroupId()`
- **接口说明**：获取虚拟组 ID。
- **返回值**：返回值类型为 `int`，即虚拟组 ID。
- `V value()`
- **接口说明**：获取消息的值。
- **返回值**：返回值类型为 `V`，即消息的值。
- `long getOffset()`
- **接口说明**：获取消息的偏移量。
- **返回值**：返回值类型为 `long`，即消息的偏移量。
#### 分区信息
TopicPartition 类提供了分区信息，包含消息主题和虚拟组 ID。
- `TopicPartition(String topic, int vGroupId)`
- **接口说明**：构造一个新的 TopicPartition 实例，用于表示一个特定的主题和虚拟组 ID。
- **参数说明**：
- `topic`：一个 `String` 类型的参数，表示消息的主题。
- `vGroupId`：一个 `int` 类型的参数，表示虚拟组 ID。
- `String getTopic()`
- **接口说明**：获取此 TopicPartition 实例的主题。
- **返回值**：返回值类型为 `String`，即此 TopicPartition 实例的主题。
- `int getVGroupId()`
- **接口说明**：获取此 TopicPartition 实例的虚拟组 ID。
- **返回值**：返回值类型为 `int`，即此 TopicPartition 实例的虚拟组 ID。
#### 偏移量元数据
OffsetAndMetadata 类提供了偏移量元数据信息。
- `long offset()`
- **接口说明**：获取此 OffsetAndMetadata 实例中的偏移量。
- **返回值**：返回值类型为 `long`，即此 OffsetAndMetadata 实例中的偏移量。
- `String metadata()`
- **接口说明**：获取此 OffsetAndMetadata 实例中的元数据。
- **返回值**：返回值类型为 `String`，即此 OffsetAndMetadata 实例中的元数据。
#### 反序列化
JDBC 驱动提供了两个反序列化类：ReferenceDeserializer 和 MapDeserializer。它们都实现了 Deserializer 接口。
ReferenceDeserializer 用来将消费到的一条记录反序列化为一个对象，需要保证对象类的属性名与消费到的数据的列名能够对应，且类型能够匹配。
MapDeserializer 则会将消费到的一行数据反序列化为一个 `Map<String, Object>` 对象，其 key 为列名，值为 Java 对象。
ReferenceDeserializer 和 MapDeserializer 的接口不会被用户直接调用，请参考使用样例。
## 附录
taos-jdbcdriver Javadoc:[taos-jdbcdriver doc](https://docs.taosdata.com/api/taos-jdbcdriver)
JDBC Javadoc:[JDBC Reference doc](https://docs.oracle.com/javase/8/docs/api/java/sql/package-summary.html)
Reference in a new issue View git blame Copy permalink