TDengine TSDB provides a rich set of application development interfaces. To facilitate users in quickly developing applications, it supports connectors for multiple programming languages — among which the official ones include those for C/C++, Java, Python, Go, Node.js, C#, and Rust. Community developers have also contributed several unofficial connectors, such as the ADO.NET connector, Lua connector, and PHP connector. These connectors support connecting to the TDengine TSDB cluster via the native interface and WebSocket interface. Additionally, users can directly call the REST API interfaces provided by taosAdapter to access TDengine TSDB for data writing and query operations.

The following is the architecture diagram of the connection methods between TDengine TSDB client and server:

As shown in the architecture diagram above, there are three ways to access TDengine TSDB:

1. WebSocket connection: Establish a connection with taosd through the WebSocket API provided by the taosAdapter component using a connector. This connection method is referred to as "WebSocket connection" in the following text. This method provides a compatibility guarantee. All connectors supporting this connection method are compatible with TDengine TSDB 3.3.6.0 and later server versions. To enjoy this guarantee, each connector must meet the following minimum version requirements: Rust has no special requirements, Java ≥3.6.0, Go ≥3.7.0, Python taos-ws-py ≥0.6.1, Node.js ≥3.2.2, C# ≥3.1.7, and C/C++/ODBC ≥3.3.6.0. WebSocket connection is recommended.

2. Native connection: Establish a direct connection with the server program taosd through the client driver taosc using a connector. This connection method is referred to as "native connection" in the following text.

   Deprecation Notice

   The following connection methods are deprecated and will be discontinued on 2027-01-01

   Native Connection (Java, C#, Go)​

   Please migrate to WebSocket connection:

   • Java: Change jdbc:TAOS:// to jdbc:TAOS-WS://, port from 6030 to 6041. For other configurations, please refer to JDBC Driver.

   • C#: Change protocol=Native to protocol=WebSocket in the connection string, port from 6030 to 6041.

   • Go:

     Go Native to WebSocket Migration Guide

     1. Execute SQL​

     database/sql code requires no modification, mainly replace driver name and DSN protocol header: from taosSql + tcp(6030) to: taosWS + ws(6041).

     2. Data Subscription​

     Migrate from Native's af/tmq to ws/tmq.

     3. STMT and Schemaless​

     Migrate from af to ws/unified.

   C/C++, Python, and Rust native connections will continue to be supported, but still recommend using WebSocket connection for better compatibility.

   REST Connection (Java, Python, Go)​

   Please migrate to WebSocket connection:

   • Java: Change jdbc:TAOS-RS:// to jdbc:TAOS-WS://. For other configurations, please refer to JDBC Driver.

   • Go: database/sql code requires no modification, mainly replace driver name and DSN protocol header: from taosRestful + http(6041) to taosWS + ws(6041).

   • Python:

     Python taosrest to taos-ws-py Migration Guide

     Step 1: Replace Connection Method​

     taosrest typically uses url + user/password parameters to connect:

     from taosrest import connect
     
     conn = connect(url="http://localhost:6041", user="root", password="taosdata")
     

     Migrate to taosws WebSocket DSN:

     import taosws
     
     conn = taosws.connect("ws://root:taosdata@localhost:6041")
     

     Step 2: Replace SQL Execution Method​

     Common taosrest usage is through cursor:

     cursor = conn.cursor()
     cursor.execute("CREATE DATABASE IF NOT EXISTS demo")
     cursor.execute("USE demo")
     cursor.execute("CREATE TABLE IF NOT EXISTS t (ts TIMESTAMP, v INT)")
     cursor.execute("INSERT INTO t VALUES (now, 1)")
     

     When migrating to taosws, you can continue using cursor style for minimal changes:

     cursor = conn.cursor()
     cursor.execute("CREATE DATABASE IF NOT EXISTS demo")
     cursor.execute("USE demo")
     cursor.execute("CREATE TABLE IF NOT EXISTS t (ts TIMESTAMP, v INT)")
     cursor.execute("INSERT INTO t VALUES (now, 1)")
     

     Step 3: Replace Query Result Reading Method​

     Common taosrest usage:

     cursor.execute("SELECT * FROM demo.t")
     rows = cursor.fetchall()
     for row in rows:
         print(row)
     

     When reading query results with taosws, you can also keep cursor style:

     cursor = conn.cursor()
     cursor.execute("SELECT * FROM demo.t")
     rows = cursor.fetchall()
     for row in rows:
         print(row)
     

3. REST API: Establish a connection with taosd by directly calling the REST API provided by the taosAdapter component using an HTTP client, without using a connector. This connection method is referred to as "REST API" in the following text.

Note: The client driver taosc includes C native and WebSocket connectors. Applications developed in C/C++ language must depend on the client driver taosc.

For both WebSocket connections and native connections, connectors provide the same or similar APIs for database operations. The only slight difference lies in the connection initialization methods, so users will not perceive any difference in usage.

For the support status of various connection methods and connectors for different languages, please refer to Connector Features.

The key differences are:

1. Recommended to use WebSocket connection:

   • Except for C/C++ and ODBC connectors, users do not need to install the client driver taosc
   • Provides compatibility guarantee, no need to ensure client and server versions are consistent
   • Must use WebSocket connection to connect to cloud service instances
   • Native connections for Go, C#, and Java are deprecated and will be discontinued on 2027-01-01, please migrate in advance

2. Native connection (deprecated; to be discontinued on 2027-01-01 for Go, C#, and Java):

   • Users using Go, C#, and Java connectors should note that native connection is deprecated and will be discontinued on 2027-01-01
   • The version of the client driver taosc must be consistent with that of the server-side TDengine TSDB
   • C/C++, Python, and Rust native connections will continue to be supported

3. REST API:

   • Only provides the function of executing SQL
   • Does not support parameter binding or data subscription
   • REST connections for Java, Python, and Go are deprecated and will be discontinued on 2027-01-01, please migrate to WebSocket connection

If you choose a native connection and your application is not running on the same server as TDengine, you need to install the client driver first; otherwise, you can skip this step. To avoid incompatibility between the client driver and the server, please use consistent versions.

Recommended to use WebSocket connection, no need to install client driver.

Installation Steps​

Installation Verification​

After completing the above installation and configuration, and confirming that the TDengine service has started running normally, you can log in using the TDengine command-line program taos included in the installation package.

$ taos

taos> show databases;
              name              |
=================================
 information_schema             |
 performance_schema             |
 db                             |
Query OK, 3 rows in database (0.019154s)

taos>

<dependency>
  <groupId>com.taosdata.jdbc</groupId>
  <artifactId>taos-jdbcdriver</artifactId>
  <version>3.8.2</version>
</dependency>

Before proceeding with this step, please ensure that there is a running TDengine that can be accessed, and that the server's FQDN is configured correctly. The following example code assumes that TDengine is installed on the local machine, and that the FQDN (default localhost) and serverPort (default 6030) are using the default configuration.

Connection Parameters​

There are many configuration options for connecting, so before establishing a connection, let's first introduce the parameters used by the connectors of each language to establish a connection.

WebSocket Connection​

Below are code examples for establishing WebSocket connections in various language connectors. It demonstrates how to connect to the TDengine database using WebSocket and set some parameters for the connection. The whole process mainly involves establishing the database connection and handling exceptions.

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

Native Connection​

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;
    }
}

