TDengine Go 连接器入门指南

TDengine Go 连接器入门指南

本文面向 TDengine 初学者，目标是让你在 5～10 分钟内完成：安装连接器 → 建立连接 → 建库建表 → 写入 → 查询，并掌握 Go 连接器在工程里的基本使用方式与常见问题排查思路。

说明：TDengine 官方 Go 连接器为driver-go，实现了 Go 标准库database/sql接口。

1. 选择连接方式

driver-go支持两种连接方式，建议优先使用WebSocket 连接：

• WebSocket 连接（推荐）：通过taosAdapter的 WebSocket 接口访问 TDengine。跨平台、依赖更轻，适合云环境/容器环境，也更便于与服务端版本解耦。
• 原生连接（Native）：Go 进程会加载 TDengine 客户端驱动（如libtaos.so/taos.dll/libtaos.dylib）直接连接 TDengine。性能高，但对本地依赖与版本匹配要求更高。

2. 环境准备

在运行示例前，请确认：

• TDengine TSDB 服务端已启动，并且你的程序能访问到它。
• 若使用WebSocket 连接：确保taosAdapter的 WebSocket 服务可用（常见默认端口6041）。
• 若使用原生连接：确保已安装 TDengine TSDB 客户端驱动。
  • 如果你的机器已经安装了 TDengine 服务端软件，一般已包含客户端驱动。
  • 如果仅在没有服务端的软件环境运行原生连接，请参考连接器总览页的“安装客户端驱动”：
    • 安装客户端驱动

3. 安装 Go 连接器

driver-go使用 Go Modules 管理依赖。

mkdirtdengine-go-quickstartcdtdengine-go-quickstart go mod init tdengine-go-quickstart go get github.com/taosdata/driver-go/v3

4. 第一个程序：建库建表、写入、查询

下面提供两份“最小可运行”示例，你可以任选其一。

为了避免USE db在database/sql连接复用场景下引入状态干扰（连接池会复用连接），示例采用“先连到无 db 的 DSN 创建数据库，再用带 db 的 DSN 做业务操作”的方式。

4.1 WebSocket（推荐）

创建文件main.go：

