TDengine Go Connector

driver-go is the official Go language connector for TDengine. It implements the 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 provides two ways to establish connections. One is native connection, which connects to TDengine instances natively through the TDengine client driver (taosc), supporting data writing, querying, subscriptions, schemaless writing, and bind interface. The other is the REST connection, which connects to TDengine instances via the REST interface provided by taosAdapter. The set of features implemented by the REST connection differs slightly from those implemented by the native connection.

This article describes how to install driver-go and connect to TDengine clusters and perform basic operations such as data query and data writing through driver-go.

The source code of driver-go is hosted on GitHub.

Supported platforms

Native connections are supported on the same platforms as the TDengine client driver. REST connections are supported on all platforms that can run Go.

Version support

Please refer to version support list

Supported features

Native connections

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
  • Continuous queries
  • Subscriptions
  • Schemaless interface
  • Parameter binding interface

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:

  • Normal queries
  • Continuous queries

Installation Steps

Pre-installation preparation

  • Install Go development environment (Go 1.14 and above, GCC 4.8.5 and above)

  • If you use the native connector, please install the TDengine client driver. Please refer to Install Client Driver for specific steps

Configure the environment variables and check the command.

  • go env
  • gcc -v

Use go get to install

go get -u github.com/taosdata/driver-go/v3@latest

Manage with go mod

  1. Initialize the project with the go mod command.

    1. go mod init taos-demo

  2. Introduce taosSql

    1. import (
    2.   "database/sql"
    3.   _ "github.com/taosdata/driver-go/v3/taosSql"
    4. )

  3. Update the dependency packages with go mod tidy.

    1. go mod tidy

  4. Run the program with go run taos-demo or compile the binary with the go build command.

    1. go run taos-demo
    2. go build

Establishing a connection

Data source name (DSN)

Data source names have a standard format, e.g. PEAR DB, but no type prefix (square brackets indicate optionally):

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

DSN in full form.

  1. username:password@protocol(address)/dbname?param=value

Connecting via connector

  • native connection
  • REST connection
  • WebSocket connection

taosSql implements Go’s database/sql/driver interface via cgo. You can use the database/sql interface by simply introducing the driver.

Use taosSql as driverName and use a correct DSN as dataSourceName, DSN supports the following parameters.

  • configPath specifies the taos.cfg directory

For example:

  1. package main
  3. import (
  4.     "database/sql"
  5.     "fmt"
  7.     _ "github.com/taosdata/driver-go/v3/taosSql"
  8. )
  10. func main() {
  11.     var taosUri = "root:taosdata@tcp(localhost:6030)/"
  12.     taos, err := sql.Open("taosSql", taosUri)
  13.     if err != nil {
  14.         fmt.Println("failed to connect TDengine, err:", err)
  15.         return
  16.     }
  17. }

taosRestful implements Go’s database/sql/driver interface via http client. You can use the database/sql interface by simply introducing the driver.

Use taosRestful as driverName and use a correct 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.
  • 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.

For example:

  1. package main
  3. import (
  4.     "database/sql"
  5.     "fmt"
  7.     _ "github.com/taosdata/driver-go/v3/taosRestful"
  8. )
  10. func main() {
  11.     var taosUri = "root:taosdata@http(localhost:6041)/"
  12.     taos, err := sql.Open("taosRestful", taosUri)
  13.     if err != nil {
  14.         fmt.Println("failed to connect TDengine, err:", err)
  15.         return
  16.     }
  17. }

taosRestful implements Go’s database/sql/driver interface via http client. You can use the database/sql interface by simply introducing the driver (driver-go minimum version 3.0.2).

Use taosWS as driverName and use a correct DSN as dataSourceName with the following parameters supported by the DSN.

  • writeTimeout The timeout to send data via WebSocket.
  • readTimeout The timeout to receive response data via WebSocket.

For example:

  1. package main
  3. import (
  4.     "database/sql"
  5.     "fmt"
  7.     _ "github.com/taosdata/driver-go/v3/taosWS"
  8. )
  10. func main() {
  11.     var taosUri = "root:taosdata@ws(localhost:6041)/"
  12.     taos, err := sql.Open("taosWS", taosUri)
  13.     if err != nil {
  14.         fmt.Println("failed to connect TDengine, err:", err)
  15.         return
  16.     }
  17. }

Usage examples

