TDengine Go 连接器完全指南：从入门到精通-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00728/article/details/148374480

TDengine Go 连接器完全指南：从入门到精通

TDengine TDengine is an open source, high-performance, cloud native time-series database optimized for Internet of Things (IoT), Connected Cars, Industrial IoT and DevOps. 项目地址: https://gitcode.com/gh_mirrors/tde/TDengine

概述

TDengine Go 连接器（driver-go）是 TDengine 数据库的官方 Go 语言驱动程序，实现了 Go 标准库 database/sql 的接口规范。通过这个连接器，Go 开发者可以轻松地开发访问 TDengine 时序数据库的应用程序。

核心特性

多协议支持：提供原生 TCP、REST 和 WebSocket 三种连接方式
全面兼容：完全兼容 Go 的 database/sql 接口标准
高性能：支持批量操作和参数绑定，优化数据传输效率
数据类型丰富：支持 TDengine 所有数据类型与 Go 类型的映射
跨平台：WebSocket/REST 连接支持所有能运行 Go 的平台

环境要求

Go 版本：1.14 及以上
TDengine 版本：不同功能需要不同版本的 TDengine 服务端支持

安装与配置

安装驱动

go get github.com/taosdata/driver-go/v3

连接配置

TDengine Go 连接器支持三种连接方式，每种方式有不同的 DSN（数据源名称）格式：

1. 原生 TCP 连接

import (
    "database/sql"
    _ "github.com/taosdata/driver-go/v3/taosSql"
)

func main() {
    db, err := sql.Open("taosSql", "root:taosdata@tcp(localhost:6030)/")
    if err != nil {
        panic(err)
    }
    defer db.Close()
}

DSN 参数说明：

cfg：指定 taos.cfg 目录
cgoThread：cgo 并发执行数量（默认为 CPU 核数）
cgoAsyncHandlerPoolSize：异步函数处理池大小（默认 10000）

2. REST 连接

import (
    "database/sql"
    _ "github.com/taosdata/driver-go/v3/taosRestful"
)

func main() {
    db, err := sql.Open("taosRestful", "root:taosdata@http(localhost:6041)/")
    if err != nil {
        panic(err)
    }
    defer db.Close()
}

DSN 参数说明：

disableCompression：是否禁用压缩（默认 true）
readBufferSize：读取缓冲区大小（默认 4KB）
token：连接云服务时的认证 token
skipVerify：是否跳过 SSL 证书验证（默认 false）

3. WebSocket 连接

import (
    "database/sql"
    _ "github.com/taosdata/driver-go/v3/taosWS"
)

func main() {
    db, err := sql.Open("taosWS", "root:taosdata@ws(localhost:6041)/")
    if err != nil {
        panic(err)
    }
    defer db.Close()
}

DSN 参数说明：

enableCompression：是否启用压缩（默认 false）
readTimeout：读取超时时间（默认 5 分钟）
writeTimeout：写入超时时间（默认 10 秒）

数据类型映射

TDengine 数据类型与 Go 类型的对应关系如下：

| TDengine 类型 | Go 类型 | |-----------------------|-------------| | TIMESTAMP | time.Time | | TINYINT | int8 | | SMALLINT | int16 | | INT | int32 | | BIGINT | int64 | | TINYINT UNSIGNED | uint8 | | SMALLINT UNSIGNED | uint16 | | INT UNSIGNED | uint32 | | BIGINT UNSIGNED | uint64 | | FLOAT | float32 | | DOUBLE | float64 | | BOOL | bool | | BINARY/NCHAR | string | | JSON/GEOMETRY/VARBINARY | []byte | | DECIMAL | string |

注意：

JSON 类型仅在 tag 中支持
GEOMETRY 类型采用小端字节序的 WKB 格式
时间类型会自动转换为本地时区（WebSocket/原生连接）或 UTC 时区（REST 连接）

基础操作

1. 执行 SQL 语句

// 创建数据库
_, err := db.Exec("CREATE DATABASE IF NOT EXISTS test")
if err != nil {
    panic(err)
}

// 创建表
_, err = db.Exec("CREATE TABLE IF NOT EXISTS test.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)")
if err != nil {
    panic(err)
}

2. 插入数据

// 单条插入
_, err := db.Exec("INSERT INTO test.d1001 USING test.meters TAGS('California.SanFrancisco', 2) VALUES (NOW, 10.2, 219, 0.32)")
if err != nil {
    panic(err)
}

// 批量插入
_, err = db.Exec("INSERT INTO test.d1001 USING test.meters TAGS('California.SanFrancisco', 2) VALUES (NOW-1s, 10.3, 218, 0.33) (NOW, 10.4, 221, 0.31)")
if err != nil {
    panic(err)
}

3. 查询数据

rows, err := db.Query("SELECT * FROM test.meters")
if err != nil {
    panic(err)
}
defer rows.Close()

for rows.Next() {
    var ts time.Time
    var current float32
    var voltage int32
    var phase float32
    var location string
    var groupId int32
    
    err := rows.Scan(&ts, &current, &voltage, &phase, &location, &groupId)
    if err != nil {
        panic(err)
    }
    fmt.Printf("ts: %v, current: %f, voltage: %d, phase: %f, location: %s, groupId: %d\n",
        ts, current, voltage, phase, location, groupId)
}

高级功能

1. 参数绑定（Prepared Statement）

// 准备语句
stmt, err := db.Prepare("INSERT INTO test.meters VALUES(?, ?, ?, ?)")
if err != nil {
    panic(err)
}
defer stmt.Close()

// 执行绑定
_, err = stmt.Exec(time.Now(), 10.5, 220, 0.30)
if err != nil {
    panic(err)
}

2. 无模式写入

TDengine 提供了三种无模式写入方式：

InfluxDB 行协议

import "github.com/taosdata/driver-go/v3/af"

conn, err := af.Open("localhost", "root", "taosdata", "", 6030)
if err != nil {
    panic(err)
}
defer conn.Close()

err = conn.InfluxDBInsertLines([]string{
    "meters,location=California.SanFrancisco,groupId=2 current=10.2,voltage=219,phase=0.32",
}, "ns")
if err != nil {
    panic(err)
}

OpenTSDB Telnet 协议

err = conn.OpenTSDBInsertTelnetLines([]string{
    "meters 1626006833 10.2 location=California.SanFrancisco groupId=2",
    "meters 1626006834 10.3 location=California.SanFrancisco groupId=2",
})
if err != nil {
    panic(err)
}

OpenTSDB JSON 协议

err = conn.OpenTSDBInsertJsonPayload(`{
    "metric": "meters",
    "timestamp": 1626006833,
    "value": 10.2,
    "tags": {
        "location": "California.SanFrancisco",
        "groupId": "2"
    }
}`)
if err != nil {
    panic(err)
}

3. 订阅功能

import "github.com/taosdata/driver-go/v3/ws/subscribe"

// 创建订阅
sub, err := subscribe.NewSubscriber("ws://localhost:6041", "root", "taosdata")
if err != nil {
    panic(err)
}
defer sub.Close()

// 订阅主题
err = sub.Subscribe("test_sub", "SELECT * FROM test.meters", time.Second*30)
if err != nil {
    panic(err)
}

// 消费消息
for {
    topic, message, err := sub.Consume()
    if err != nil {
        panic(err)
    }
    fmt.Printf("topic: %s, message: %s\n", topic, message)
}