Some connectors offer a connection pool, or can be used in conjunction with existing connection pool components. By using a connection pool, applications can quickly obtain available connections from the pool, avoiding the overhead of creating and destroying connections with each operation. This not only reduces resource consumption but also improves response speed. Additionally, connection pools support the management of connections, such as limiting the maximum number of connections and checking the validity of connections, ensuring efficient and reliable use of connections. We recommend managing connections using a connection pool.
Below are code examples of connection pool support for various language connectors.

public static void main(String[] args) throws Exception {
    HikariConfig config = new HikariConfig();
    // jdbc properties
    config.setJdbcUrl("jdbc:TAOS-WS://127.0.0.1:6041/log?varcharAsString=true");
    config.setUsername("root");
    config.setPassword("taosdata");
    // connection pool configurations
    config.setMinimumIdle(10); // minimum number of idle connection
    config.setMaximumPoolSize(10); // maximum number of connection in the pool
    config.setConnectionTimeout(30000); // maximum wait milliseconds for get connection from pool
    config.setMaxLifetime(0); // maximum life time for each connection
    config.setIdleTimeout(0); // max idle time for recycle idle connection

    HikariDataSource dataSource = new HikariDataSource(config); // create datasource

    Connection connection = dataSource.getConnection(); // get connection
    Statement statement = connection.createStatement(); // get statement

    // query or insert
    // ...
    statement.close();
    connection.close(); // put back to connection pool
    dataSource.close();
}

public static void main(String[] args) throws Exception {
    String url = "jdbc:TAOS-WS://127.0.0.1:6041/log?varcharAsString=true";

    DruidDataSource dataSource = new DruidDataSource();
    // jdbc properties
    dataSource.setDriverClassName("com.taosdata.jdbc.ws.WebSocketDriver");
    dataSource.setUrl(url);
    dataSource.setUsername("root");
    dataSource.setPassword("taosdata");
    // pool configurations
    dataSource.setInitialSize(10);
    dataSource.setMinIdle(10);
    dataSource.setMaxActive(10);
    dataSource.setMaxWait(30000);

    Connection connection = dataSource.getConnection(); // get connection
    Statement statement = connection.createStatement(); // get statement
    // query or insert
    // ...

    statement.close();
    connection.close(); // put back to connection pool
    dataSource.close();
}