Write data

SQL Write

  1. package main
  3. import (
  4.     "database/sql"
  5.     "fmt"
  6.     "log"
  8.     _ "github.com/taosdata/driver-go/v3/taosRestful"
  9. )
  11. func createStable(taos *sql.DB) {
  12.     _, err := taos.Exec("CREATE DATABASE power")
  13.     if err != nil {
  14.         log.Fatalln("failed to create database, err:", err)
  15.     }
  16.     _, err = taos.Exec("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)")
  17.     if err != nil {
  18.         log.Fatalln("failed to create stable, err:", err)
  19.     }
  20. }
  22. func insertData(taos *sql.DB) {
  23.     sql := `INSERT INTO power.d1001 USING power.meters TAGS('California.SanFrancisco', 2) VALUES ('2018-10-03 14:38:05.000', 10.30000, 219, 0.31000) ('2018-10-03 14:38:15.000', 12.60000, 218, 0.33000) ('2018-10-03 14:38:16.800', 12.30000, 221, 0.31000)
  24.     power.d1002 USING power.meters TAGS('California.SanFrancisco', 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)
  25.     power.d1003 USING power.meters TAGS('California.LosAngeles', 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000)
  26.     power.d1004 USING power.meters TAGS('California.LosAngeles', 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)`
  27.     result, err := taos.Exec(sql)
  28.     if err != nil {
  29.         log.Fatalln("failed to insert, err:", err)
  30.     }
  31.     rowsAffected, err := result.RowsAffected()
  32.     if err != nil {
  33.         log.Fatalln("failed to get affected rows, err:", err)
  34.     }
  35.     fmt.Println("RowsAffected", rowsAffected)
  36. }
  38. func main() {
  39.     var taosDSN = "root:taosdata@http(localhost:6041)/"
  40.     taos, err := sql.Open("taosRestful", taosDSN)
  41.     if err != nil {
  42.         log.Fatalln("failed to connect TDengine, err:", err)
  43.     }
  44.     defer taos.Close()
  45.     createStable(taos)
  46.     insertData(taos)
  47. }

view source code

InfluxDB line protocol write

  1. package main
  3. import (
  4.     "fmt"
  5.     "log"
  7.     "github.com/taosdata/driver-go/v3/af"
  8. )
  10. func prepareDatabase(conn *af.Connector) {
  11.     _, err := conn.Exec("CREATE DATABASE test")
  12.     if err != nil {
  13.         panic(err)
  14.     }
  15.     _, err = conn.Exec("USE test")
  16.     if err != nil {
  17.         panic(err)
  18.     }
  19. }
  21. func main() {
  22.     conn, err := af.Open("localhost", "root", "taosdata", "", 6030)
  23.     if err != nil {
  24.         fmt.Println("fail to connect, err:", err)
  25.     }
  26.     defer conn.Close()
  27.     prepareDatabase(conn)
  28.     var lines = []string{
  29.         "meters,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249",
  30.         "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250",
  31.         "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249",
  32.         "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250",
  33.     }
  35.     err = conn.InfluxDBInsertLines(lines, "ms")
  36.     if err != nil {
  37.         log.Fatalln("insert error:", err)
  38.     }
  39. }

view source code

OpenTSDB Telnet line protocol write

  1. package main
  3. import (
  4.     "log"
  6.     "github.com/taosdata/driver-go/v3/af"
  7. )
  9. func prepareDatabase(conn *af.Connector) {
  10.     _, err := conn.Exec("CREATE DATABASE test")
  11.     if err != nil {
  12.         panic(err)
  13.     }
  14.     _, err = conn.Exec("USE test")
  15.     if err != nil {
  16.         panic(err)
  17.     }
  18. }
  20. func main() {
  21.     conn, err := af.Open("localhost", "root", "taosdata", "", 6030)
  22.     if err != nil {
  23.         log.Fatalln("fail to connect, err:", err)
  24.     }
  25.     defer conn.Close()
  26.     prepareDatabase(conn)
  27.     var lines = []string{
  28.         "meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2",
  29.         "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2",
  30.         "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3",
  31.         "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3",
  32.         "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2",
  33.         "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2",
  34.         "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3",
  35.         "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3",
  36.     }
  38.     err = conn.OpenTSDBInsertTelnetLines(lines)
  39.     if err != nil {
  40.         log.Fatalln("insert error:", err)
  41.     }
  42. }

