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 client libraries for various programming languages, including C/C++, Java, Python, Go, Node.js, C#, and Rust, to access TDengine. These client libraries support connecting to TDengine clusters using both native interfaces (taosc). Some client libraries also support connecting over a REST interface. Community developers have also contributed several unofficial client libraries, such as the ADO.NET, Lua, and PHP libraries.

Establish Connection​

There are three ways for a client library to establish connections to TDengine:

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

TDengine connection type

For these ways of connections, client libraries 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. For a Native connection, the client driver taosc and the server TDengine version must be compatible.
  2. For a REST connection, users do not need to install the client driver taosc, providing the advantage of cross-platform ease of use. However, functions such as data subscription and binary data types are not available. Additionally, compared to Native and Websocket connections, a REST connection has the worst performance.
  3. For a Websocket connection, users also do not need to install the client driver taosc.
  4. To connect to a cloud service instance, you need to use the REST connection or Websocket connection.

Normally we recommend using Websocket connection.

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
Download TDengine
TDengine Database
Enter your information to receive a download link
I agree to receive communications from TDengine and to allow TDengine to store and process my personal data.

You must select the checkbox to continue.

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

    2. Execute the install script

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

      • _ install_client.sh_: install script
      • _ package.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.

    3. 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              |
    =================================
     information_schema             |
     performance_schema             |
     db                             |
    Query OK, 3 rows in database (0.019154s)

    taos>

    Install Client Library​

    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.3.3</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 {
        // ANCHOR: main
        public static void main(String[] args) throws Exception {
            // use
            // String jdbcUrl =
            // "jdbc:TAOS://localhost:6030/dbName?user=root&password=taosdata";
            // if you want to connect a specified database named "dbName".
            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");

            try (Connection conn = DriverManager.getConnection(jdbcUrl, connProps)) {
                System.out.println("Connected to " + jdbcUrl + " successfully.");

                // you can use the connection for execute SQL here

            } catch (Exception ex) {
                // please refer to the JDBC specifications for detailed exceptions info
                System.out.printf("Failed to connect to %s, %sErrMessage: %s%n",
                        jdbcUrl,
                        ex instanceof SQLException ? "ErrCode: " + ((SQLException) ex).getErrorCode() + ", " : "",
                        ex.getMessage());
                // Print stack trace for context in examples. Use logging in production.
                ex.printStackTrace();
                throw ex;
            }
        }
        // ANCHOR_END: main
    }

    view source code

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

            // you can use the connection for execute SQL here

        } catch (Exception ex) {
            // please refer to the JDBC specifications for detailed exceptions info
            System.out.printf("Failed to connect to %s, %sErrMessage: %s%n",
                    jdbcUrl,
                    ex instanceof SQLException ? "ErrCode: " + ((SQLException) ex).getErrorCode() + ", " : "",
                    ex.getMessage());
            // Print stack trace for context in examples. Use logging in production.
            ex.printStackTrace();
            throw ex;
        }
    }

    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 Exception {
        // use
        // String jdbcUrl =
        // "jdbc:TAOS-WS://localhost:6041/dbName?user=root&password=taosdata";
        // if you want to connect a specified database named "dbName".
        String jdbcUrl = "jdbc:TAOS-WS://localhost:6041?user=root&password=taosdata";
        Properties connProps = new Properties();
        connProps.setProperty(TSDBDriver.PROPERTY_KEY_ENABLE_AUTO_RECONNECT, "true");
        connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8");
        connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8");

        try (Connection conn = DriverManager.getConnection(jdbcUrl, connProps)) {
            System.out.println("Connected to " + jdbcUrl + " successfully.");

            // you can use the connection for execute SQL here

        } catch (Exception ex) {
            // please refer to the JDBC specifications for detailed exceptions info
            System.out.printf("Failed to connect to %s, %sErrMessage: %s%n",
                    jdbcUrl,
                    ex instanceof SQLException ? "ErrCode: " + ((SQLException) ex).getErrorCode() + ", " : "",
                    ex.getMessage());
            // Print stack trace for context in examples. Use logging in production.
            ex.printStackTrace();
            throw ex;
        }
    }

    view source code

    More configuration about connection, please refer to Java Client Library

    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.

    TDengine
    SOC 2 Certified
    ISO 27001 Certified
    ISO 27017 Certified

    TDengine™ is a time-series database purpose-built for Industry 4.0 and Industrial IoT. It enables real-time ingestion, storage, analysis, and distribution of petabytes of data per day, generated by billions of sensors and data collectors. With TDengine making big data accessible, valuable, and affordable, digital transformation has never been easier.

    © 2022–2024 TDengine

    Products
    TDengine Enterprise
    TDengine Cloud
    Learn
    Docs
    Blog
    Webinars
    Company
    About
    Newsroom
    Security
    Legal
    Partners
    Newsletter
    Contact Us
    Social