TDengine Rust Connector

libtaos is the official Rust language connector for TDengine. Rust developers can develop applications to access the TDengine instance data.

libtaos provides two ways to establish connections. One is the Native Connection, which connects to TDengine instances via the TDengine client driver (taosc). The other is REST connection, which connects to TDengine instances via taosAdapter’s REST interface.

The source code for libtaos is hosted on GitHub.

Supported platforms

The platforms supported by native connections are the same as those supported by the TDengine client driver. REST connections are supported on all platforms that can run Rust.

Version support

Please refer to version support list.

The Rust Connector is still under rapid development and is not guaranteed to be backward compatible before 1.0. We recommend using TDengine version 2.4 or higher to avoid known issues.

Installation

Pre-installation

  • Install the Rust development toolchain
  • If using the native connection, please install the TDengine client driver. Please refer to install client driver

Adding libtaos dependencies

Add the libtaos dependency to the Rust project as follows, depending on the connection method selected.

  • native connection
  • REST connection

Add libtaos to the Cargo.toml file.

  1. [dependencies]
  2. # use default feature
  3. libtaos = "*"

Add libtaos to the Cargo.toml file and enable the rest feature.

  1. [dependencies]
  2. # use rest feature
  3. libtaos = { version = "*", features = ["rest"]}

Using connection pools

Please enable the r2d2 feature in Cargo.toml.

  1. [dependencies]
  2. # with taosc
  3. libtaos = { version = "*", features = ["r2d2"] }
  4. # or rest
  5. libtaos = { version = "*", features = ["rest", "r2d2"] }

Create a connection

The TaosCfgBuilder provides the user with an API in the form of a constructor for the subsequent creation of connections or use of connection pools.

  1. let cfg: TaosCfg = TaosCfgBuilder::default()
  2.     .ip("127.0.0.1")
  3.     .user("root")
  4.     .pass("taosdata")
  5.     .db("log") // do not set if not require a default database.
  6.     .port(6030u16)
  7.     .build()
  8.     .expect("TaosCfg builder error");
  9. }

You can now use this object to create the connection.

  1. let conn = cfg.connect()? ;

The connection object can create more than one.

  1. let conn = cfg.connect()? ;
  2. let conn2 = cfg.connect()? ;

You can use connection pools in applications.

  1. let pool = r2d2::Pool::builder()
  2.     .max_size(10000) // max connections
  3.     .build(cfg)? ;
  5. // ...
  6. // Use pool to get connection
  7. let conn = pool.get()? ;

After that, you can perform the following operations on the database.

  1. async fn demo() -> Result<(), Error> {
  2.     // get connection ...
  4.     // create database
  5.     conn.exec("create database if not exists demo").await?
  6.     // change database context
  7.     conn.exec("use demo").await?
  8.     // create table
  9.     conn.exec("create table if not exists tb1 (ts timestamp, v int)").await?
  10.     // insert
  11.     conn.exec("insert into tb1 values(now, 1)").await?
  12.     // query
  13.     let rows = conn.query("select * from tb1").await?
  14.     for row in rows.rows {
  15.         println!("{}", row.into_iter().join(","));
  16.     }
  17. }

Usage examples

Write data

SQL Write

  1. use libtaos::*;
  3. #[tokio::main]
  4. async fn main() -> Result<(), Error> {
  5.     let taos = TaosCfg::default().connect().expect("fail to connect");
  6.     taos.create_database("power").await?;
  7.     taos.exec("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)").await?;
  8.     let 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)
  9.     power.d1002 USING power.meters TAGS(California.SanFrancisco, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)
  10.     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)
  11.     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)";
  12.     let result = taos.query(sql).await?;
  13.     println!("{:?}", result);
  14.     Ok(())
  15. }
  17. // output:
  18. // TaosQueryData { column_meta: [ColumnMeta { name: "affected_rows", type_: Int, bytes: 4 }], rows: [[Int(8)]] }

view source code

InfluxDB line protocol write

  1. use libtaos::schemaless::*;
  2. use libtaos::*;
  4. fn main() {
  5.     let taos = TaosCfg::default().connect().expect("fail to connect");
  6.     taos.raw_query("CREATE DATABASE test").unwrap();
  7.     taos.raw_query("USE test").unwrap();
  8.     let lines = ["meters,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249",
  9.     "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250",
  10.     "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249",
  11.     "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250"];
  12.     let affected_rows = taos
  13.         .schemaless_insert(
  14.             &lines,
  15.             TSDB_SML_LINE_PROTOCOL,
  16.             TSDB_SML_TIMESTAMP_MILLISECONDS,
  17.         )
  18.         .unwrap();
  19.     println!("affected_rows={}", affected_rows);
  20. }
  22. // run with:  cargo run --example influxdb_line_example

view source code