view source code

OpenTSDB JSON line protocol write

  1. package main
  3. import (
  4.     "log"
  6.     "github.com/taosdata/driver-go/v3/af"
  7. )
  9. func prepareDatabase(conn *af.Connector) {
  10.     _, err := conn.Exec("CREATE DATABASE test")
  11.     if err != nil {
  12.         panic(err)
  13.     }
  14.     _, err = conn.Exec("USE test")
  15.     if err != nil {
  16.         panic(err)
  17.     }
  18. }
  20. func main() {
  21.     conn, err := af.Open("localhost", "root", "taosdata", "", 6030)
  22.     if err != nil {
  23.         log.Fatalln("fail to connect, err:", err)
  24.     }
  25.     defer conn.Close()
  26.     prepareDatabase(conn)
  28.     payload := `[{"metric": "meters.current", "timestamp": 1648432611249, "value": 10.3, "tags": {"location": "California.SanFrancisco", "groupid": 2}},
  29.                 {"metric": "meters.voltage", "timestamp": 1648432611249, "value": 219, "tags": {"location": "California.LosAngeles", "groupid": 1}},
  30.                 {"metric": "meters.current", "timestamp": 1648432611250, "value": 12.6, "tags": {"location": "California.SanFrancisco", "groupid": 2}},
  31.                 {"metric": "meters.voltage", "timestamp": 1648432611250, "value": 221, "tags": {"location": "California.LosAngeles", "groupid": 1}}]`
  33.     err = conn.OpenTSDBInsertJsonPayload(payload)
  34.     if err != nil {
  35.         log.Fatalln("insert error:", err)
  36.     }
  37. }

view source code

Query data

  1. package main
  3. import (
  4.     "database/sql"
  5.     "log"
  6.     "time"
  8.     _ "github.com/taosdata/driver-go/v3/taosRestful"
  9. )
  11. func main() {
  12.     var taosDSN = "root:taosdata@http(localhost:6041)/power"
  13.     taos, err := sql.Open("taosRestful", taosDSN)
  14.     if err != nil {
  15.         log.Fatalln("failed to connect TDengine, err:", err)
  16.     }
  17.     defer taos.Close()
  18.     rows, err := taos.Query("SELECT ts, current FROM meters LIMIT 2")
  19.     if err != nil {
  20.         log.Fatalln("failed to select from table, err:", err)
  21.     }
  23.     defer rows.Close()
  24.     for rows.Next() {
  25.         var r struct {
  26.             ts      time.Time
  27.             current float32
  28.         }
  29.         err := rows.Scan(&r.ts, &r.current)
  30.         if err != nil {
  31.             log.Fatalln("scan error:\n", err)
  32.             return
  33.         }
  34.         log.Println(r.ts, r.current)
  35.     }
  36. }

view source code

More sample programs

Usage limitations

Since the REST interface is stateless, the use db syntax will not work. You need to put the db name into the SQL command, e.g. create table if not exists tb1 (ts timestamp, a int) to create table if not exists test.tb1 (ts timestamp, a int) otherwise it will report the error [0x217] Database not specified or available.

You can also put the db name in the DSN by changing root:taosdata@http(localhost:6041)/ to root:taosdata@http(localhost:6041)/test. Executing the create database statement when the specified db does not exist will not report an error while executing other queries or writing against that db will report an error.

The complete example is as follows.

  1. package main
  3. import (
  4.     "database/sql"
  5.     "fmt"
  6.     "time"
  8.     _ "github.com/taosdata/driver-go/v3/taosRestful"
  9. )
  11. func main() {
  12.     var taosDSN = "root:taosdata@http(localhost:6041)/test"
  13.     taos, err := sql.Open("taosRestful", taosDSN)
  14.     if err != nil {
  15.         fmt.Println("failed to connect TDengine, err:", err)
  16.         return
  17.     }
  18.     defer taos.Close()
  19.     taos.Exec("create database if not exists test")
  20.     taos.Exec("create table if not exists tb1 (ts timestamp, a int)")
  21.     _, err = taos.Exec("insert into tb1 values(now, 0)(now+1s,1)(now+2s,2)(now+3s,3)")
  22.     if err != nil {
  23.         fmt.Println("failed to insert, err:", err)
  24.         return
  25.     }
  26.     rows, err := taos.Query("select * from tb1")
  27.     if err != nil {
  28.         fmt.Println("failed to select from table, err:", err)
  29.         return
  30.     }
  32.     defer rows.Close()
  33.     for rows.Next() {
  34.         var r struct {
  35.             ts time.Time
  36.             a  int
  37.         }
  38.         err := rows.Scan(&r.ts, &r.a)
  39.         if err != nil {
  40.             fmt.Println("scan error:\n", err)
  41.             return
  42.         }
  43.         fmt.Println(r.ts, r.a)
  44.     }
  45. }

