go.mdx

---
sidebar_position: 4
sidebar_label: Go
title: Go Connector
---

import Preparition from "./_preparition.mdx"

## 总体介绍

driver-go 是 TDengine 的官方 Go 语言连接器。Go 语言开发人员可以通过它开发存取 TDengine 数据库的应用软件。driver-go 实现了 Go [database/sql](https://golang.org/pkg/database/sql/) 包的接口，支持通过客户端驱动程序（taosc）原生连接 TDengine 服务端，支持数据写入、查询、订阅、schemaless 接口和参数绑定接口等功能。

driver-go 也支持使用 REST 连接 TDengine 服务端。

本文介绍如何在 Windows 或 Linux 环境中安装 driver-go，并通过 driver-go 连接 TDengine 数据库、进行数据查询、数据写入等基本操作。

Go 连接器的源码托管在 github。项目名称：driver-go。欢迎 [贡献源码](https://github.com/taosdata/driver-go) 或 [报告问题](https://github.com/taosdata/driver-go/issues)。

## 支持的平台

| **CPU 类型** | x64（64bit） |        |        | aarch64 | aarch32 |
|------------|------------|--------|--------|---------|---------|
| **OS 类型**  | Linux      | Win64  | Win32  | Linux   | Linux   |
| **支持与否**   | **支持**     | **支持** | **支持** | **支持**  | **支持**  |

## 版本支持

|   分支    |                      功能                       | 建议 taosd 版本 |
|:-------:|:---------------------------------------------:|:-----------:|
| master  |    database/sql（cgo）、订阅、schemaless写入、stmt     | 2.2.0.0 及以上 |
| develop | database/sql（cgo & REST）、订阅、schemaless写入、stmt | 2.4.0.4及以上  |

## 支持的特性

### 原生连接

“原生连接”指连接器通过客户端驱动（taosc）直接与 TDengine 服务端建立连接。

* database/sql (cgo 模式)
* 订阅
* schemaless 接口
* 参数绑定接口

### REST 连接

REST 连接指连接器通过 taosAdapter 组件提供的 REST API 建立与 taosd 的连接。

`develop` 分支使用 `http client` 实现了 `database/sql` 接口。

## 安装步骤

### 安装前的准备

1. 安装 Go 开发环境（Go 1.14 及以上，GCC 4.8.5 及以上）
<Preparition />

配置好环境变量，检查命令：

* ```go env```
* ```gcc -v```

### 使用 go get 安装

`go get -u github.com/taosdata/driver-go/v2@develop`

## 建立连接

### DSN

数据源名称具有通用格式，例如 [PEAR DB](http://pear.php.net/manual/en/package.database.db.intro-dsn.php)，但没有类型前缀（方括号表示可选）：

``` text
[username[:password]@][protocol[(address)]]/[dbname][?param1=value1&...&paramN=valueN]
```

完整形式的 DSN：

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

### 建立原生连接

_taosSql_ 通过 cgo 实现了 Go 的 `database/sql/driver` 接口。只需要引入驱动就可以使用[`database/sql`](https://golang.org/pkg/database/sql/)的接口。

使用 `taosSql` 作为 `driverName` 并且使用一个正确的 [DSN](#DSN) 作为 `dataSourceName`，DSN 支持的参数：

* configPath 指定 taos.cfg 目录

示例：

```go
package main

import (
    "database/sql"
    "fmt"

    _ "github.com/taosdata/driver-go/v2/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
    }
}
```

### 建立 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/v2/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
    }
}
```

## 示例程序

使用 Go 连接器的示例代码请参考：

* [示例程序](https://github.com/taosdata/TDengine/tree/develop/examples/go)
* [视频教程](https://www.taosdata.com/blog/2020/11/11/1951.html)。

### 使用限制

由于 REST 接口无状态所以 `use db` 语法不会生效，需要将 db 名称放到 SQL 语句中，如：`create table if not exists tb1 (ts timestamp, a int)`改为`create table if not exists test.tb1 (ts timestamp, a int)`否则将报错`[0x217] Database not specified or available`。

也可以将 db 名称放到 DSN 中，将 `root:taosdata@http(localhost:6041)/` 改为 `root:taosdata@http(localhost:6041)/test`，此方法在 TDengine 2.4.0.5 版本的 taosAdapter 开始支持。当指定的 db 不存在时执行 `create database` 语句不会报错，而执行针对该 db 的其他查询或写入操作会报错。

完整示例如下：

```go
package main

import (
    "database/sql"
    "fmt"
    "time"

    _ "github.com/taosdata/driver-go/v2/taosRestful"
)

func main() {
    var taosDSN = "root:taosdata@http(localhost:6041)/test"
    taos, err := sql.Open("taosRestful", taosDSN)
    if err != nil {
        fmt.Println("failed to connect TDengine, err:", err)
        return
    }
    defer taos.Close()
    taos.Exec("create database if not exists test")
    taos.Exec("create table if not exists tb1 (ts timestamp, a int)")
    _, err = taos.Exec("insert into tb1 values(now, 0)(now+1s,1)(now+2s,2)(now+3s,3)")
    if err != nil {
        fmt.Println("failed to insert, err:", err)
        return
    }
    rows, err := taos.Query("select * from tb1")
    if err != nil {
        fmt.Println("failed to select from table, err:", err)
        return
    }

    defer rows.Close()
    for rows.Next() {
        var r struct {
            ts time.Time
            a  int
        }
        err := rows.Scan(&r.ts, &r.a)
        if err != nil {
            fmt.Println("scan error:\n", err)
            return
        }
        fmt.Println(r.ts, r.a)
    }
}
```

### 常见问题

* 无法找到包 `github.com/taosdata/driver-go/v2/taosRestful`

将 `go.mod` 中 require 块对`github.com/taosdata/driver-go/v2`的引用改为`github.com/taosdata/driver-go/v2 develop`，之后执行 `go mod tidy`。

* database/sql 中 stmt 相关接口崩溃

REST 不支持 stmt 相关接口，建议使用`db.Exec`和`db.Query`。

* 使用 `use db` 语句后执行其他语句报错 `[0x217] Database not specified or available`

在 REST 接口中 SQL 语句的执行无上下文关联，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。

* 使用 taosSql 不报错使用 taosRestful 报错 `[0x217] Database not specified or available`

因为 REST 接口无状态，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。

* 升级 `github.com/taosdata/driver-go/v2/taosRestful`

将 `go.mod` 文件中对 `github.com/taosdata/driver-go/v2` 的引用改为 `github.com/taosdata/driver-go/v2 develop`，之后执行 `go mod tidy`。

* `readBufferSize` 参数调大后无明显效果

`readBufferSize` 调大后会减少获取结果时 `syscall` 的调用。如果查询结果的数据量不大，修改该参数不会带来明显提升，如果该参数修改过大，瓶颈会在解析 JSON 数据。如果需要优化查询速度，需要根据实际情况调整该值来达到查询效果最优。

* `disableCompression` 参数设置为 `false` 时查询效率降低

当 `disableCompression` 参数设置为 `false` 时查询结果会使用 `gzip` 压缩后传输，拿到数据后要先进行 `gzip` 解压。

* `go get` 命令无法获取包，或者获取包超时

设置 Go 代理 `go env -w GOPROXY=https://goproxy.cn,direct`。

## API

全部 API 见 [driver-go 文档](https://pkg.go.dev/github.com/taosdata/driver-go/v2)

### 常用 API

#### `database/sql`

* `sql.Open(DRIVER_NAME string, dataSourceName string) *DB`

该 API 用来打开 DB，返回一个类型为 \*DB 的对象。

**注意**： 该 API 成功创建的时候，并没有做权限等检查，只有在真正执行 Query 或者 Exec 的时候才能真正的去创建连接，并同时检查 user/password/host/port 是不是合法。

* `func (db *DB) Exec(query string, args ...interface{}) (Result, error)`

`sql.Open` 内置的方法，用来执行非查询相关 SQL。

* `func (db *DB) Query(query string, args ...interface{}) (*Rows, error)`

`sql.Open` 内置的方法，用来执行查询语句。

#### 高级功能

af 包封装了订阅、stmt 等 TDengine 高级功能。

* `af.Open(host, user, pass, db string, port int) (*Connector, error)`

该 API 通过 cgo 创建与 taosd 的连接。

* `func (conn *Connector) Close() error`

关闭与 taosd 的连接。

* `func (conn *Connector) StmtExecute(sql string, params *param.Param) (res driver.Result, err error)`

stmt 单行插入。

* `func (conn *Connector) StmtQuery(sql string, params *param.Param) (rows driver.Rows, err error)`

stmt 查询，返回 `database/sql/driver` 包的 `Rows` 结构。

##### 订阅

* `func (conn *Connector) Subscribe(restart bool, topic string, sql string, interval time.Duration) (Subscriber, error)`

订阅数据。

* `func (s *taosSubscriber) Consume() (driver.Rows, error)`

消费订阅数据，返回 `database/sql/driver` 包的 `Rows` 结构。

* `func (s *taosSubscriber) Unsubscribe(keepProgress bool)`

取消订阅数据。

##### schemaless 写入

* `func (conn *Connector) InfluxDBInsertLines(lines []string, precision string) error`

写入 influxDB 行协议。

* `func (conn *Connector) OpenTSDBInsertTelnetLines(lines []string) error`

写入 OpenTDSB telnet 协议。

* `func (conn *Connector) OpenTSDBInsertJsonPayload(payload string) error`

写入 OpenTSDB json 协议。

##### 批量 stmt 插入

* `func (conn *Connector) InsertStmt() *insertstmt.InsertStmt`

初始化 stmt。

* `func (stmt *InsertStmt) Prepare(sql string) error`

预处理 sql 语句。

* `func (stmt *InsertStmt) SetTableName(name string) error`

设置表名。

* `func (stmt *InsertStmt) SetSubTableName(name string) error`

设置子表名。

* `func (stmt *InsertStmt) BindParam(params []*param.Param, bindType *param.ColumnType) error`

绑定多行数据。

* `func (stmt *InsertStmt) AddBatch() error`

添加到批处理。

* `func (stmt *InsertStmt) Execute() error`

执行 stmt。

* `func (stmt *InsertStmt) GetAffectedRows() int`

获取受影响行数。

* `func (stmt *InsertStmt) Close() error`

结束 stmt。