Skip to content

TDengine
TDengine

taosdata / TDengine
1 年多 前同步成功

通知 1185
Star 22016
Fork 4786
TDengine
TDengine
未验证 提交 8549bd82 编写于 作者: W wade zhang 提交者： GitHub
浏览文件
操作

Merge pull request #14452 from taosdata/test/dingbo/doc-example-2.6 

test: improve docs example for go connector
上级 c2d37d0a 86e57c9e
隐藏空白更改
内联 并排
Showing with 168 addition and 183 deletion
docs/en/07-develop/01-connect/index.md
浏览文件 @ 8549bd82
...@@ -98,11 +98,7 @@ pip install git+https://github.com/taosdata/taos-connector-python.git ...@@ -98,11 +98,7 @@ pip install git+https://github.com/taosdata/taos-connector-python.git
Just need to add `driver-go` dependency in `go.mod` . Just need to add `driver-go` dependency in `go.mod` .
```go-mod title=go.mod ```go-mod title=go.mod
module goexample {{#include docs/examples/go/go.mod}}
go 1.17
require github.com/taosdata/driver-go/v2 develop
``` ```
:::note :::note
......
docs/en/14-reference/03-connector/go.mdx
浏览文件 @ 8549bd82
...@@ -5,15 +5,15 @@ sidebar_label: Go ...@@ -5,15 +5,15 @@ sidebar_label: Go
title: TDengine Go Connector title: TDengine Go Connector
--- ---
import Tabs from '@theme/Tabs'; import Tabs from "@theme/Tabs";
import TabItem from '@theme/TabItem'; import TabItem from "@theme/TabItem";
import Preparation from "./_preparation.mdx" import Preparation from "./_preparation.mdx";
import GoInsert from "../../07-develop/03-insert-data/_go_sql.mdx" import GoInsert from "../../07-develop/03-insert-data/_go_sql.mdx";
import GoInfluxLine from "../../07-develop/03-insert-data/_go_line.mdx" import GoInfluxLine from "../../07-develop/03-insert-data/_go_line.mdx";
import GoOpenTSDBTelnet from "../../07-develop/03-insert-data/_go_opts_telnet.mdx" import GoOpenTSDBTelnet from "../../07-develop/03-insert-data/_go_opts_telnet.mdx";
import GoOpenTSDBJson from "../../07-develop/03-insert-data/_go_opts_json.mdx" import GoOpenTSDBJson from "../../07-develop/03-insert-data/_go_opts_json.mdx";
import GoQuery from "../../07-develop/04-query-data/_go.mdx" import GoQuery from "../../07-develop/04-query-data/_go.mdx";
`driver-go` is the official Go language connector for TDengine. It implements the [database/sql](https://golang.org/pkg/database/sql/) package, the generic Go language interface to SQL databases. Go developers can use it to develop applications that access TDengine cluster data. `driver-go` is the official Go language connector for TDengine. It implements the [database/sql](https://golang.org/pkg/database/sql/) package, the generic Go language interface to SQL databases. Go developers can use it to develop applications that access TDengine cluster data.
...@@ -38,18 +38,18 @@ Please refer to [version support list](/reference/connector#version-support) ...@@ -38,18 +38,18 @@ Please refer to [version support list](/reference/connector#version-support)
A "native connection" is established by the connector directly to the TDengine instance via the TDengine client driver (taosc). The supported functional features are: A "native connection" is established by the connector directly to the TDengine instance via the TDengine client driver (taosc). The supported functional features are:
* Normal queries - Normal queries
* Continuous queries - Continuous queries
* Subscriptions - Subscriptions
* schemaless interface - schemaless interface
* parameter binding interface - parameter binding interface
### REST connection ### REST connection
A "REST connection" is a connection between the application and the TDengine instance via the REST API provided by the taosAdapter component. The following features are supported: A "REST connection" is a connection between the application and the TDengine instance via the REST API provided by the taosAdapter component. The following features are supported:
* General queries - General queries
* Continuous queries - Continuous queries
## Installation steps ## Installation steps
...@@ -60,44 +60,44 @@ A "REST connection" is a connection between the application and the TDengine ins ...@@ -60,44 +60,44 @@ A "REST connection" is a connection between the application and the TDengine ins
Configure the environment variables and check the command. Configure the environment variables and check the command.
* `go env` - `go env`
* `gcc -v` - `gcc -v`
### Use go get to install ### Use go get to install
``` ```
go get -u github.com/taosdata/driver-go/v2@develop go get -u github.com/taosdata/driver-go/v2@latest
``` ```
### Manage with go mod ### Manage with go mod
1. Initialize the project with the `go mod` command. 1. Initialize the project with the `go mod` command.
```text ```text
go mod init taos-demo go mod init taos-demo
``` ```
2. Introduce taosSql 2. Introduce taosSql
```go ```go
import ( import (
"database/sql" "database/sql"
_ "github.com/taosdata/driver-go/v2/taosSql" _ "github.com/taosdata/driver-go/v2/taosSql"
) )
``` ```
3. Update the dependency packages with `go mod tidy`. 3. Update the dependency packages with `go mod tidy`.
```text ```text
go mod tidy go mod tidy
``` ```
4. Run the program with `go run taos-demo` or compile the binary with the `go build` command. 4. Run the program with `go run taos-demo` or compile the binary with the `go build` command.
```text ```text
go run taos-demo go run taos-demo
go build go build
``` ```
## Create a connection ## Create a connection
...@@ -105,7 +105,7 @@ go get -u github.com/taosdata/driver-go/v2@develop ...@@ -105,7 +105,7 @@ go get -u github.com/taosdata/driver-go/v2@develop
Data source names have a standard format, e.g. [PEAR DB](http://pear.php.net/manual/en/package.database.db.intro-dsn.php), but no type prefix (square brackets indicate optionally): Data source names have a standard format, e.g. [PEAR DB](http://pear.php.net/manual/en/package.database.db.intro-dsn.php), but no type prefix (square brackets indicate optionally):
``` text ```text
[username[:password]@][protocol[(address)]]/[dbname][?param1=value1&... &paramN=valueN] [username[:password]@][protocol[(address)]]/[dbname][?param1=value1&... &paramN=valueN]
``` ```
...@@ -124,7 +124,7 @@ _taosSql_ implements Go's `database/sql/driver` interface via cgo. You can use t ...@@ -124,7 +124,7 @@ _taosSql_ implements Go's `database/sql/driver` interface via cgo. You can use t
Use `taosSql` as `driverName` and use a correct [DSN](#DSN) as `dataSourceName`, DSN supports the following parameters. Use `taosSql` as `driverName` and use a correct [DSN](#DSN) as `dataSourceName`, DSN supports the following parameters.
* configPath specifies the `taos.cfg` directory - configPath specifies the `taos.cfg` directory
Example. Example.
...@@ -155,8 +155,8 @@ _taosRestful_ implements Go's `database/sql/driver` interface via `http client`. ...@@ -155,8 +155,8 @@ _taosRestful_ implements Go's `database/sql/driver` interface via `http client`.
Use `taosRestful` as `driverName` and use a correct [DSN](#DSN) as `dataSourceName` with the following parameters supported by the DSN. Use `taosRestful` as `driverName` and use a correct [DSN](#DSN) as `dataSourceName` with the following parameters supported by the DSN.
* `disableCompression` whether to accept compressed data, default is true do not accept compressed data, set to false if transferring data using gzip compression. - `disableCompression` whether to accept compressed data, default is true do not accept compressed data, set to false if transferring data using gzip compression.
* `readBufferSize` The default size of the buffer for reading data is 4K (4096), which can be adjusted upwards when the query result has a lot of data. - `readBufferSize` The default size of the buffer for reading data is 4K (4096), which can be adjusted upwards when the query result has a lot of data.
Example. Example.
...@@ -179,6 +179,7 @@ func main() { ...@@ -179,6 +179,7 @@ func main() {
} }
} }
``` ```
</TabItem> </TabItem>
</Tabs> </Tabs>
...@@ -208,8 +209,8 @@ func main() { ...@@ -208,8 +209,8 @@ func main() {
### More sample programs ### More sample programs
* [sample program](https://github.com/taosdata/TDengine/tree/develop/examples/go) - [sample program](https://github.com/taosdata/TDengine/tree/develop/examples/go)
* [Video tutorial](https://www.taosdata.com/blog/2020/11/11/1951.html). - [Video tutorial](https://www.taosdata.com/blog/2020/11/11/1951.html).
## Usage limitations ## Usage limitations
...@@ -269,56 +270,52 @@ func main() { ...@@ -269,56 +270,52 @@ func main() {
## Frequently Asked Questions ## Frequently Asked Questions
1. Cannot find the package `github.com/taosdata/driver-go/v2/taosRestful` 1. bind interface in database/sql crashes
Change the `github.com/taosdata/driver-go/v2` line in the require block of the `go.mod` file to `github.com/taosdata/driver-go/v2 develop`, then execute `go mod tidy`.
2. bind interface in database/sql crashes
REST does not support parameter binding related interface. It is recommended to use `db.Exec` and `db.Query`. REST does not support parameter binding related interface. It is recommended to use `db.Exec` and `db.Query`.
3. error `[0x217] Database not specified or available` after executing other statements with `use db` statement 2. error `[0x217] Database not specified or available` after executing other statements with `use db` statement
The execution of SQL command in the REST interface is not contextual, so using `use db` statement will not work, see the usage restrictions section above. The execution of SQL command in the REST interface is not contextual, so using `use db` statement will not work, see the usage restrictions section above.
4. use `taosSql` without error but use `taosRestful` with error `[0x217] Database not specified or available` 3. use `taosSql` without error but use `taosRestful` with error `[0x217] Database not specified or available`
Because the REST interface is stateless, using the `use db` statement will not take effect. See the usage restrictions section above. Because the REST interface is stateless, using the `use db` statement will not take effect. See the usage restrictions section above.
5. Upgrade `github.com/taosdata/driver-go/v2/taosRestful` 4. Upgrade `github.com/taosdata/driver-go/v2/taosRestful`
Change the `github.com/taosdata/driver-go/v2` line in the `go.mod` file to `github.com/taosdata/driver-go/v2 develop`, then execute `go mod tidy`. Change the `github.com/taosdata/driver-go/v2` line in the `go.mod` file to `github.com/taosdata/driver-go/v2 develop`, then execute `go mod tidy`.
6. `readBufferSize` parameter has no significant effect after being increased 5. `readBufferSize` parameter has no significant effect after being increased
Increasing `readBufferSize` will reduce the number of `syscall` calls when fetching results. If the query result is smaller, modifying this parameter will not improve performance significantly. If you increase the parameter value too much, the bottleneck will be parsing JSON data. If you need to optimize the query speed, you must adjust the value based on the actual situation to achieve the best query performance. Increasing `readBufferSize` will reduce the number of `syscall` calls when fetching results. If the query result is smaller, modifying this parameter will not improve performance significantly. If you increase the parameter value too much, the bottleneck will be parsing JSON data. If you need to optimize the query speed, you must adjust the value based on the actual situation to achieve the best query performance.
7. `disableCompression` parameter is set to `false` when the query efficiency is reduced 6. `disableCompression` parameter is set to `false` when the query efficiency is reduced
When set `disableCompression` parameter to `false`, the query result will be compressed by `gzip` and then transmitted, so you have to decompress the data by `gzip` after getting it. When set `disableCompression` parameter to `false`, the query result will be compressed by `gzip` and then transmitted, so you have to decompress the data by `gzip` after getting it.
8. `go get` command can't get the package, or timeout to get the package 7. `go get` command can't get the package, or timeout to get the package
Set Go proxy `go env -w GOPROXY=https://goproxy.cn,direct`. Set Go proxy `go env -w GOPROXY=https://goproxy.cn,direct`.
## Common APIs ## Common APIs
### database/sql API ### database/sql API
* `sql.Open(DRIVER_NAME string, dataSourceName string) *DB` - `sql.Open(DRIVER_NAME string, dataSourceName string) *DB`
Use This API to open a DB, returning an object of type \*DB. Use This API to open a DB, returning an object of type \*DB.
:::info :::info
This API is created successfully without checking permissions, but only when you execute a Query or Exec, and check if user/password/host/port is legal. This API is created successfully without checking permissions, but only when you execute a Query or Exec, and check if user/password/host/port is legal.
::: :::
* `func (db *DB) Exec(query string, args . .interface{}) (Result, error)` - `func (db *DB) Exec(query string, args . .interface{}) (Result, error)`
`sql.Open` built-in method to execute non-query related SQL. `sql.Open` built-in method to execute non-query related SQL.
* `func (db *DB) Query(query string, args ... . interface{}) (*Rows, error)` - `func (db *DB) Query(query string, args ... . interface{}) (*Rows, error)`
`sql.Open` Built-in method to execute query statements. `sql.Open` Built-in method to execute query statements.
...@@ -328,85 +325,85 @@ The `af` package encapsulates TDengine advanced functions such as connection man ...@@ -328,85 +325,85 @@ The `af` package encapsulates TDengine advanced functions such as connection man
#### Connection management #### Connection management
* `af.Open(host, user, pass, db string, port int) (*Connector, error)` - `af.Open(host, user, pass, db string, port int) (*Connector, error)`
This API creates a connection to taosd via cgo. This API creates a connection to taosd via cgo.
* `func (conn *Connector) Close() error` - `func (conn *Connector) Close() error`
Closes the connection. Closes the connection.
#### Subscribe to #### Subscribe to
* `func (conn *Connector) Subscribe(restart bool, topic string, sql string, interval time.Duration) (Subscriber, error)` - `func (conn *Connector) Subscribe(restart bool, topic string, sql string, interval time.Duration) (Subscriber, error)`
Subscribe to data. Subscribe to data.
* `func (s *taosSubscriber) Consume() (driver.Rows, error)` - `func (s *taosSubscriber) Consume() (driver.Rows, error)`
Consume the subscription data, returning the `Rows` structure of the `database/sql/driver` package. Consume the subscription data, returning the `Rows` structure of the `database/sql/driver` package.
* `func (s *taosSubscriber) Unsubscribe(keepProgress bool)` - `func (s *taosSubscriber) Unsubscribe(keepProgress bool)`
Unsubscribe from data. Unsubscribe from data.
#### schemaless #### schemaless
* `func (conn *Connector) InfluxDBInsertLines(lines []string, precision string) error` - `func (conn *Connector) InfluxDBInsertLines(lines []string, precision string) error`
Write to influxDB line protocol. Write to influxDB line protocol.
* `func (conn *Connector) OpenTSDBInsertTelnetLines(lines []string) error` - `func (conn *Connector) OpenTSDBInsertTelnetLines(lines []string) error`
Write OpenTDSB telnet protocol data. Write OpenTDSB telnet protocol data.
* `func (conn *Connector) OpenTSDBInsertJsonPayload(payload string) error` - `func (conn *Connector) OpenTSDBInsertJsonPayload(payload string) error`
Writes OpenTSDB JSON protocol data. Writes OpenTSDB JSON protocol data.
#### parameter binding #### parameter binding
* `func (conn *Connector) StmtExecute(sql string, params *param.Param) (res driver.Result, err error)` - `func (conn *Connector) StmtExecute(sql string, params *param.Param) (res driver.Result, err error)`
Parameter bound single row insert. Parameter bound single row insert.
* `func (conn *Connector) StmtQuery(sql string, params *param.Param) (rows driver.Rows, err error)` - `func (conn *Connector) StmtQuery(sql string, params *param.Param) (rows driver.Rows, err error)`
Parameter bound query that returns the `Rows` structure of the `database/sql/driver` package. Parameter bound query that returns the `Rows` structure of the `database/sql/driver` package.
* `func (conn *Connector) InsertStmt() *insertstmt. - `func (conn *Connector) InsertStmt() *insertstmt.
Initialize the parameters. Initialize the parameters.
* `func (stmt *InsertStmt) Prepare(sql string) error` - `func (stmt *InsertStmt) Prepare(sql string) error`
Parameter binding preprocessing SQL statement. Parameter binding preprocessing SQL statement.
* `func (stmt *InsertStmt) SetTableName(name string) error` - `func (stmt *InsertStmt) SetTableName(name string) error`
Bind the set table name parameter. Bind the set table name parameter.
* `func (stmt *InsertStmt) SetSubTableName(name string) error` - `func (stmt *InsertStmt) SetSubTableName(name string) error`
Parameter binding to set the sub table name. Parameter binding to set the sub table name.
* `func (stmt *InsertStmt) BindParam(params []*param.Param, bindType *param.ColumnType) error` - `func (stmt *InsertStmt) BindParam(params []*param.Param, bindType *param.ColumnType) error`
Parameter bind multiple rows of data. Parameter bind multiple rows of data.
* `func (stmt *InsertStmt) AddBatch() error` - `func (stmt *InsertStmt) AddBatch() error`
Add to a parameter-bound batch. Add to a parameter-bound batch.
* `func (stmt *InsertStmt) Execute() error` - `func (stmt *InsertStmt) Execute() error`
Execute a parameter binding. Execute a parameter binding.
* `func (stmt *InsertStmt) GetAffectedRows() int` - `func (stmt *InsertStmt) GetAffectedRows() int`
Gets the number of affected rows inserted by the parameter binding. Gets the number of affected rows inserted by the parameter binding.
* `func (stmt *InsertStmt) Close() error` - `func (stmt *InsertStmt) Close() error`
Closes the parameter binding. Closes the parameter binding.
......
docs/examples/.gitignore
浏览文件 @ 8549bd82
.vscode .vscode
*.lock *.lock
.idea .idea
\ No newline at end of file .env
\ No newline at end of file
docs/examples/.gitignre 已删除 100644 → 0
浏览文件 @ c2d37d0a
.vscode
*.lock
\ No newline at end of file
docs/examples/go/go.mod
浏览文件 @ 8549bd82
...@@ -2,5 +2,4 @@ module goexample ...@@ -2,5 +2,4 @@ module goexample
go 1.17 go 1.17
require github.com/taosdata/driver-go/v2 develop require github.com/taosdata/driver-go/v2 latest
docs/zh/07-develop/01-connect/index.md
浏览文件 @ 8549bd82
...@@ -99,11 +99,7 @@ pip install git+https://github.com/taosdata/taos-connector-python.git ...@@ -99,11 +99,7 @@ pip install git+https://github.com/taosdata/taos-connector-python.git
编辑 `go.mod` 添加 `driver-go` 依赖即可。 编辑 `go.mod` 添加 `driver-go` 依赖即可。
```go-mod title=go.mod ```go-mod title=go.mod
module goexample {{#include docs/examples/go/go.mod}}
go 1.17
require github.com/taosdata/driver-go/v2 develop
``` ```
:::note :::note
......
docs/zh/14-reference/03-connector/go.mdx
浏览文件 @ 8549bd82
...@@ -5,15 +5,15 @@ sidebar_label: Go ...@@ -5,15 +5,15 @@ sidebar_label: Go
title: TDengine Go Connector title: TDengine Go Connector
--- ---
import Tabs from '@theme/Tabs'; import Tabs from "@theme/Tabs";
import TabItem from '@theme/TabItem'; import TabItem from "@theme/TabItem";
import Preparition from "./_preparition.mdx" import Preparition from "./_preparition.mdx";
import GoInsert from "../../07-develop/03-insert-data/_go_sql.mdx" import GoInsert from "../../07-develop/03-insert-data/_go_sql.mdx";
import GoInfluxLine from "../../07-develop/03-insert-data/_go_line.mdx" import GoInfluxLine from "../../07-develop/03-insert-data/_go_line.mdx";
import GoOpenTSDBTelnet from "../../07-develop/03-insert-data/_go_opts_telnet.mdx" import GoOpenTSDBTelnet from "../../07-develop/03-insert-data/_go_opts_telnet.mdx";
import GoOpenTSDBJson from "../../07-develop/03-insert-data/_go_opts_json.mdx" import GoOpenTSDBJson from "../../07-develop/03-insert-data/_go_opts_json.mdx";
import GoQuery from "../../07-develop/04-query-data/_go.mdx" import GoQuery from "../../07-develop/04-query-data/_go.mdx";
`driver-go` 是 TDengine 的官方 Go 语言连接器，实现了 Go 语言[ database/sql ](https://golang.org/pkg/database/sql/) 包的接口。Go 开发人员可以通过它开发存取 TDengine 集群数据的应用软件。 `driver-go` 是 TDengine 的官方 Go 语言连接器，实现了 Go 语言[ database/sql ](https://golang.org/pkg/database/sql/) 包的接口。Go 开发人员可以通过它开发存取 TDengine 集群数据的应用软件。
...@@ -38,64 +38,64 @@ REST 连接支持所有能运行 Go 的平台。 ...@@ -38,64 +38,64 @@ REST 连接支持所有能运行 Go 的平台。
“原生连接”指连接器通过 TDengine 客户端驱动（taosc）直接与 TDengine 运行实例建立的连接。支持的功能特性有： “原生连接”指连接器通过 TDengine 客户端驱动（taosc）直接与 TDengine 运行实例建立的连接。支持的功能特性有：
* 普通查询 - 普通查询
* 连续查询 - 连续查询
* 订阅 - 订阅
* schemaless 接口 - schemaless 接口
* 参数绑定接口 - 参数绑定接口
### REST 连接 ### REST 连接
"REST 连接"指连接器通过 taosAdapter 组件提供的 REST API 与 TDengine 运行实例建立的连接。支持的功能特性有： "REST 连接"指连接器通过 taosAdapter 组件提供的 REST API 与 TDengine 运行实例建立的连接。支持的功能特性有：
* 普通查询 - 普通查询
* 连续查询 - 连续查询
## 安装步骤 ## 安装步骤
### 安装前准备 ### 安装前准备
* 安装 Go 开发环境（Go 1.14 及以上，GCC 4.8.5 及以上） - 安装 Go 开发环境（Go 1.14 及以上，GCC 4.8.5 及以上）
* 如果使用原生连接器，请安装 TDengine 客户端驱动，具体步骤请参考[安装客户端驱动](/reference/connector#安装客户端驱动) - 如果使用原生连接器，请安装 TDengine 客户端驱动，具体步骤请参考[安装客户端驱动](/reference/connector#安装客户端驱动)
配置好环境变量，检查命令： 配置好环境变量，检查命令：
* ```go env``` - `go env`
* ```gcc -v``` - `gcc -v`
### 使用 go get 安装 ### 使用 go get 安装
`go get -u github.com/taosdata/driver-go/v2@develop` `go get -u github.com/taosdata/driver-go/v2@latest`
### 使用 go mod 管理 ### 使用 go mod 管理
1. 使用 `go mod` 命令初始化项目： 1. 使用 `go mod` 命令初始化项目：
```text ```text
go mod init taos-demo go mod init taos-demo
``` ```
2. 引入 taosSql ： 2. 引入 taosSql ：
```go ```go
import ( import (
"database/sql" "database/sql"
_ "github.com/taosdata/driver-go/v2/taosSql" _ "github.com/taosdata/driver-go/v2/taosSql"
) )
``` ```
3. 使用 `go mod tidy` 更新依赖包： 3. 使用 `go mod tidy` 更新依赖包：
```text ```text
go mod tidy go mod tidy
``` ```
4. 使用 `go run taos-demo` 运行程序或使用 `go build` 命令编译出二进制文件。 4. 使用 `go run taos-demo` 运行程序或使用 `go build` 命令编译出二进制文件。
```text ```text
go run taos-demo go run taos-demo
go build go build
``` ```
## 建立连接 ## 建立连接
...@@ -103,7 +103,7 @@ REST 连接支持所有能运行 Go 的平台。 ...@@ -103,7 +103,7 @@ REST 连接支持所有能运行 Go 的平台。
数据源名称具有通用格式，例如 [PEAR DB](http://pear.php.net/manual/en/package.database.db.intro-dsn.php)，但没有类型前缀（方括号表示可选）： 数据源名称具有通用格式，例如 [PEAR DB](http://pear.php.net/manual/en/package.database.db.intro-dsn.php)，但没有类型前缀（方括号表示可选）：
``` text ```text
[username[:password]@][protocol[(address)]]/[dbname][?param1=value1&...&paramN=valueN] [username[:password]@][protocol[(address)]]/[dbname][?param1=value1&...&paramN=valueN]
``` ```
...@@ -112,6 +112,7 @@ REST 连接支持所有能运行 Go 的平台。 ...@@ -112,6 +112,7 @@ REST 连接支持所有能运行 Go 的平台。
```text ```text
username:password@protocol(address)/dbname?param=value username:password@protocol(address)/dbname?param=value
``` ```
### 使用连接器进行连接 ### 使用连接器进行连接
<Tabs defaultValue="native"> <Tabs defaultValue="native">
...@@ -121,7 +122,7 @@ _taosSql_ 通过 cgo 实现了 Go 的 `database/sql/driver` 接口。只需要 ...@@ -121,7 +122,7 @@ _taosSql_ 通过 cgo 实现了 Go 的 `database/sql/driver` 接口。只需要
使用 `taosSql` 作为 `driverName` 并且使用一个正确的 [DSN](#DSN) 作为 `dataSourceName`，DSN 支持的参数： 使用 `taosSql` 作为 `driverName` 并且使用一个正确的 [DSN](#DSN) 作为 `dataSourceName`，DSN 支持的参数：
* configPath 指定 taos.cfg 目录 - configPath 指定 taos.cfg 目录
示例： 示例：
...@@ -152,8 +153,8 @@ _taosRestful_ 通过 `http client` 实现了 Go 的 `database/sql/driver` 接口 ...@@ -152,8 +153,8 @@ _taosRestful_ 通过 `http client` 实现了 Go 的 `database/sql/driver` 接口
使用 `taosRestful` 作为 `driverName` 并且使用一个正确的 [DSN](#DSN) 作为 `dataSourceName`，DSN 支持的参数： 使用 `taosRestful` 作为 `driverName` 并且使用一个正确的 [DSN](#DSN) 作为 `dataSourceName`，DSN 支持的参数：
* `disableCompression` 是否接受压缩数据，默认为 true 不接受压缩数据，如果传输数据使用 gzip 压缩设置为 false。 - `disableCompression` 是否接受压缩数据，默认为 true 不接受压缩数据，如果传输数据使用 gzip 压缩设置为 false。
* `readBufferSize` 读取数据的缓存区大小默认为 4K（4096），当查询结果数据量多时可以适当调大该值。 - `readBufferSize` 读取数据的缓存区大小默认为 4K（4096），当查询结果数据量多时可以适当调大该值。
示例： 示例：
...@@ -176,6 +177,7 @@ func main() { ...@@ -176,6 +177,7 @@ func main() {
} }
} }
``` ```
</TabItem> </TabItem>
</Tabs> </Tabs>
...@@ -205,8 +207,8 @@ func main() { ...@@ -205,8 +207,8 @@ func main() {
### 更多示例程序 ### 更多示例程序
* [示例程序](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)。 - [视频教程](https://www.taosdata.com/blog/2020/11/11/1951.html)。
## 使用限制 ## 使用限制
...@@ -266,55 +268,51 @@ func main() { ...@@ -266,55 +268,51 @@ func main() {
## 常见问题 ## 常见问题
1. 无法找到包 `github.com/taosdata/driver-go/v2/taosRestful` 1. database/sql 中 stmt（参数绑定）相关接口崩溃
将 `go.mod` 中 require 块对`github.com/taosdata/driver-go/v2`的引用改为`github.com/taosdata/driver-go/v2 develop`，之后执行 `go mod tidy`。
2. database/sql 中 stmt（参数绑定）相关接口崩溃
REST 不支持参数绑定相关接口，建议使用`db.Exec`和`db.Query`。 REST 不支持参数绑定相关接口，建议使用`db.Exec`和`db.Query`。
3. 使用 `use db` 语句后执行其他语句报错 `[0x217] Database not specified or available` 2. 使用 `use db` 语句后执行其他语句报错 `[0x217] Database not specified or available`
在 REST 接口中 SQL 语句的执行无上下文关联，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。 在 REST 接口中 SQL 语句的执行无上下文关联，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。
4. 使用 taosSql 不报错使用 taosRestful 报错 `[0x217] Database not specified or available` 3. 使用 taosSql 不报错使用 taosRestful 报错 `[0x217] Database not specified or available`
因为 REST 接口无状态，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。 因为 REST 接口无状态，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。
5. 升级 `github.com/taosdata/driver-go/v2/taosRestful` 4. 升级 `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`。 将 `go.mod` 文件中对 `github.com/taosdata/driver-go/v2` 的引用改为 `github.com/taosdata/driver-go/v2 develop`，之后执行 `go mod tidy`。
6. `readBufferSize` 参数调大后无明显效果 5. `readBufferSize` 参数调大后无明显效果
`readBufferSize` 调大后会减少获取结果时 `syscall` 的调用。如果查询结果的数据量不大，修改该参数不会带来明显提升，如果该参数修改过大，瓶颈会在解析 JSON 数据。如果需要优化查询速度，需要根据实际情况调整该值来达到查询效果最优。 `readBufferSize` 调大后会减少获取结果时 `syscall` 的调用。如果查询结果的数据量不大，修改该参数不会带来明显提升，如果该参数修改过大，瓶颈会在解析 JSON 数据。如果需要优化查询速度，需要根据实际情况调整该值来达到查询效果最优。
7. `disableCompression` 参数设置为 `false` 时查询效率降低 6. `disableCompression` 参数设置为 `false` 时查询效率降低
当 `disableCompression` 参数设置为 `false` 时查询结果会使用 `gzip` 压缩后传输，拿到数据后要先进行 `gzip` 解压。 当 `disableCompression` 参数设置为 `false` 时查询结果会使用 `gzip` 压缩后传输，拿到数据后要先进行 `gzip` 解压。
8. `go get` 命令无法获取包，或者获取包超时 7. `go get` 命令无法获取包，或者获取包超时
设置 Go 代理 `go env -w GOPROXY=https://goproxy.cn,direct`。 设置 Go 代理 `go env -w GOPROXY=https://goproxy.cn,direct`。
## 常用 API ## 常用 API
### database/sql API ### database/sql API
* `sql.Open(DRIVER_NAME string, dataSourceName string) *DB` - `sql.Open(DRIVER_NAME string, dataSourceName string) *DB`
该 API 用来打开 DB，返回一个类型为 \*DB 的对象。 该 API 用来打开 DB，返回一个类型为 \*DB 的对象。
:::info :::info
该 API 成功创建的时候，并没有做权限等检查，只有在真正执行 Query 或者 Exec 的时候才能真正的去创建连接，并同时检查 user/password/host/port 是不是合法。 该 API 成功创建的时候，并没有做权限等检查，只有在真正执行 Query 或者 Exec 的时候才能真正的去创建连接，并同时检查 user/password/host/port 是不是合法。
::: :::
* `func (db *DB) Exec(query string, args ...interface{}) (Result, error)` - `func (db *DB) Exec(query string, args ...interface{}) (Result, error)`
`sql.Open` 内置的方法，用来执行非查询相关 SQL。 `sql.Open` 内置的方法，用来执行非查询相关 SQL。
* `func (db *DB) Query(query string, args ...interface{}) (*Rows, error)` - `func (db *DB) Query(query string, args ...interface{}) (*Rows, error)`
`sql.Open` 内置的方法，用来执行查询语句。 `sql.Open` 内置的方法，用来执行查询语句。
...@@ -324,85 +322,85 @@ func main() { ...@@ -324,85 +322,85 @@ func main() {
#### 连接管理 #### 连接管理
* `af.Open(host, user, pass, db string, port int) (*Connector, error)` - `af.Open(host, user, pass, db string, port int) (*Connector, error)`
该 API 通过 cgo 创建与 taosd 的连接。 该 API 通过 cgo 创建与 taosd 的连接。
* `func (conn *Connector) Close() error` - `func (conn *Connector) Close() error`
关闭与 taosd 的连接。 关闭与 taosd 的连接。
#### 订阅 #### 订阅
* `func (conn *Connector) Subscribe(restart bool, topic string, sql string, interval time.Duration) (Subscriber, error)` - `func (conn *Connector) Subscribe(restart bool, topic string, sql string, interval time.Duration) (Subscriber, error)`
订阅数据。 订阅数据。
* `func (s *taosSubscriber) Consume() (driver.Rows, error)` - `func (s *taosSubscriber) Consume() (driver.Rows, error)`
消费订阅数据，返回 `database/sql/driver` 包的 `Rows` 结构。 消费订阅数据，返回 `database/sql/driver` 包的 `Rows` 结构。
* `func (s *taosSubscriber) Unsubscribe(keepProgress bool)` - `func (s *taosSubscriber) Unsubscribe(keepProgress bool)`
取消订阅数据。 取消订阅数据。
#### schemaless #### schemaless
* `func (conn *Connector) InfluxDBInsertLines(lines []string, precision string) error` - `func (conn *Connector) InfluxDBInsertLines(lines []string, precision string) error`
写入 influxDB 行协议。 写入 influxDB 行协议。
* `func (conn *Connector) OpenTSDBInsertTelnetLines(lines []string) error` - `func (conn *Connector) OpenTSDBInsertTelnetLines(lines []string) error`
写入 OpenTDSB telnet 协议数据。 写入 OpenTDSB telnet 协议数据。
* `func (conn *Connector) OpenTSDBInsertJsonPayload(payload string) error` - `func (conn *Connector) OpenTSDBInsertJsonPayload(payload string) error`
写入 OpenTSDB JSON 协议数据。 写入 OpenTSDB JSON 协议数据。
#### 参数绑定 #### 参数绑定
* `func (conn *Connector) StmtExecute(sql string, params *param.Param) (res driver.Result, err error)` - `func (conn *Connector) StmtExecute(sql string, params *param.Param) (res driver.Result, err error)`
参数绑定单行插入。 参数绑定单行插入。
* `func (conn *Connector) StmtQuery(sql string, params *param.Param) (rows driver.Rows, err error)` - `func (conn *Connector) StmtQuery(sql string, params *param.Param) (rows driver.Rows, err error)`
参数绑定查询，返回 `database/sql/driver` 包的 `Rows` 结构。 参数绑定查询，返回 `database/sql/driver` 包的 `Rows` 结构。
* `func (conn *Connector) InsertStmt() *insertstmt.InsertStmt` - `func (conn *Connector) InsertStmt() *insertstmt.InsertStmt`
初始化参数。 初始化参数。
* `func (stmt *InsertStmt) Prepare(sql string) error` - `func (stmt *InsertStmt) Prepare(sql string) error`
参数绑定预处理 SQL 语句。 参数绑定预处理 SQL 语句。
* `func (stmt *InsertStmt) SetTableName(name string) error` - `func (stmt *InsertStmt) SetTableName(name string) error`
参数绑定设置表名。 参数绑定设置表名。
* `func (stmt *InsertStmt) SetSubTableName(name string) error` - `func (stmt *InsertStmt) SetSubTableName(name string) error`
参数绑定设置子表名。 参数绑定设置子表名。
* `func (stmt *InsertStmt) BindParam(params []*param.Param, bindType *param.ColumnType) error` - `func (stmt *InsertStmt) BindParam(params []*param.Param, bindType *param.ColumnType) error`
参数绑定多行数据。 参数绑定多行数据。
* `func (stmt *InsertStmt) AddBatch() error` - `func (stmt *InsertStmt) AddBatch() error`
添加到参数绑定批处理。 添加到参数绑定批处理。
* `func (stmt *InsertStmt) Execute() error` - `func (stmt *InsertStmt) Execute() error`
执行参数绑定。 执行参数绑定。
* `func (stmt *InsertStmt) GetAffectedRows() int` - `func (stmt *InsertStmt) GetAffectedRows() int`
获取参数绑定插入受影响行数。 获取参数绑定插入受影响行数。
* `func (stmt *InsertStmt) Close() error` - `func (stmt *InsertStmt) Close() error`
结束参数绑定。 结束参数绑定。
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或