Go SDK
更新时间：2026-07-24
本文介绍如何使用 Go SDK 连接 TSDB 专享版，并完成数据写入和查询。
环境准备
使用 SDK 前，请准备一个 Go Module 项目，并完成 SDK 使用说明中的连接准备工作。
安装 SDK
本文示例使用 influxdb3-go/v2 2.17.0。
Bash
1go get github.com/InfluxCommunity/influxdb3-go/v2@v2.17.0配置连接信息
示例通过以下环境变量读取连接信息：
| 环境变量 | 说明 |
|---|---|
TSDB_HOST_URL |
由集群详情页显示的访问地址和端口组成的完整 URL，例如 http://<访问地址>:<端口> |
TSDB_DATABASE_NAME |
目标 Database 名称 |
TSDB_AUTH_TOKEN |
具有目标 Database 读写权限的业务访问令牌 |
写入和查询数据
以下示例初始化客户端，写入一条 Line Protocol 数据，然后使用 SQL 查询刚写入的数据：
Go
1package main
2
3import (
4 "context"
5 "fmt"
6 "os"
7 "time"
8
9 "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3"
10)
11
12func main() {
13 writeOptions := influxdb3.DefaultWriteOptions
14 writeOptions.UseV2Api = false
15
16 client, err := influxdb3.New(influxdb3.ClientConfig{
17 Host: os.Getenv("TSDB_HOST_URL"),
18 Token: os.Getenv("TSDB_AUTH_TOKEN"),
19 AuthScheme: "Bearer",
20 Database: os.Getenv("TSDB_DATABASE_NAME"),
21 WriteOptions: &writeOptions,
22 })
23 if err != nil {
24 panic(err)
25 }
26 defer client.Close()
27
28 ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
29 defer cancel()
30
31 if err := client.Write(ctx, []byte("cpu,host=server01 usage=42.5")); err != nil {
32 panic(err)
33 }
34
35 // 首次写入创建 Table 后，等待新表可查询。
36 time.Sleep(5 * time.Second)
37
38 sql := "SELECT time, host, usage FROM cpu " +
39 "WHERE host = 'server01' ORDER BY time DESC LIMIT 1"
40 rows, err := client.Query(ctx, sql)
41 if err != nil {
42 panic(err)
43 }
44 for rows.Next() {
45 fmt.Println(rows.Value())
46 }
47 if err := rows.Err(); err != nil {
48 panic(err)
49 }
50}配置说明
writeOptions.UseV2Api = false用于启用 V3 写入接口，复制示例时请保留该配置。- 请先复制
DefaultWriteOptions，再修改UseV2Api。如果直接新建只包含UseV2Api的WriteOptions，其他选项会使用 Go 零值，从而改变客户端的默认写入行为。 - 写入和查询使用同一个
TSDB_HOST_URL，无需手动拼接 API 路径。 - 示例首次写入
cpu时会自动创建 Table，因此在写入后等待 5 秒。新表通常在约 5 秒后可以查询，实际时间可能受集群运行状态影响。该等待只适用于首次建表；向已有 Table 写入不受影响。 - 建议为每次写入和查询设置
context超时，并在应用退出前关闭客户端。 - 调用
Query后既要检查返回的error，也要在迭代完成后检查rows.Err()。 - SDK 只用于数据写入和查询。管理 Database、Table、Retention 或业务访问令牌时，请使用 CLI 工具或资源管理 API。
评价此篇文章