--- 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 连接支持负载均衡
2. 自动重连支持参数绑定
3. 优化了高效写入序列化性能
4. 优化了 WebSocket 连接 isValid 性能 | - | | 3.7.3 | 优化了 WebSocket 和 Native 查询实现 | - | | 3.7.2 | 解决了 supportsBatchUpdates 问题，提升 Spring JdbcTemplate 参数绑定写入性能 | - | | 3.7.1 | 1. 使用 Netty 替换 Java-WebSocket 库，提升小查询性能
2. 兼容 IPv6 网络协议
3. 支持 BLOB 二进制数据类型
4. 实现 TDengine 版本兼容性检查
5. 支持 `varcharAsString` 配置属性
6. 优化 WebSocket 查询内存使用效率
7. 修复 WebSocket 连接的时区问题
| - | | 3.6.3 | 解决了订阅数据库和超级表时的数据类型转换 bug | - | | 3.6.2 | 1. 支持订阅数据库和超级表（不支持订阅元数据）
2. 解决了云服务订阅 bug
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 连接参数绑定性能，支持参数绑定查询使用二进制数据
2. 优化了 WebSocket 连接在小查询上的性能
3. WebSocket 连接上支持设置时区和应用信息 | 3.3.5.0 及更高版本 | | 3.4.0 | 1. 使用 jackson 库替换 fastjson 库
2. WebSocket 采用独立协议标识
3. 优化后台拉取线程使用，避免用户误用导致超时 | - | | 3.3.4 | 解决了 getInt 在数据类型为 float 报错 | - | | 3.3.3 | 解决了 WebSocket statement 关闭导致的内存泄漏 | - | | 3.3.2 | 1. 优化 WebSocket 连接下的参数绑定性能
2. 优化了对 mybatis 的支持 | - | | 3.3.0 | 1. 优化 WebSocket 连接下的数据传输性能
2. 支持跳过 SSL 验证，默认关闭 | 3.3.2.0 及更高版本 | | 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 | 1. 优化了自动提交
2. 解决了 WebSocket 手动提交 bug
3.优化 WebSocket prepareStatement 使用一个连接
4.元数据支持视图 | - | | 3.2.7 | 1. 支持 VARBINARY 和 GEOMETRY 类型
2. 增加 native 连接的时区设置支持
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 写入
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 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 getObject(String columnLabel, Class 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 list) throws SQLException` - **接口说明**：为指定列索引设置批量整型值。 - **参数说明**： - `columnIndex`：列的索引位置。 - `list`：包含整型值的列表。 - **异常**： - 如果操作过程中发生错误，将抛出 SQLException 异常。 - 下面接口除了要设置的值类型不同外，其余同 setInt： - `void setFloat(int columnIndex, ArrayList list) throws SQLException` - `void setTimestamp(int columnIndex, ArrayList list) throws SQLException` - `void setLong(int columnIndex, ArrayList list) throws SQLException` - `void setDouble(int columnIndex, ArrayList list) throws SQLException` - `void setBoolean(int columnIndex, ArrayList list) throws SQLException` - `void setByte(int columnIndex, ArrayList list) throws SQLException` - `void setShort(int columnIndex, ArrayList list) throws SQLException` - `void setString(int columnIndex, ArrayList list, int size) throws SQLException` - **接口说明**：为指定列索引设置字符串值列表。 - **参数说明**： - `columnIndex`：列的索引位置。 - `list`：包含字符串值的列表。 - `size`：所有字符串的最大长度，一般为建表语句的限制值。 - **异常**： - 如果操作过程中发生错误，将抛出 SQLException 异常。 - 下面接口除了要设置的值类型不同外，其余同 setString： - `void setVarbinary(int columnIndex, ArrayList list, int size) throws SQLException` - `void setGeometry(int columnIndex, ArrayList list, int size) throws SQLException` - `void setNString(int columnIndex, ArrayList list, int size) throws SQLException` - `void columnDataAddBatch() throws SQLException` - **接口说明**：将 `setInt（int columnIndex， ArrayList 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` 类型的消费者。这样每行数据就可以反序列化为表名和一个 `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 topics) throws SQLException` - **接口说明**：订阅一组主题。 - **参数说明**： - `topics`：一个 `Collection` 类型的参数，表示要订阅的主题列表。 - **异常**：如果在订阅过程中发生错误，将抛出 SQLException 异常。 - `void unsubscribe() throws SQLException` - **接口说明**：取消订阅所有主题。 - **异常**：如果在取消订阅过程中发生错误，将抛出 SQLException 异常。 - `Set subscription() throws SQLException` - **接口说明**：获取当前订阅的所有主题。 - **返回值**：返回值类型为 `Set`，即当前订阅的所有主题集合。 - **异常**：如果在获取订阅信息过程中发生错误，将抛出 SQLException 异常。 - `ConsumerRecords poll(Duration timeout) throws SQLException` - **接口说明**：轮询消息。 - **参数说明**： - `timeout`：一个 `Duration` 类型的参数，表示轮询的超时时间。 - **返回值**：返回值类型为 `ConsumerRecords`，即轮询到的消息记录。 - **异常**：如果在轮询过程中发生错误，将抛出 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 beginningOffsets(String topic) throws SQLException` - **接口说明**：获取指定主题的每个分区的最早偏移量。 - **参数说明**： - `topic`：一个 `String` 类型的参数，表示要查询的主题。 - **返回值**：返回值类型为 `Map`，即指定主题的每个分区的最早偏移量。 - **异常**：如果在获取最早偏移量过程中发生错误，将抛出 SQLException 异常。 - `Map endOffsets(String topic) throws SQLException` - **接口说明**：获取指定主题的每个分区的最新偏移量。 - **参数说明**： - `topic`：一个 `String` 类型的参数，表示要查询的主题。 - **返回值**：返回值类型为 `Map`，即指定主题的每个分区的最新偏移量。 - **异常**：如果在获取最新偏移量过程中发生错误，将抛出 SQLException 异常。 - `void seekToBeginning(Collection partitions) throws SQLException` - **接口说明**：将一组分区的偏移量设置到最早的偏移量。 - **参数说明**： - `partitions`：一个 `Collection` 类型的参数，表示要操作的分区集合。 - **异常**：如果在设置偏移量过程中发生错误，将抛出 SQLException 异常。 - `void seekToEnd(Collection partitions) throws SQLException` - **接口说明**：将一组分区的偏移量设置到最新的偏移量。 - **参数说明**： - `partitions`：一个 `Collection` 类型的参数，表示要操作的分区集合。 - **异常**：如果在设置偏移量过程中发生错误，将抛出 SQLException 异常。 - `Set assignment() throws SQLException` - **接口说明**：获取消费者当前分配的所有分区。 - **返回值**：返回值类型为 `Set`，即消费者当前分配的所有分区。 - **异常**：如果在获取分配的分区过程中发生错误，将抛出 SQLException 异常。 - `OffsetAndMetadata committed(TopicPartition partition) throws SQLException` - **接口说明**：获取指定分区最后提交的偏移量。 - **参数说明**： - `partition`：一个 `TopicPartition` 类型的参数，表示要查询的分区。 - **返回值**：返回值类型为 `OffsetAndMetadata`，即指定分区最后提交的偏移量。 - **异常**：如果在获取提交的偏移量过程中发生错误，将抛出 SQLException 异常。 - `Map committed(Set partitions) throws SQLException` - **接口说明**：获取一组分区最后提交的偏移量。 - **参数说明**： - `partitions`：一个 `Set` 类型的参数，表示要查询的分区集合。 - **返回值**：返回值类型为 `Map`，即一组分区最后提交的偏移量。 - **异常**：如果在获取提交的偏移量过程中发生错误，将抛出 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` 对象，其 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)