Frequently Asked Questions

  1. bind interface in database/sql crashes

    REST does not support parameter binding related interface. It is recommended to use db.Exec and db.Query.

  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.

  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.

  4. 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.

  5. 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.

  6. 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.

Common APIs

database/sql API

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

    Use This API to open a DB, returning an object of type *DB.

Go - 图1info

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)

    sql.Open built-in method to execute non-query related SQL.

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

    sql.Open Built-in method to execute query statements.

Advanced functions (af) API

The af package encapsulates TDengine advanced functions such as connection management, subscriptions, schemaless, parameter binding, etc.

Connection management

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

    This API creates a connection to taosd via cgo.

  • func (conn *Connector) Close() error

    Closes the connection.

Subscribe

  • func NewConsumer(conf *Config) (*Consumer, error)

Creates consumer group.

  • func (c *Consumer) Subscribe(topics []string) error

Subscribes to topics.

  • func (c *Consumer) Poll(timeout time.Duration) (*Result, error)

Polling information.

  • func (c *Consumer) Commit(ctx context.Context, message unsafe.Pointer) error

Commit information.

  • func (c *Consumer) FreeMessage(message unsafe.Pointer)

Free information.

  • func (c *Consumer) Unsubscribe() error

Unsubscribe.

  • func (c *Consumer) Close() error

Close consumer.

schemaless

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

    Write to InfluxDB line protocol.

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

    Write OpenTDSB telnet protocol data.

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

    Writes OpenTSDB JSON protocol data.

parameter binding

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

    Parameter bound single row insert.

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

    Initialize the parameters.

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

    Parameter binding preprocessing SQL statement.

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

    Bind the table name parameter.

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

    Parameter binding to set the sub table name.

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

    Parameter bind multiple rows of data.

  • func (stmt *InsertStmt) AddBatch() error

    Add to a parameter-bound batch.

  • func (stmt *InsertStmt) Execute() error

    Execute a parameter binding.

  • func (stmt *InsertStmt) GetAffectedRows() int

    Gets the number of affected rows inserted by the parameter binding.

  • func (stmt *InsertStmt) Close() error

    Closes the parameter binding.

Subscribe via WebSocket

  • func NewConsumer(config *Config) (*Consumer, error)

    Creates consumer group.

  • func (c *Consumer) Subscribe(topic []string) error

    Subscribes to topics.

  • func (c *Consumer) Poll(timeout time.Duration) (*Result, error)

    Polling information.

  • func (c *Consumer) Commit(messageID uint64) error

    Commit information.

  • func (c *Consumer) Close() error

    Close consumer.

For a complete example see GitHub sample file

parameter binding via WebSocket

  • func NewConnector(config *Config) (*Connector, error)

    Create a connection.

  • func (c *Connector) Init() (*Stmt, error)

    Initialize the parameters.

  • func (c *Connector) Close() error

    Close the connection.

  • func (s *Stmt) Prepare(sql string) error

    Parameter binding preprocessing SQL statement.

  • func (s *Stmt) SetTableName(name string) error

    Bind the table name parameter.

  • func (s *Stmt) SetTags(tags *param.Param, bindType *param.ColumnType) error

    Set tags.

  • func (s *Stmt) BindParam(params []*param.Param, bindType *param.ColumnType) error

    Parameter bind multiple rows of data.

  • func (s *Stmt) AddBatch() error

    Add to a parameter-bound batch.

  • func (s *Stmt) Exec() error

    Execute a parameter binding.

  • func (s *Stmt) GetAffectedRows() int

    Gets the number of affected rows inserted by the parameter binding.

  • func (s *Stmt) Close() error

    Closes the parameter binding.

For a complete example see GitHub sample file

API Reference

Full API see driver-go documentation