OpenTSDB Telnet line protocol write

  1. use libtaos::schemaless::*;
  2. use libtaos::*;
  4. fn main() {
  5.     let taos = TaosCfg::default().connect().expect("fail to connect");
  6.     taos.raw_query("CREATE DATABASE test").unwrap();
  7.     taos.raw_query("USE test").unwrap();
  8.     let lines = [
  9.         "meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2",
  10.         "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2",
  11.         "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3",
  12.         "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3",
  13.         "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2",
  14.         "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2",
  15.         "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3",
  16.         "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3",
  17.     ];
  18.     let affected_rows = taos
  19.         .schemaless_insert(
  20.             &lines,
  21.             TSDB_SML_TELNET_PROTOCOL,
  22.             TSDB_SML_TIMESTAMP_NOT_CONFIGURED,
  23.         )
  24.         .unwrap();
  25.     println!("affected_rows={}", affected_rows); // affected_rows=8
  26. }
  28. // run with:  cargo run --example opentsdb_telnet_example

view source code

OpenTSDB JSON line protocol write

  1. use libtaos::schemaless::*;
  2. use libtaos::*;
  4. fn main() {
  5.     let taos = TaosCfg::default().connect().expect("fail to connect");
  6.     taos.raw_query("CREATE DATABASE test").unwrap();
  7.     taos.raw_query("USE test").unwrap();
  8.     let lines = [
  9.         r#"[{"metric": "meters.current", "timestamp": 1648432611249, "value": 10.3, "tags": {"location": "California.SanFrancisco", "groupid": 2}},
  10.         {"metric": "meters.voltage", "timestamp": 1648432611249, "value": 219, "tags": {"location": "California.LosAngeles", "groupid": 1}},
  11.         {"metric": "meters.current", "timestamp": 1648432611250, "value": 12.6, "tags": {"location": "California.SanFrancisco", "groupid": 2}},
  12.         {"metric": "meters.voltage", "timestamp": 1648432611250, "value": 221, "tags": {"location": "California.LosAngeles", "groupid": 1}}]"#,
  13.     ];
  15.     let affected_rows = taos
  16.         .schemaless_insert(
  17.             &lines,
  18.             TSDB_SML_JSON_PROTOCOL,
  19.             TSDB_SML_TIMESTAMP_NOT_CONFIGURED,
  20.         )
  21.         .unwrap();
  22.     println!("affected_rows={}", affected_rows); // affected_rows=4
  23. }
  25. // run with:  cargo run --example opentsdb_json_example

view source code

Query data

  1. use libtaos::*;
  3. fn taos_connect() -> Result<Taos, Error> {
  4.     TaosCfgBuilder::default()
  5.         .ip("localhost")
  6.         .user("root")
  7.         .pass("taosdata")
  8.         .db("power")
  9.         .port(6030u16)
  10.         .build()
  11.         .expect("TaosCfg builder error")
  12.         .connect()
  13. }
  15. #[tokio::main]
  16. async fn main() -> Result<(), Error> {
  17.     let taos = taos_connect().expect("connect error");
  18.     let result = taos.query("SELECT ts, current FROM meters LIMIT 2").await?;
  19.     // print column names
  20.     let meta: Vec<ColumnMeta> = result.column_meta;
  21.     for column in meta {
  22.         print!("{}\t", column.name)
  23.     }
  24.     println!();
  25.     // print rows
  26.     let rows: Vec<Vec<Field>> = result.rows;
  27.     for row in rows {
  28.         for field in row {
  29.             print!("{}\t", field);
  30.         }
  31.         println!();
  32.     }
  33.     Ok(())
  34. }
  36. // output:
  37. // ts      current
  38. // 2022-03-28 09:56:51.249 10.3
  39. // 2022-03-28 09:56:51.749 12.6

view source code

More sample programs

Program PathProgram Description
demo.rsBasic API Usage Examples
bailongma-rsUsing TDengine as the Prometheus remote storage API adapter for the storage backend, using the r2d2 connection pool

API Reference

Connection constructor API

The Builder Pattern constructor pattern is Rust’s solution for handling complex data types or optional configuration types. The libtaos implementation uses the connection constructor TaosCfgBuilder as the entry point for the TDengine Rust connector. The TaosCfgBuilder provides optional configuration of servers, ports, databases, usernames, passwords, etc.

Using the default() method, you can construct a TaosCfg with default parameters for subsequent connections to the database or establishing connection pools.

  1. let cfg = TaosCfgBuilder::default().build()? ;

Using the constructor pattern, the user can set on-demand.

  1. let cfg = TaosCfgBuilder::default()
  2.     .ip("127.0.0.1")
  3.     .user("root")
  4.     .pass("taosdata")
  5.     .db("log")
  6.     .port(6030u16)
  7.     .build()? ;

Create TDengine connection using TaosCfg object.

  1. let conn: Taos = cfg.connect();

Connection pooling

In complex applications, we recommend enabling connection pools. Connection pool for libtaos is implemented using r2d2.

As follows, a connection pool with default parameters can be generated.

  1. let pool = r2d2::Pool::new(cfg)? ;

