Connect

Any application programs running on any kind of platform can access TDengine through the REST API provided by TDengine. For details, please refer to REST API. Additionally, application programs can use the connectors of multiple programming languages including C/C++, Java, Python, Go, Node.js, C#, Rust to access TDengine. This chapter describes how to establish a connection to TDengine and briefly introduces how to install and use connectors. TDengine community also provides connectors in LUA and PHP languages. For details about the connectors, please refer to Connectors.

Establish Connection

There are two ways for a connector to establish connections to TDengine:

  1. Connection through the REST API provided by the taosAdapter component, this way is called “REST connection” hereinafter.
  2. Connection through the TDengine client driver (taosc), this way is called “Native connection” hereinafter.

Key differences：

  1. The TDengine client driver (taosc) has the highest performance with all the features of TDengine like Parameter Binding, Subscription, etc.
  2. The TDengine client driver (taosc) is not supported across all platforms, and applications built on taosc may need to be modified when updating taosc to newer versions.
  3. The REST connection is more accessible with cross-platform support, however it results in a 30% performance downgrade.

Install Client Driver taosc

If you are choosing to use the native connection and the the application is not on the same host as TDengine server, the TDengine client driver taosc needs to be installed on the application host. If choosing to use the REST connection or the application is on the same host as TDengine server, this step can be skipped. It’s better to use same version of taosc as the TDengine server.

