diff --git a/docs-cn/14-reference/03-connector/go.mdx b/docs-cn/14-reference/03-connector/go.mdx index 608db63fd5c342c6a8e5e75fb5babc2b9b26d2bb..0a61e3e65244b2f19c49c9cd098d818118f285a4 100644 --- a/docs-cn/14-reference/03-connector/go.mdx +++ b/docs-cn/14-reference/03-connector/go.mdx @@ -4,135 +4,153 @@ sidebar_label: Go title: Go Connector --- -## 安装准备 +## 总体介绍 -Go 连接器支持的系统有: +driver-go 实现 Go [database/sql](https://golang.org/pkg/database/sql/) 包的 TDengine 驱动程序,同时提供通过本地的客户端驱动程序直接与服务端程序 taosd 进行订阅、 schemaless 写入和 stmt 功能。 -| **CPU 类型** | x64(64bit) | | | aarch64 | aarch32 | -| ------------ | ------------ | -------- | -------- | -------- | ---------- | -| **OS 类型** | Linux | Win64 | Win32 | Linux | Linux | -| **支持与否** | **支持** | **支持** | **支持** | **支持** | **支持** | +Go 连接器的源码托管在 github。项目名称:driver-go。欢迎 [贡献源码](https://github.com/taosdata/driver-go) 或 [报告问题](https://github.com/taosdata/driver-go/issues)。 -安装前准备:已安装好 TDengine 应用驱动,参考[安装连接器驱动步骤](/reference/connector)。 +## 支持的平台 -## 示例程序 +| **CPU 类型** | x64(64bit) | | | aarch64 | aarch32 | +|------------|------------|--------|--------|---------|---------| +| **OS 类型** | Linux | Win64 | Win32 | Linux | Linux | +| **支持与否** | **支持** | **支持** | **支持** | **支持** | **支持** | -使用 Go 连接器的示例代码请参考 [https://github.com/taosdata/TDengine/tree/develop/examples/go](https://github.com/taosdata/TDengine/tree/develop/examples/go) 以及[视频教程](https://www.taosdata.com/blog/2020/11/11/1951.html)。 +## 版本支持 -示例程序源码也位于安装目录下的 examples/go/taosdemo.go 文件中。 +| 分支 | 功能 | 建议 taosd 版本 | +|:-------:|:---------------------------------------------:|:-----------:| +| master | database/sql(cgo)、订阅、schemaless写入、stmt | 2.2.0.0 及以上 | +| develop | database/sql(cgo & REST)、订阅、schemaless写入、stmt | 2.4.0.4及以上 | -:::tip -建议 Go 版本是 1.13 及以上,并开启模块支持: -::: +## 支持的特性 -```sh -go env -w GO111MODULE=on -go env -w GOPROXY=https://goproxy.io,direct -``` +### 本地连接 -在 taosdemo.go 所在目录下进行编译和执行: +`本地连接` 指连接器通过本地的客户端驱动程序直接与服务端程序 taosd 建立连接。 -```sh -go mod init taosdemo -go get github.com/taosdata/driver-go/taosSql -# use win branch in Windows platform. -#go get github.com/taosdata/driver-go/taosSql@win -go build -./taosdemo -h fqdn -p serverPort -``` +* database/sql (cgo 模式) +* 订阅 +* schemaless +* stmt -## Go 连接器的使用 +### REST 连接 -TDengine 提供了 GO 驱动程序包`taosSql`。`taosSql` 实现了 GO 语言的内置接口 `database/sql/driver`。用户只需按如下方式引入包就可以在应用程序中访问 TDengine。 +REST 连接指连接器通过 taosAdapter 组件提供的 REST API 建立与 taosd 的连接。 -```go -import ( - "database/sql" - _ "github.com/taosdata/driver-go/v2/taosSql" -) -``` +`develop` 分支使用 `http client` 实现了 `database/sql` 接口。 -:::tip -下划线与双引号之间必须有一个空格。 +## 安装步骤 -::: +### 安装前的准备 -`taosSql` 的 v2 版本进行了重构,分离出内置数据库操作接口 `database/sql/driver` 到目录 `taosSql`;订阅、 stmt 等其他功能放到目录 `af`。 +* taos本地的客户端 +* Go 1.14 及以上 +* GCC 4.8.5 及以上 -## 常用 API +配置好环境变量,检查命令: -- `sql.Open(DRIVER_NAME string, dataSourceName string) *DB` +* ```go env``` +* ```gcc -v``` - 该 API 用来打开 DB,返回一个类型为\*DB 的对象,一般情况下,DRIVER_NAME 设置为字符串 `taosSql`,dataSourceName 设置为字符串 `user:password@/tcp(host:port)/dbname`,如果客户想要用多个 goroutine 并发访问 TDengine, 那么需要在各个 goroutine 中分别创建一个 sql.Open 对象并用之访问 TDengine。 +### 使用 go get 安装 - **注意**: 该 API 成功创建的时候,并没有做权限等检查,只有在真正执行 Query 或者 Exec 的时候才能真正的去创建连接,并同时检查 user/password/host/port 是不是合法。另外,由于整个驱动程序大部分实现都下沉到 taosSql 所依赖的 libtaos 动态库中。所以,sql.Open 本身特别轻量。 +`go get -u github.com/taosdata/driver-go/v2@develop` -- `func (db *DB) Exec(query string, args ...interface{}) (Result, error)` +## 建立连接 -sql.Open 内置的方法,用来执行非查询相关 SQL +### DSN -- `func (db *DB) Query(query string, args ...interface{}) (*Rows, error)` +数据源名称具有通用格式,例如 [PEAR DB](http://pear.php.net/manual/en/package.database.db.intro-dsn.php),但没有类型前缀(方括号表示可选): -sql.Open 内置的方法,用来执行查询语句 +``` text +[username[:password]@][protocol[(address)]]/[dbname][?param1=value1&...¶mN=valueN] +``` -- `func (db *DB) Prepare(query string) (*Stmt, error)` +完整形式的 DSN: - sql.Open 内置的方法,Prepare creates a prepared statement for later queries or executions. +```text +username:password@protocol(address)/dbname?param=value +``` -- `func (s *Stmt) Exec(args ...interface{}) (Result, error)` +### 建立本地连接 - sql.Open 内置的方法,executes a prepared statement with the given arguments and returns a Result summarizing the effect of the statement. +_taosSql_ 通过 cgo 实现了 Go 的 `database/sql/driver` 接口。只需要引入驱动就可以使用[`database/sql`](https://golang.org/pkg/database/sql/)的接口。 -- `func (s *Stmt) Query(args ...interface{}) (*Rows, error)` +使用 `taosSql` 作为 `driverName` 并且使用一个正确的 [DSN](#DSN) 作为 `dataSourceName`,DSN 支持的参数: - sql.Open 内置的方法,Query executes a prepared query statement with the given arguments and returns the query results as a \*Rows. +* configPath 指定 taos.cfg 目录 -- `func (s *Stmt) Close() error` +示例: - sql.Open 内置的方法,Close closes the statement. +```go +package main -## 其他代码示例 +import ( + "database/sql" + "fmt" -[Consume Messages from Kafka](https://github.com/taosdata/go-demo-kafka) 是一个通过 Go 语言实现消费 Kafka 队列写入 TDengine 的示例程序,也可以作为通过 Go 连接 TDengine 的写法参考。 + _ "github.com/taosdata/driver-go/v2/taosSql" +) -## Go RESTful 的使用 +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 连接 -```go restful -import ( - "database/sql" - _ "github.com/taosdata/driver-go/v2/taosRestful" -) -``` +_taosRestful_ 通过 `http client` 实现了 Go 的 `database/sql/driver` 接口。只需要引入驱动就可以使用[`database/sql`](https://golang.org/pkg/database/sql/)的接口。 -`go.mod ` 的文件 require 块使用  github.com/taosdata/driver-go/v2 develop  之后执行  `go mod tidy ` +使用 `taosRestful` 作为 `driverName` 并且使用一个正确的 [DSN](#DSN) 作为 `dataSourceName`,DSN 支持的参数: -`sql.Open `的 driverName 为  `taosRestful` +* `disableCompression` 是否接受压缩数据,默认为 true 不接受压缩数据,如果传输数据使用 gzip 压缩设置为 false。 +* `readBufferSize` 读取数据的缓存区大小默认为 4K(4096),当查询结果数据量多时可以适当调大该值。 -### DSN +示例: -格式为: +```go +package main -数据库用户名:数据库密码@连接方式(域名或 ip:端口)/[数据库][?参数] +import ( + "database/sql" + "fmt" -样例: + _ "github.com/taosdata/driver-go/v2/taosRestful" +) -`root:taosdata@http(localhost:6041)/test?readBufferSize=52428800` +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 + } +} +``` -参数: +## 示例程序 -`disableCompression` 是否接受压缩数据,默认为 true 不接受压缩数据,如果传输数据使用 gzip 压缩设置为 false。 +使用 Go 连接器的示例代码请参考: -`readBufferSize` 读取数据的缓存区大小默认为 4K(4096),当查询结果数据量多时可以适当调大该值。 +* [示例程序](https://github.com/taosdata/TDengine/tree/develop/examples/go) +* [视频教程](https://www.taosdata.com/blog/2020/11/11/1951.html)。 ### 使用限制 -由于 RESTful 接口无状态所以 `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`。 +由于 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 的其他查询或写入操作会报错。 -也可以将 db 名称放到 DSN 中,将 `root:taosdata@http(localhost:6041)/` 改为 `root:taosdata@http(localhost:6041)/test`,此方法在 TDengine 2.4.0.5 版本的 taosAdapter 开始支持。当指定的 db 不存在时执行 `create database` 语句不会报错,而执行针对该 db 的其他查询或写入操作会报错。完整示例如下: +完整示例如下: -```go restful demo +```go package main import ( @@ -182,30 +200,142 @@ func main() { ### 常见问题 -- 无法找到包`github.com/taosdata/driver-go/v2/taosRestful` +* 无法找到包 `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` - 将 `go.mod` 中 require 块对`github.com/taosdata/driver-go/v2`的引用改为`github.com/taosdata/driver-go/v2 develop`,之后执行 `go mod tidy`。 +设置表名。 -- stmt 相关接口崩溃 +* `func (stmt *InsertStmt) SetSubTableName(name string) error` - RESTful 不支持 stmt 相关接口,建议使用`db.Exec`和`db.Query`。 +设置子表名。 -- 使用 `use db` 语句后执行其他语句报错 `[0x217] Database not specified or available` +* `func (stmt *InsertStmt) BindParam(params []*param.Param, bindType *param.ColumnType) error` - 在 RESTful 接口中 SQL 语句的执行无上下文关联,使用 `use db` 语句不会生效,解决办法见上方使用限制章节。 +绑定多行数据。 -- 使用 taosSql 不报错使用 taosRestful 报错 `[0x217] Database not specified or available` +* `func (stmt *InsertStmt) AddBatch() error` - 因为 RESTful 接口无状态,使用 `use db` 语句不会生效,解决办法见上方使用限制章节。 +添加到批处理。 -- 升级 `github.com/taosdata/driver-go/v2/taosRestful` +* `func (stmt *InsertStmt) Execute() error` - 将 `go.mod` 文件中对 `github.com/taosdata/driver-go/v2` 的引用改为 `github.com/taosdata/driver-go/v2 develop`,之后执行 `go mod tidy`。 +执行 stmt。 -- readBufferSize 参数调大后无明显效果 +* `func (stmt *InsertStmt) GetAffectedRows() int` - readBufferSize 调大后会减少获取结果时 syscall 的调用。如果查询结果的数据量不大,修改该参数不会带来明显提升,如果该参数修改过大,瓶颈会在解析 JSON 数据。如果需要优化查询速度,需要根据实际情况调整该值来达到查询效果最优。 +获取受影响行数。 -- disableCompression 参数设置为 false 时查询效率降低 +* `func (stmt *InsertStmt) Close() error` - 当 disableCompression 参数设置为 false 时查询结果会 gzip 压缩后传输,拿到数据后要先进行 gzip 解压。 +结束 stmt。