You can set the same connection pool parameters using the connection pool’s constructor.

  1.     use std::time::Duration;
  2.     let pool = r2d2::Pool::builder()
  3.         .max_size(5000) // max connections
  4.         .max_lifetime(Some(Duration::from_minutes(100))) // lifetime of each connection
  5.         .min_idle(Some(1000)) // minimal idle connections
  6.         .connection_timeout(Duration::from_minutes(2))
  7.         .build(cfg);

In the application code, use pool.get()? to get a connection object Taos.

  1. let taos = pool.get()? ;

The Taos structure is the connection manager in libtaos and provides two main APIs.

  1. exec: Execute some non-query SQL statements, such as CREATE, ALTER, INSERT, etc.

    1. taos.exec().await?

  2. query: Execute the query statement and return the TaosQueryData object.

    1. let q = taos.query("select * from log.logs").await?

    The TaosQueryData object stores the query result data and basic information about the returned columns (column name, type, length).

    Column information is stored using [ColumnMeta].

    1. let cols = &q.column_meta;
    2. for col in cols {
    3.     println!("name: {}, type: {:?} , bytes: {}", col.name, col.type_, col.bytes);
    4. }

    It fetches data line by line.

    1. for (i, row) in q.rows.iter().enumerate() {
    2.     for (j, cell) in row.iter().enumerate() {
    3.         println!("cell({}, {}) data: {}", i, j, cell);
    4.     }
    5. }

Note that Rust asynchronous functions and an asynchronous runtime are required.

Taos provides a few Rust methods that encapsulate SQL to reduce the frequency of format! code blocks.

  • .describe(table: &str): Executes DESCRIBE and returns a Rust data structure.
  • .create_database(database: &str): Executes the CREATE DATABASE statement.
  • .use_database(database: &str): Executes the USE statement.

In addition, this structure is also the entry point for [Parameter Binding](#Parameter Binding Interface) and [Line Protocol Interface](#Line Protocol Interface). Please refer to the specific API descriptions for usage.

Bind Interface

Similar to the C interface, Rust provides the bind interface’s wrapping. First, create a bind object Stmt for a SQL command from the Taos object.

  1. let mut stmt: Stmt = taos.stmt("insert into ? values(? ,?)") ? ;

The bind object provides a set of interfaces for implementing parameter binding.

.set_tbname(tbname: impl ToCString)

To bind table names.

.set_tbname_tags(tbname: impl ToCString, tags: impl IntoParams)

Bind sub-table table names and tag values when the SQL statement uses a super table.

  1. let mut stmt = taos.stmt("insert into ? using stb0 tags(?) values(? ,?)") ? ;
  2. // tags can be created with any supported type, here is an example using JSON
  3. let v = Field::Json(serde_json::from_str("{\"tag1\":\"one, two, three, four, five, six, seven, eight, nine, ten\"}").unwrap());
  4. stmt.set_tbname_tags("tb0", [&tag])? ;
.bind(params: impl IntoParams)

Bind value types. Use the Field structure to construct the desired type and bind.

  1. let ts = Field::Timestamp(Timestamp::now());
  2. let value = Field::Float(0.0);
  3. stmt.bind(vec![ts, value].iter())? ;
.execute()

Execute SQL.Stmt objects can be reused, re-binded, and executed after execution.

  1. stmt.execute()? ;
  3. // next bind cycle.
  4. // stmt.set_tbname()? ;
  5. //stmt.bind()? ;
  6. //stmt.execute()? ;

Line protocol interface

The line protocol interface supports multiple modes and different precision and requires the introduction of constants in the schemaless module to set.

  1. use libtaos::*;
  2. use libtaos::schemaless::*;

  • InfluxDB line protocol

    1. let lines = [
    2.     "st,t1=abc,t2=def,t3=anything c1=3i64,c3=L\"pass\",c2=false 1626006833639000000"
    3.     "st,t1=abc,t2=def,t3=anything c1=3i64,c3=L\"abc\",c4=4f64 1626006833639000000"
    4. ];
    5. taos.schemaless_insert(&lines, TSDB_SML_LINE_PROTOCOL, TSDB_SML_TIMESTAMP_NANOSECONDS)? ;

  • OpenTSDB Telnet Protocol

    1. let lines = ["sys.if.bytes.out 1479496100 1.3E3 host=web01 interface=eth0"];
    2. taos.schemaless_insert(&lines, TSDB_SML_LINE_PROTOCOL, TSDB_SML_TIMESTAMP_SECONDS)? ;

  • OpenTSDB JSON protocol

    1. let lines = [r#"
    2.     {
    3.         "metric": "st",
    4.         "timestamp": 1626006833,
    5.         "value": 10,
    6.         "tags": {
    7.             "t1": true,
    8.             "t2": false,
    9.             "t3": 10,
    10.             "t4": "123_abc_.! @#$%^&*:;,. /? |+-=()[]{}<>"
    11.         }
    12.     }"#];
    13. taos.schemaless_insert(&lines, TSDB_SML_LINE_PROTOCOL, TSDB_SML_TIMESTAMP_SECONDS)? ;

Please move to the Rust documentation hosting page for other related structure API usage instructions: https://docs.rs/libtaos.