Install

  • Linux
  • Windows

  1. Download the TDengine client installation package

    Enter your email to receive the download link

    TDengine Database

    encn

    Agree to TDengine to contact me via this email addressDownload

    Close

    All Packages

  2. Unzip

    Download the package to any directory the current user has read/write permission. Then execute tar -xzvf TDengine-client-VERSION.tar.gz command. The VERSION should be the version of the package you just downloaded.

  3. Execute the install script

    Once the package is unzipped, you will see the following files in the directory:

    • install_client.sh: install script
    • taos.tar.gz: client driver package
    • driver: TDengine client driver
    • examples: some example programs of different programming languages (C/C#/go/JDBC/MATLAB/python/R)

    You can run install_client.sh to install it.

  4. Edit taos.cfg

    Edit taos.cfg file (full path is /etc/taos/taos.cfg by default), modify firstEP with actual TDengine server’s End Point, for example h1.tdengine.com:6030

Connect - 图2tip

  1. If the computer does not run the TDengine service but installs the TDengine client driver, then you need to config firstEP in taos.cfg only, and there is no need to configure FQDN;

  2. If you encounter the “Unable to resolve FQDN” error, please make sure the FQDN in the /etc/hosts file of the current computer is correctly configured, or the DNS service is correctly configured.

  3. Download the client installation package

    Enter your email to receive the download link

    TDengine Database

    encn

    Agree to TDengine to contact me via this email addressDownload

    Close

    All downloads

  4. Execute the installer, select the default value as prompted, and complete the installation

  5. Installation path

    The default installation path is C:\TDengine, including the following files (directories).

    • taos.exe : TDengine CLI command-line program
    • cfg : configuration file directory
    • driver: client driver dynamic link library
    • examples: sample programs bash/C/C#/go/JDBC/Python/Node.js
    • include: header files
    • log : log file
    • unins000.exe: uninstaller

  6. configure taos.cfg

    Edit the taos.cfg file (default path C:\TDengine\cfg\taos.cfg) and change the firstEP to the End Point of the TDengine server, for example: h1.tdengine.com:6030.

Connect - 图4tip
  1. If you use FQDN to connect to the server, you must ensure the local network environment DNS is configured, or add FQDN addressing records in the hosts file, e.g., edit C:\Windows\system32\drivers\etc\hosts and add a record like the following: 192.168.1.99 h1.taosd.com..
  2. Uninstall: Run unins000.exe to uninstall the TDengine client driver.

Verify

After the above installation and configuration are done and making sure TDengine service is already started and in service, the TDengine command-line interface taos can be launched to access TDengine.

  • Linux
  • Windows

Execute TDengine CLI program taos directly from the Linux shell to connect to the TDengine service and enter the TDengine CLI interface, as shown in the following example.

  1. $ taos
  2. Welcome to the TDengine shell from Linux, Client  Version:2.0.5.0
  3. Copyright (c) 2017 by TAOS Data, Inc. All rights  reserved.
  4. taos> show databases;
  5. name       |   created_time    |   ntables  |  vgroups   | replica | quorum | days |    keep1,keep2,keep(D)   | cache(MB)|   blocks  |  minrows   |  maxrows  | wallevel |  fsync    | comp | precision |    status  |
  6. =========================================================================================================================================================================================================================
  7. test       | 2020-10-14  10:35:48.617 |     10 |      1 |    1 |   1 |     2 | 3650,3650,3650        |     16|      6 |     100 |    4096 |    1 |    3000 |  2 | ms      | ready    |
  8. log        | 2020-10-12  09:08:21.651 |      4 |      1 |    1 |   1 |   10 | 30,30,30               |      1|      3 |     100 |    4096 |    1 |    3000 |  2 | us    | ready    |
  9. Query OK, 2 row(s) in set (0.001198s)
  10. taos>

Go to the C:\TDengine directory from cmd and execute TDengine CLI program taos.exe directly to connect to the TDengine service and enter the TDengine CLI interface, for example, as follows:

  1.   C:\TDengine>taos
  2.   Welcome to the TDengine  shell from Linux, Client Version:2.0.5.0
  3.   Copyright (c) 2017 by  TAOS Data, Inc. All rights reserved.
  4.   taos> show  databases;
  5.   name       |   created_time    |   ntables  |  vgroups   | replica | quorum | days |    keep1,keep2,keep(D)   | cache(MB)   |  blocks  |   minrows  |  maxrows   | wallevel |  fsync  | comp | precision |  status    |
  6.   ===================================================================================================================================================================================================================================================================
  7.   test       | 2020-10-14  10:35:48.617 |     10 |      1 |    1 |   1 |     2 | 3650,3650,3650        |     16 |      6 |     100 |    4096 |    1 |    3000 |  2 | ms    | ready    |
  8.   log        | 2020-10-12  09:08:21.651 |      4 |      1 |    1 |   1 |    10 | 30,30,30              |      1 |      3 |     100 |    4096 |    1 |    3000 |  2 | us    | ready    |
  9.   Query OK, 2 row(s) in  set (0.045000s)
  10.   taos>

Install Connectors

  • Java
  • Python
  • Go
  • Rust
  • Node.js
  • C#
  • R
  • C
  • PHP

If `maven` is used to manage the projects, what needs to be done is only adding below dependency in `pom.xml`.

  1. <dependency>
  2.   <groupId>com.taosdata.jdbc</groupId>
  3.   <artifactId>taos-jdbcdriver</artifactId>
  4.   <version>2.0.38</version>
  5. </dependency>

Install from PyPI using pip:

  1. pip install taospy

Install from Git URL:

  1. pip install git+https://github.com/taosdata/taos-connector-python.git

Just need to add driver-go dependency in go.mod .

go.mod

  1. module goexample
  3. go 1.17
  5. require github.com/taosdata/driver-go/v2 latest

view source code

Connect - 图5note

driver-go uses cgo to wrap the APIs provided by taosc, while cgo needs gcc to compile source code in C language, so please make sure you have proper gcc on your system.

Just need to add libtaos dependency in Cargo.toml.

Cargo.toml

  1. [dependencies]
  2. libtaos = { version = "0.4.2"}
Connect - 图6info

Rust connector uses different features to distinguish the way to establish connection. To establish REST connection, please enable rest feature.

  1. libtaos = { version = "*", features = ["rest"] }

Node.js connector provides different ways of establishing connections by providing different packages.

  1. Install Node.js Native Connector
  1. npm i td2.0-connector
Connect - 图7note

It’s recommend to use Node whose version is between node-v12.8.0 and node-v13.0.0.

  1. Install Node.js REST Connector
  1. npm i td2.0-rest-connector

Just need to add the reference to TDengine.Connector in the project configuration file.

csharp.csproj

  1. <Project Sdk="Microsoft.NET.Sdk">
  3.   <PropertyGroup>
  4.     <OutputType>Exe</OutputType>
  5.     <TargetFramework>net6.0</TargetFramework>
  6.     <ImplicitUsings>enable</ImplicitUsings>
  7.     <Nullable>enable</Nullable>
  8.     <StartupObject>TDengineExample.AsyncQueryExample</StartupObject>
  9.   </PropertyGroup>
  11.   <ItemGroup>
  12.     <PackageReference Include="TDengine.Connector" Version="1.0.6" />
  13.   </ItemGroup>
  15. </Project>

Or add by dotnet command.

  1. dotnet add package TDengine.Connector
Connect - 图8note

The sample code below are based on dotnet6.0, they may need to be adjusted if your dotnet version is not exactly same.

  1. Download taos-jdbcdriver-version-dist.jar.
  2. Install the dependency package RJDBC：
  1. install.packages("RJDBC")

If the client driver (taosc) is already installed, then the C connector is already available.

Download Source Code Package and Unzip：

  1. curl -L -o php-tdengine.tar.gz https://github.com/Yurunsoft/php-tdengine/archive/refs/tags/v1.0.2.tar.gz \
  2. && mkdir php-tdengine \
  3. && tar -xzf php-tdengine.tar.gz -C php-tdengine --strip-components=1

Version number v1.0.2 is only for example, it can be replaced to any newer version, please check available version from TDengine PHP Connector Releases.

Non-Swoole Environment：

  1. phpize && ./configure && make -j && make install

Specify TDengine Location：

  1. phpize && ./configure --with-tdengine-dir=/usr/local/Cellar/tdengine/2.4.0.0 && make -j && make install

--with-tdengine-dir= is followed by the TDengine installation location. This way is useful in case TDengine location can’t be found automatically or macOS.

Swoole Environment：

  1. phpize && ./configure --enable-swoole && make -j && make install

Enable The Extension:

Option One: Add extension=tdengine in php.ini

Option Two: Specify the extension on CLI php -d extension=tdengine test.php

Establish Connection

Prior to establishing connection, please make sure TDengine is already running and accessible. The following sample code assumes TDengine is running on the same host as the client program, with FQDN configured to “localhost” and serverPort configured to “6030”.

  • Java
  • Python
  • Go
  • Rust
  • Node.js
  • C#
  • R
  • C

Native Connection

  1. package com.taos.example;
  3. import java.sql.Connection;
  4. import java.sql.DriverManager;
  5. import java.sql.SQLException;
  6. import java.util.Properties;
  8. import com.taosdata.jdbc.TSDBDriver;
  10. public class JNIConnectExample {
  11.     public static void main(String[] args) throws SQLException {
  12.         String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata";
  13.         Properties connProps = new Properties();
  14.         connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8");
  15.         connProps.setProperty(TSDBDriver.PROPERTY_KEY_LOCALE, "en_US.UTF-8");
  16.         connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8");
  17.         Connection conn = DriverManager.getConnection(jdbcUrl, connProps);
  18.         System.out.println("Connected");
  19.         conn.close();
  20.     }
  21. }
  23. // use
  24. // String jdbcUrl = "jdbc:TAOS://localhost:6030/dbName?user=root&password=taosdata";
  25. // if you want to connect a specified database named "dbName".

view source code

REST Connection

  1.     public static void main(String[] args) throws SQLException {
  2.         String jdbcUrl = "jdbc:TAOS-RS://localhost:6041?user=root&password=taosdata";
  3.         Connection conn = DriverManager.getConnection(jdbcUrl);
  4.         System.out.println("Connected");
  5.         conn.close();
  6.     }

view source code

When using REST connection, the feature of bulk pulling can be enabled if the size of resulting data set is huge.

Enable Bulk Pulling

  1.     public static void main(String[] args) throws SQLException {
  2.         String jdbcUrl = "jdbc:TAOS-RS://localhost:6041?user=root&password=taosdata";
  3.         Properties connProps = new Properties();
  4.         connProps.setProperty(TSDBDriver.PROPERTY_KEY_BATCH_LOAD, "true");
  5.         Connection conn = DriverManager.getConnection(jdbcUrl, connProps);
  6.         System.out.println("Connected");
  7.         conn.close();
  8.     }

view source code

More configuration about connection，please refer to Java Connector

Native Connection

  1. import taos
  4. def test_connection():
  5.     # all parameters are optional.
  6.     # if database is specified,
  7.     # then it must exist.
  8.     conn = taos.connect(host="localhost",
  9.                         port=6030,
  10.                         user="root",
  11.                         password="taosdata",
  12.                         database="log")
  13.     print('client info:', conn.client_info)
  14.     print('server info:', conn.server_info)
  15.     conn.close()
  18. if __name__ == "__main__":
  19.     test_connection()

view source code

Unified Database Access Interface

Native Connection

  1. package main
  3. import (
  4.     "database/sql"
  5.     "fmt"
  7.     _ "github.com/taosdata/driver-go/v2/taosSql"
  8. )
  10. func main() {
  11.     var taosDSN = "root:taosdata@tcp(localhost:6030)/"
  12.     taos, err := sql.Open("taosSql", taosDSN)
  13.     if err != nil {
  14.         fmt.Println("failed to connect TDengine, err:", err)
  15.         return
  16.     }
  17.     fmt.Println("Connected")
  18.     defer taos.Close()
  19. }
  21. // use
  22. // var taosDSN = "root:taosdata@tcp(localhost:6030)/dbName"
  23. // if you want to connect a specified database named "dbName".

view source code

REST Connection

  1. package main
  3. import (
  4.     "database/sql"
  5.     "fmt"
  7.     _ "github.com/taosdata/driver-go/v2/taosRestful"
  8. )
  10. func main() {
  11.     var taosDSN = "root:taosdata@http(localhost:6041)/"
  12.     taos, err := sql.Open("taosRestful", taosDSN)
  13.     if err != nil {
  14.         fmt.Println("failed to connect TDengine, err:", err)
  15.         return
  16.     }
  17.     fmt.Println("Connected")
  18.     defer taos.Close()
  19. }
  21. // use
  22. // var taosDSN = "root:taosdata@http(localhost:6041)/dbName"
  23. // if you want to connect a specified database named "dbName".

view source code

Advanced Features

The af package of driver-go can also be used to establish connection, with this way some advanced features of TDengine, like parameter binding and subscription, can be used.

Establish native connection using af package

  1. package main
  3. import (
  4.     "fmt"
  6.     "github.com/taosdata/driver-go/v2/af"
  7. )
  9. func main() {
  10.     conn, err := af.Open("localhost", "root", "taosdata", "", 6030)
  11.     defer conn.Close()
  12.     if err != nil {
  13.         fmt.Println("failed to connect, err:", err)
  14.     } else {
  15.         fmt.Println("connected")
  16.     }
  17. }

view source code

Native Connection/REST Connection

  1. use libtaos::*;
  3. fn taos_connect() -> Result<Taos, Error> {
  4.     TaosCfgBuilder::default()
  5.         .ip("localhost")
  6.         .user("root")
  7.         .pass("taosdata")
  8.         // .db("log") // remove comment if you want to connect to database log by default.
  9.         .port(6030u16)
  10.         .build()
  11.         .expect("TaosCfg builder error")
  12.         .connect()
  13. }
  15. fn main() {
  16.     #[allow(unused_variables)]
  17.     let taos = taos_connect().unwrap();
  18.     println!("Connected")
  19. }

view source code

Connect - 图9note

For Rust connector, the connection depends on the feature being used. If “rest” feature is enabled, then only the implementation for “rest” is compiled and packaged.

Native Connection

  1. const taos = require("td2.0-connector");
  3. var conn = taos.connect({
  4.   host: "localhost",
  5.   port: 6030,
  6.   user: "root",
  7.   password: "taosdata",
  8. });
  9. conn.close();
  11. // run with: node connect.js
  12. // output:
  13. // Successfully connected to TDengine

view source code

REST Connection

  1. const { options, connect } = require("td2.0-rest-connector");
  3. async function test() {
  4.   options.path = "/rest/sqlt";
  5.   options.host = "localhost";
  6.   let conn = connect(options);
  7.   let cursor = conn.cursor();
  8.   try {
  9.     let res = await cursor.query("SELECT server_version()");
  10.     res.toString();
  11.   } catch (err) {
  12.     console.log(err);
  13.   }
  14. }
  15. test();
  17. // output:
  18. // server_version() |
  19. // ===================
  20. // 2.4.0.12         |

view source code

Native Connection

  1. using TDengineDriver;
  3. namespace TDengineExample
  4. {
  6.     internal class ConnectExample
  7.     {
  8.         static void Main(String[] args)
  9.         {
  10.             string host = "localhost";
  11.             short port = 6030;
  12.             string username = "root";
  13.             string password = "taosdata";
  14.             string dbname = "";
  16.             var conn = TDengine.Connect(host, username, password, dbname, port);
  17.             if (conn == IntPtr.Zero)
  18.             {
  19.                 Console.WriteLine("Connect to TDengine failed");
  20.             }
  21.             else
  22.             {
  23.                 Console.WriteLine("Connect to TDengine success");
  24.             }
  25.             TDengine.Close(conn);
  26.             TDengine.Cleanup();
  27.         }
  28.     }
  29. }

view source code

Connect - 图10info

C# connector supports only native connection for now.

Native Connection

  1. library("DBI")
  2. library("rJava")
  3. library("RJDBC")
  5. args<- commandArgs(trailingOnly = TRUE)
  6. driver_path = args[1] # path to jdbc-driver for example: "/root/taos-jdbcdriver-2.0.37-dist.jar"
  7. driver = JDBC("com.taosdata.jdbc.TSDBDriver", driver_path)
  8. conn = dbConnect(driver, "jdbc:TAOS://127.0.0.1:6030/?user=root&password=taosdata")
  9. dbGetQuery(conn, "SELECT server_version()")
  10. dbDisconnect(conn)

view source code

Native Connection

  1. // compile with
  2. // gcc connect_example.c -o connect_example -ltaos
  3. #include <stdio.h>
  4. #include <stdlib.h>
  5. #include "taos.h"
  7. int main() {
  8.   const char *host = "localhost";
  9.   const char *user = "root";
  10.   const char *passwd = "taosdata";
  11.   // if don't want to connect to a default db, set it to NULL or ""
  12.   const char *db = NULL;
  13.   uint16_t    port = 0;  // 0 means use the default port
  14.   TAOS       *taos = taos_connect(host, user, passwd, db, port);
  15.   if (taos == NULL) {
  16.     int   errno = taos_errno(NULL);
  17.     char *msg = taos_errstr(NULL);
  18.     printf("%d, %s\n", errno, msg);
  19.   } else {
  20.     printf("connected\n");
  21.     taos_close(taos);
  22.   }
  23.   taos_cleanup();
  24. }

view source code

Connect - 图11tip

If the connection fails, in most cases it’s caused by improper configuration for FQDN or firewall. Please refer to the section “Unable to establish connection” in FAQ.