连接方式

taos-jdbcdriver主要提供三种形式的连接器。一般我们推荐使用 Websocket 连接。

  • 原生连接，通过 TDengine 客户端驱动程序（taosc）原生连接 TDengine 实例，支持数据写入、查询、数据订阅、schemaless 接口和参数绑定接口等功能。
  • REST 连接，通过 taosAdapter 提供的 HTTP 接口连接 TDengine 实例，不支持 schemaless 和数据订阅等特性。
  • Websocket 连接，通过 taosAdapter 提供的 Websocket 接口连接 TDengine 实例，WebSocket 连接实现的功能集合和原生连接有少量不同。

安装步骤

添加Maven依赖

1
2
3
4
5
<dependency>
  <groupId>com.taosdata.jdbc</groupId>
  <artifactId>taos-jdbcdriver</artifactId>
  <version>3.2.8</version>
</dependency>

连接配置

1
2
3
4
username: ${tdengine.username}
password: ${tdengine.password}
driver-class-name: ${tdengine.driverClassName}
url: jdbc:TAOS-RS://${tdengine.ip}:${tdengine.port}/${tdengine.database}?charset=UTF-8&batchfetch=true
  • user：登录 TDengine 用户名，默认值 ‘root’。
  • password：用户登录密码，默认值 ‘taosdata’。
  • batchfetch: true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：false。逐行拉取结果集使用 HTTP 方式进行数据传输。JDBC REST 连接支持批量拉取数据功能。taos-jdbcdriver 与 TDengine 之间通过 WebSocket 连接进行数据传输。相较于 HTTP，WebSocket 可以使 JDBC REST 连接支持大数据量查询，并提升查询性能。
  • charset: 当开启批量拉取数据时，指定解析字符串数据的字符集。
  • batchErrorIgnore：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 SQL 了。false：不再执行失败 SQL 后的任何语句。默认值为：false。
  • httpConnectTimeout: 连接超时时间，单位 ms， 默认值为 60000。
  • httpSocketTimeout: socket 超时时间，单位 ms，默认值为 60000。仅在 batchfetch 设置为 false 时生效。
  • messageWaitTimeout: 消息超时时间, 单位 ms， 默认值为 60000。 仅在 batchfetch 设置为 true 时生效。
  • useSSL: 连接中是否使用 SSL。
  • httpPoolSize: REST 并发请求大小，默认 20。

NOTE

  • 与原生连接方式不同，REST 接口是无状态的。在使用 JDBC REST 连接时，需要在 SQL 中指定表、超级表的数据库名称。例如：
1
>INSERT INTO power.d1001 USING power.meters TAGS(2,'California.SanFrancisco') VALUES (NOW, 10.30000, 219, 0.31000);
  • 如果在 url 中指定了 dbname，那么，JDBC REST 连接会默认使用/rest/sql/dbname 作为 restful 请求的 url，在 SQL 中不需要指定 dbname。例如：url 为 jdbc:TAOS-RS://127.0.0.1:6041/power，那么，可以执行 sql：INSERT INTO d1001 USING meters TAGS(2,‘California.SanFrancisco’) VALUES (NOW, 10.30000, 219, 0.31000);

创建实体类

1
2
3
4
5
6
7
8
9
@Data
public class Weather {

    private Timestamp ts;
    private float temperature;
    private int humidity;
    private String location;

}

创建Mapper

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
public interface TemperatureMapper extends BaseMapper<Temperature> {

    @Update("CREATE TABLE if not exists temperature(ts timestamp, temperature float) tags(location nchar(64), tbIndex int)")
    int createSuperTable();

    @Update("create table #{tbName} using temperature tags( #{location}, #{tbindex})")
    int createTable(@Param("tbName") String tbName, @Param("location") String location, @Param("tbindex") int tbindex);

    @Update("drop table if exists temperature")
    void dropSuperTable();

    @Insert("insert into t${tbIndex}(ts, temperature) values(#{ts}, #{temperature})")
    int insertOne(Temperature one);
    /**
 	 * 批量写入
 	 * 此批量插入使用了超级表的方式进行批量插入
     *
     * @author lokywang
     * @date 2024/03/29
     */
    void saveBatch(@Param("temperatures") List<Temperature> temperatures);

}

Mapper.xml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.loky.wang.mapper.TemperatureMapper">

    <insert id="saveBatch" parameterType="java.util.List">
        INSERT INTO stb_temperature (
        `ts`,
        `temperature`,
        `location`,
        `tbIndex`
        ) VALUES
        <foreach collection="temperatures" item="item" index="index" separator=",">
            (
            #{item.ts},
            #{item.temperature},
            #{item.location},
            #{item.tbIndex}
            )
        </foreach>
    </insert>
</mapper>