packagemainimport("context""database/sql""fmt""log""time"// WebSocket 驱动_"github.com/taosdata/driver-go/v3/taosWS"// 可选：用于解析 TDengine 错误码taosErrors"github.com/taosdata/driver-go/v3/errors")funcmain(){// 1) 先连接到“无 db”的 DSN，用于创建数据库// DSN 规范见 Go 连接器参考文档。// 常见默认：WebSocket 端口 6041rootDSN:="root:taosdata@ws(localhost:6041)/"rootDB,err:=sql.Open("taosWS",rootDSN)iferr!=nil{log.Fatal(err)}deferrootDB.Close()// 给连接与单次请求设置超时（建议）ctx,cancel:=context.WithTimeout(context.Background(),10*time.Second)defercancel()if_,err:=rootDB.ExecContext(ctx,"CREATE DATABASE IF NOT EXISTS demo");err!=nil{logFatalTaos(err)}// 2) 再连接到“带 db”的 DSN，进行建表/写入/查询demoDSN:="root:taosdata@ws(localhost:6041)/demo"db,err:=sql.Open("taosWS",demoDSN)iferr!=nil{log.Fatal(err)}deferdb.Close()// 按需调整连接池参数（示例给出一个保守配置）db.SetMaxOpenConns(10)db.SetMaxIdleConns(10)db.SetConnMaxLifetime(30*time.Minute)ctx2,cancel2:=context.WithTimeout(context.Background(),10*time.Second)defercancel2()// 创建超级表与子表_,err=db.ExecContext(ctx2,` CREATE STABLE IF NOT EXISTS meters ( ts TIMESTAMP, current FLOAT, voltage INT ) TAGS (location BINARY(24)) `)iferr!=nil{logFatalTaos(err)}_,err=db.ExecContext(ctx2,"CREATE TABLE IF NOT EXISTS d0 USING meters TAGS('beijing')")iferr!=nil{logFatalTaos(err)}// 写入两条数据_,err=db.ExecContext(ctx2,"INSERT INTO d0 VALUES (NOW, 10.2, 220) (NOW + 1s, 10.3, 221)")iferr!=nil{logFatalTaos(err)}// 查询并打印rows,err:=db.QueryContext(ctx2,"SELECT ts, current, voltage FROM meters LIMIT 5")iferr!=nil{logFatalTaos(err)}deferrows.Close()forrows.Next(){var(ts time.Time currentfloat32voltageint32)iferr:=rows.Scan(&ts,&current,&voltage);err!=nil{log.Fatal(err)}fmt.Printf("ts=%s current=%.2f voltage=%d\n",ts.Format(time.RFC3339Nano),current,voltage)}iferr:=rows.Err();err!=nil{logFatalTaos(err)}fmt.Println("done")}funclogFatalTaos(errerror){iferr==nil{return}// 尝试输出 TDengine 错误码，便于排查ifte,ok:=err.(*taosErrors.TaosError);ok{log.Fatalf("taos error: code=%d msg=%s",int(te.Code),te.ErrStr)}log.Fatal(err)}

运行：

go run.

4.2 原生连接（Native）

原生连接与 WebSocket 的主要区别是：导入的驱动不同、协议与端口通常不同（常见默认原生端口6030）。

将上面的示例改动两处即可：

1. 把驱动导入改为：

_"github.com/taosdata/driver-go/v3/taosSql"

2. 把 DSN 与 driverName 改为原生连接：

rootDSN:="root:taosdata@tcp(localhost:6030)/"rootDB,err:=sql.Open("taosSql",rootDSN)demoDSN:="root:taosdata@tcp(localhost:6030)/demo"db,err:=sql.Open("taosSql",demoDSN)

其余 SQL 与database/sql用法保持不变。

5. 连接参数与 DSN

常见 DSN 形态：

username:password@protocol(address)/dbname?param=value

• WebSocket：root:taosdata@ws(localhost:6041)/demo
• 原生：root:taosdata@tcp(localhost:6030)/demo

注意事项：

• 密码包含特殊字符时，需要用url.QueryEscape转义（参考 Go 连接器手册中的 DSN 规范说明）。
• IPv6 地址需要用方括号，例如：root:taosdata@ws([::1]:6041)/demo
• timezone参数可指定连接时区（IANA 格式），例如：timezone=Asia%2FShanghai

详见：

• Go 连接器参考手册

6. 常见问题与排查

• 连接失败（WebSocket）：确认taosAdapter已启动、端口可达、账号密码正确。
• 连接失败（原生）：确认客户端驱动已安装且可被加载；并检查客户端/服务端版本匹配。
• 查询结果时区与预期不一致：按需设置 DSNtimezone，并注意默认会按本地时区转换。
• 需要定位 TDengine 错误原因：打印TaosError的Code/ErrStr，并对照错误码文档。

参考：

• 错误码表

7. 下一步（进阶能力入口）

当你能跑通上面的“建库建表、写入、查询”后，建议按需求继续：

• 参数绑定（stmt / stmt2）以提升写入性能。
• 无模式写入（schemaless）以接入 InfluxDB Line Protocol / OpenTSDB 等。
• TMQ 消息订阅与消费。

关于TDengine

TDengine 专为物联网IoT平台、工业大数据平台设计。其中，TDengine TSDB 是一款高性能、分布式的时序数据库（Time Series Database），同时它还带有内建的缓存、流式计算、数据订阅等系统功能；TDengine IDMP 是一款AI原生工业数据管理平台，它通过树状层次结构建立数据目录，对数据进行标准化、情景化，并通过 AI 提供实时分析、可视化、事件管理与报警等功能。