Skip to main content

Connect to TDengine

Any application running on any platform can access TDengine through the REST API provided by TDengine. For information, see REST API. Applications can also use the connectors for various programming languages, including C/C++, Java, Python, Go, Node.js, C#, and Rust, to access TDengine. These connectors support connecting to TDengine clusters using both native interfaces (taosc). Some connectors also support connecting over a REST interface. Community developers have also contributed several unofficial connectors, such as the ADO.NET connector, the Lua connector, and the PHP connector.

Establish Connection

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

  1. REST connection through the REST API provided by the taosAdapter component.
  2. Native connection through the TDengine client driver (taosc).

For REST and native connections, connectors provide similar APIs for performing operations and running SQL statements on your databases. The main difference is the method of establishing the connection, which is not visible to users.

Key differences:

  1. The REST connection is more accessible with cross-platform support, however it results in a 30% performance downgrade.
  2. The TDengine client driver (taosc) has the highest performance with all the features of TDengine like Parameter Binding, Subscription, etc.

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

  1. Download the client installation package

      All Downloads

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

    • 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.
    • configure 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

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

    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.

    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.

    $ taos

    taos> show databases;
    name | create_time | vgroups | ntables | replica | strict | duration | keep | buffer | pagesize | pages | minrows | maxrows | comp | precision | status | retention | single_stable | cachemodel | cachesize | wal_level | wal_fsync_period | wal_retention_period | wal_retention_size | wal_roll_period | wal_seg_size |
    =========================================================================================================================================================================================================================================================================================================================================================================================================================================================================
    information_schema | NULL | NULL | 14 | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | ready | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL |
    performance_schema | NULL | NULL | 3 | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | ready | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL |
    db | 2022-08-04 14:14:49.385 | 2 | 4 | 1 | off | 14400m | 5254560m,5254560m,5254560m | 96 | 4 | 256 | 100 | 4096 | 2 | ms | ready | NULL | false | none | 1 | 1 | 3000 | 0 | 0 | 0 | 0 |
    Query OK, 3 rows in database (0.019154s)

    taos>

    Install Connectors

    If `maven` is used to manage the projects, what needs to be done is only adding below dependency in `pom.xml`.
    <dependency>
    <groupId>com.taosdata.jdbc</groupId>
    <artifactId>taos-jdbcdriver</artifactId>
    <version>3.0.0</version>
    </dependency>

    Establish a 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".

    Native Connection
    package com.taos.example;

    import java.sql.Connection;
    import java.sql.DriverManager;
    import java.sql.SQLException;
    import java.util.Properties;

    import com.taosdata.jdbc.TSDBDriver;

    public class JNIConnectExample {
    public static void main(String[] args) throws SQLException {
    String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata";
    Properties connProps = new Properties();
    connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8");
    connProps.setProperty(TSDBDriver.PROPERTY_KEY_LOCALE, "en_US.UTF-8");
    connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8");
    Connection conn = DriverManager.getConnection(jdbcUrl, connProps);
    System.out.println("Connected");
    conn.close();
    }
    }

    // use
    // String jdbcUrl = "jdbc:TAOS://localhost:6030/dbName?user=root&password=taosdata";
    // if you want to connect a specified database named "dbName".

    view source code

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

    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
        public static void main(String[] args) throws SQLException {
    String jdbcUrl = "jdbc:TAOS-RS://localhost:6041?user=root&password=taosdata";
    Properties connProps = new Properties();
    connProps.setProperty(TSDBDriver.PROPERTY_KEY_BATCH_LOAD, "true");
    Connection conn = DriverManager.getConnection(jdbcUrl, connProps);
    System.out.println("Connected");
    conn.close();
    }

    view source code

    More configuration about connection,please refer to Java Connector

    tip

    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.