400 lines
10 KiB
Plaintext
400 lines
10 KiB
Plaintext
---
|
||
toc_max_heading_level: 4
|
||
sidebar_position: 4
|
||
sidebar_label: Go
|
||
title: TDengine Go Connector
|
||
---
|
||
|
||
import Tabs from '@theme/Tabs';
|
||
import TabItem from '@theme/TabItem';
|
||
|
||
import RequestId from "./_request_id.mdx";
|
||
|
||
`driver-go` 是 TDengine 的官方 Go 语言连接器，实现了 Go 语言 [database/sql](https://golang.org/pkg/database/sql/) 包的接口。Go 开发人员可以通过它开发存取 TDengine 集群数据的应用软件。
|
||
|
||
## 连接方式
|
||
|
||
`driver-go` 提供三种建立连接的方式。
|
||
|
||
* **原生连接**，通过 TDengine 客户端驱动程序（taosc）原生连接 TDengine 实例，支持数据写入、查询、数据订阅、schemaless 接口和参数绑定接口等功能。
|
||
* **REST 连接**，通过 taosAdapter 提供的 HTTP 接口连接 TDengine 实例，不支持 schemaless 和数据订阅等特性。
|
||
* **Websocket 连接**，通过 taosAdapter 提供的 Websocket 接口连接 TDengine 实例，WebSocket 连接实现的功能集合和原生连接有少量不同。
|
||
|
||
连接方式的详细介绍请参考：[连接器建立连接的方式](../../develop/connect/#连接器建立连接的方式)
|
||
|
||
## 兼容性
|
||
|
||
支持最低 Go 版本 1.14，建议使用最新 Go 版本
|
||
|
||
## 支持的平台
|
||
|
||
原生连接支持的平台和 TDengine 客户端驱动支持的平台一致。
|
||
REST 连接支持所有能运行 Go 的平台。
|
||
|
||
## 版本支持
|
||
|
||
请参考[版本支持列表](https://github.com/taosdata/driver-go#remind)
|
||
|
||
## 处理异常
|
||
|
||
如果是 TDengine 错误可以通过以下方式获取错误码和错误信息。
|
||
|
||
```go
|
||
// import "github.com/taosdata/driver-go/v3/errors"
|
||
if err != nil {
|
||
tError, is := err.(*errors.TaosError)
|
||
if is {
|
||
fmt.Println("errorCode:", int(tError.Code))
|
||
fmt.Println("errorMessage:", tError.ErrStr)
|
||
} else {
|
||
fmt.Println(err.Error())
|
||
}
|
||
}
|
||
```
|
||
|
||
## TDengine DataType 和 Go DataType
|
||
|
||
| TDengine DataType | Go Type |
|
||
|-------------------|-----------|
|
||
| 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 | string |
|
||
| NCHAR | string |
|
||
| JSON | []byte |
|
||
|
||
**注意**：JSON 类型仅在 tag 中支持。
|
||
|
||
## 安装步骤
|
||
|
||
### 安装前准备
|
||
|
||
* 安装 Go 开发环境（Go 1.14 及以上，GCC 4.8.5 及以上）
|
||
* 如果使用原生连接器，请安装 TDengine 客户端驱动，具体步骤请参考[安装客户端驱动](../#安装客户端驱动)
|
||
|
||
配置好环境变量，检查命令：
|
||
|
||
* ```go env```
|
||
* ```gcc -v```
|
||
|
||
### 安装连接器
|
||
|
||
1. 使用 `go mod` 命令初始化项目：
|
||
|
||
```text
|
||
go mod init taos-demo
|
||
```
|
||
|
||
2. 引入 taosSql ：
|
||
|
||
```go
|
||
import (
|
||
"database/sql"
|
||
_ "github.com/taosdata/driver-go/v3/taosSql"
|
||
)
|
||
```
|
||
|
||
3. 使用 `go mod tidy` 更新依赖包：
|
||
|
||
```text
|
||
go mod tidy
|
||
```
|
||
|
||
4. 使用 `go run taos-demo` 运行程序或使用 `go build` 命令编译出二进制文件。
|
||
|
||
```text
|
||
go run taos-demo
|
||
go build
|
||
```
|
||
|
||
## 建立连接
|
||
|
||
数据源名称具有通用格式，例如 [PEAR DB](http://pear.php.net/manual/en/package.database.db.intro-dsn.php)，但没有类型前缀（方括号表示可选）：
|
||
|
||
``` text
|
||
[username[:password]@][protocol[(address)]]/[dbname][?param1=value1&...¶mN=valueN]
|
||
```
|
||
|
||
完整形式的 DSN：
|
||
|
||
```text
|
||
username:password@protocol(address)/dbname?param=value
|
||
```
|
||
|
||
<Tabs defaultValue="rest" groupId="connect">
|
||
<TabItem value="native" label="原生连接">
|
||
|
||
_taosSql_ 通过 cgo 实现了 Go 的 `database/sql/driver` 接口。只需要引入驱动就可以使用 [`database/sql`](https://golang.org/pkg/database/sql/) 的接口。
|
||
|
||
使用 `taosSql` 作为 `driverName` 并且使用一个正确的 [DSN](#DSN) 作为 `dataSourceName`，DSN 支持的参数：
|
||
|
||
* cfg 指定 taos.cfg 目录
|
||
|
||
示例：
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"database/sql"
|
||
"fmt"
|
||
|
||
_ "github.com/taosdata/driver-go/v3/taosSql"
|
||
)
|
||
|
||
func main() {
|
||
var taosUri = "root:taosdata@tcp(localhost:6030)/"
|
||
taos, err := sql.Open("taosSql", taosUri)
|
||
if err != nil {
|
||
fmt.Println("failed to connect TDengine, err:", err)
|
||
return
|
||
}
|
||
}
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem value="rest" label="REST 连接">
|
||
|
||
_taosRestful_ 通过 `http client` 实现了 Go 的 `database/sql/driver` 接口。只需要引入驱动就可以使用[`database/sql`](https://golang.org/pkg/database/sql/)的接口。
|
||
|
||
使用 `taosRestful` 作为 `driverName` 并且使用一个正确的 [DSN](#DSN) 作为 `dataSourceName`，DSN 支持的参数：
|
||
|
||
* `disableCompression` 是否接受压缩数据，默认为 true 不接受压缩数据，如果传输数据使用 gzip 压缩设置为 false。
|
||
* `readBufferSize` 读取数据的缓存区大小默认为 4K（4096），当查询结果数据量多时可以适当调大该值。
|
||
|
||
示例：
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"database/sql"
|
||
"fmt"
|
||
|
||
_ "github.com/taosdata/driver-go/v3/taosRestful"
|
||
)
|
||
|
||
func main() {
|
||
var taosUri = "root:taosdata@http(localhost:6041)/"
|
||
taos, err := sql.Open("taosRestful", taosUri)
|
||
if err != nil {
|
||
fmt.Println("failed to connect TDengine, err:", err)
|
||
return
|
||
}
|
||
}
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem value="WebSocket" label="WebSocket 连接">
|
||
|
||
_taosWS_ 通过 `WebSocket` 实现了 Go 的 `database/sql/driver` 接口。只需要引入驱动（driver-go 最低版本 3.0.2）就可以使用[`database/sql`](https://golang.org/pkg/database/sql/)的接口。
|
||
|
||
使用 `taosWS` 作为 `driverName` 并且使用一个正确的 [DSN](#DSN) 作为 `dataSourceName`，DSN 支持的参数：
|
||
|
||
* `writeTimeout` 通过 WebSocket 发送数据的超时时间。
|
||
* `readTimeout` 通过 WebSocket 接收响应数据的超时时间。
|
||
|
||
示例：
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"database/sql"
|
||
"fmt"
|
||
|
||
_ "github.com/taosdata/driver-go/v3/taosWS"
|
||
)
|
||
|
||
func main() {
|
||
var taosUri = "root:taosdata@ws(localhost:6041)/"
|
||
taos, err := sql.Open("taosWS", taosUri)
|
||
if err != nil {
|
||
fmt.Println("failed to connect TDengine, err:", err)
|
||
return
|
||
}
|
||
}
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### 指定 URL 和 Properties 获取连接
|
||
|
||
Go 连接器不支持此功能
|
||
|
||
### 配置参数的优先级
|
||
|
||
Go 连接器不支持此功能
|
||
|
||
## 使用示例
|
||
|
||
### 创建数据库和表
|
||
|
||
```go
|
||
{{#include docs/examples/go/demo/query/main.go:create_db_and_table}}
|
||
```
|
||
|
||
### 插入数据
|
||
|
||
```go
|
||
{{#include docs/examples/go/demo/query/main.go:insert_data}}
|
||
```
|
||
|
||
### 查询数据
|
||
|
||
```go
|
||
{{#include docs/examples/go/demo/query/main.go:query_data}}
|
||
```
|
||
|
||
### 执行带有 reqId 的 SQL
|
||
|
||
<RequestId />
|
||
|
||
```go
|
||
{{#include docs/examples/go/demo/query/main.go:with_reqid}}
|
||
```
|
||
|
||
### 通过参数绑定写入数据
|
||
|
||
<Tabs defaultValue="native" groupId="connect">
|
||
<TabItem value="native" label="原生连接">
|
||
|
||
```go
|
||
{{#include docs/examples/go/demo/stmt/main.go}}
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem value="WebSocket" label="WebSocket 连接">
|
||
|
||
```go
|
||
{{#include docs/examples/go/demo/stmtws/main.go}}
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### 无模式写入
|
||
|
||
<Tabs defaultValue="native" groupId="connect">
|
||
<TabItem value="native" label="原生连接">
|
||
|
||
```go
|
||
{{#include docs/examples/go/demo/sml/main.go}}
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem value="WebSocket" label="WebSocket 连接">
|
||
|
||
```go
|
||
{{#include docs/examples/go/demo/smlws/main.go}}
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### 执行带有 reqId 的无模式写入
|
||
|
||
```go
|
||
func (s *Schemaless) Insert(lines string, protocol int, precision string, ttl int, reqID int64) error
|
||
```
|
||
|
||
可以通过 `common.GetReqID()` 获取唯一 id。
|
||
|
||
### 数据订阅
|
||
|
||
TDengine Go 连接器支持订阅功能，应用 API 如下：
|
||
|
||
#### 创建 Topic
|
||
|
||
```go
|
||
{{#include docs/examples/go/demo/consumer/main.go:create_topic}}
|
||
```
|
||
|
||
#### 创建 Consumer
|
||
|
||
```go
|
||
{{#include docs/examples/go/demo/consumer/main.go:create_consumer}}
|
||
```
|
||
|
||
#### 订阅消费数据
|
||
|
||
```go
|
||
{{#include docs/examples/go/demo/consumer/main.go:poll_data}}
|
||
```
|
||
|
||
#### 指定订阅 Offset
|
||
|
||
```go
|
||
{{#include docs/examples/go/demo/consumer/main.go:consumer_seek}}
|
||
```
|
||
|
||
#### 关闭订阅
|
||
|
||
```go
|
||
{{#include docs/examples/go/demo/consumer/main.go:consumer_close}}
|
||
```
|
||
|
||
#### 完整示例
|
||
|
||
<Tabs defaultValue="native" groupId="connect">
|
||
<TabItem value="native" label="原生连接">
|
||
|
||
```go
|
||
{{#include docs/examples/go/demo/consumer/main.go}}
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem value="WebSocket" label="WebSocket 连接">
|
||
|
||
```go
|
||
{{#include docs/examples/go/demo/consumerws/main.go}}
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### 更多示例程序
|
||
|
||
* [示例程序](https://github.com/taosdata/driver-go/tree/3.0/examples)
|
||
* [视频教程](https://www.taosdata.com/blog/2020/11/11/1951.html)。
|
||
|
||
## 常见问题
|
||
|
||
1. database/sql 中 stmt（参数绑定）相关接口崩溃
|
||
|
||
REST 不支持参数绑定相关接口，建议使用`db.Exec`和`db.Query`。
|
||
|
||
2. 使用 `use db` 语句后执行其他语句报错 `[0x217] Database not specified or available`
|
||
|
||
在 REST 接口中 SQL 语句的执行无上下文关联，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。
|
||
|
||
3. 使用 taosSql 不报错使用 taosRestful 报错 `[0x217] Database not specified or available`
|
||
|
||
因为 REST 接口无状态，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。
|
||
|
||
4. `readBufferSize` 参数调大后无明显效果
|
||
|
||
`readBufferSize` 调大后会减少获取结果时 `syscall` 的调用。如果查询结果的数据量不大，修改该参数不会带来明显提升，如果该参数修改过大，瓶颈会在解析 JSON 数据。如果需要优化查询速度，需要根据实际情况调整该值来达到查询效果最优。
|
||
|
||
5. `disableCompression` 参数设置为 `false` 时查询效率降低
|
||
|
||
当 `disableCompression` 参数设置为 `false` 时查询结果会使用 `gzip` 压缩后传输，拿到数据后要先进行 `gzip` 解压。
|
||
|
||
6. `go get` 命令无法获取包，或者获取包超时
|
||
|
||
设置 Go 代理 `go env -w GOPROXY=https://goproxy.cn,direct`。
|
||
|
||
## API 参考
|
||
|
||
全部 API 见 [driver-go 文档](https://pkg.go.dev/github.com/taosdata/driver-go/v3)
|