Skip to main content

Client Libraries

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.

Connection Methods​

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

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. 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.
  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. When using a native connection, the version of the client driver taosc must be consistent with that of the server-side TDengine TSDB.
  2. When using a WebSocket connection, except for C/C++ and ODBC connectors, users do not need to install the client driver taosc. Even if the client driver taosc is required, there is no need to ensure its version is consistent with that of the server-side TDengine TSDB.
  3. To connect to a cloud service instance, a WebSocket connection must be used.
  4. REST API only provides the function of executing SQL, and does not support parameter binding or data subscription.

Supported Platforms​

Currently, the connectors for TDengine TSDB support a wide range of platforms, including hardware platforms such as X64/X86/ARM64/ARM32/MIPS/LoongArch64 (or Loong64), and development environments such as Linux/Win64/Win32/macOS.

The compatibility matrix is as follows:

CPUX64 64bitX64 64bitX64 64bitARM64ARM64
OSLinuxWin64macOSLinuxmacOS
C/C++●●●●●
JDBC●●●●●
Python●●●●●
Go●●●●●
NodeJs●●●●●
C#●●○○○
Rust●●●○●
REST API●●●●●

Note: ● indicates official testing and verification passed, ○ indicates non-official testing and verification passed, -- indicates not verified.

Version Support​

TDengine version updates often add new features. The list below shows the best matching connector versions for each TDengine version.

TDengine VersionJavaPythonGoC#Node.jsRustC/C++
3.3.0.0 and above3.3.0 and abovetaospy 2.7.15 and above, taos-ws-py 0.3.2 and above3.5.5 and above3.1.3 and above3.1.0 and aboveCurrent versionSame as TDengine version
3.0.0.0 and above3.0.2 and aboveCurrent version3.0 branch3.0.03.1.0Current versionSame as TDengine version
2.4.0.14 and above2.0.38Current versiondevelop branch1.0.2 - 1.0.62.0.10 - 2.0.12Current versionSame as TDengine version
2.4.0.4 - 2.4.0.132.0.37Current versiondevelop branch1.0.2 - 1.0.62.0.10 - 2.0.12Current versionSame as TDengine version
2.2.x.x2.0.36Current versionmaster branchn/a2.0.7 - 2.0.9Current versionSame as TDengine version
2.0.x.x2.0.34Current versionmaster branchn/a2.0.1 - 2.0.6Current versionSame as TDengine version

Feature Support​

The following table outlines the support for TDengine TSDB features across different connectors:

WebSocket/Native Connections​

FeatureJavaPythonGoC#Node.jsRustC/C++
Connection ManagementSupportedSupportedSupportedSupportedSupportedSupportedSupported
Execute SQLSupportedSupportedSupportedSupportedSupportedSupportedSupported
Parameter BindingSupportedSupportedSupportedSupportedSupportedSupportedSupported
Data Subscription (TMQ)SupportedSupportedSupportedSupportedSupportedSupportedSupported
Schema-less WriteSupportedSupportedSupportedSupportedSupportedSupportedSupported

Note: The Node.js connector does not support native connections.

info

Due to differences in database framework specifications across programming languages, it does not mean that all C/C++ interfaces require corresponding encapsulation support.

warning
  • Regardless of the programming language connector used, for TDengine TSDB version 2.0 and above, it is recommended that each thread of a database application establishes an independent connection or creates a thread-based connection pool. This avoids mutual interference of the "USE statement" state within the connection between threads (however, the connection's query and write operations are thread-safe).

REST API​

Supports Execute SQL

Install Client Driver​

info

You only need to install the client driver if you are using a native interface connector on a system where the TDengine server software is not installed.

Installation Steps​

  1. Download the client installation package

    1. Unzip the software package

      Place the package in any directory where the current user has read and write access, then execute the following command: tar -xzvf TDengine-client-VERSION.tar.gz Replace VERSION with the actual version string.

    2. Run the installation script

      After unzipping the package, you will see the following files (directories) in the unzipped directory:

      • install_client.sh: Installation script, used for applying the driver
      • package.tar.gz: Application driver installation package
      • driver: TDengine application driver
      • examples: Sample programs for various programming languages (c/C#/go/JDBC/MATLAB/python/R) Run install_client.sh to install.

    3. Configure taos.cfg

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

    tip
    1. If the TDengine service is not deployed on this machine and only the application driver is installed, then only firstEP needs to be configured in taos.cfg, there is no need to configure FQDN on this machine.
    2. To prevent the "Unable to resolve FQDN" error when connecting to the server, it is recommended to ensure that the /etc/hosts file on your machine is configured with the correct FQDN value of the server, or that the DNS service is properly configured.

    Installation Verification​

    After completing the above installation and configuration, and confirming that the TDengine service has started running normally, you can now use the TDengine CLI tool to log in.

    In the Linux shell, execute taos directly to connect to the TDengine service, entering the TDengine CLI interface, as shown below:

    $ taos

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

    taos>

    📄️ C/C++

    C/C++ developers can use the TDengine client driver (i.e., C/C++ connector) to develop their own applications to connect to the TDengine cluster to complete data storage, query, and other functions. The API of the TDengine client driver is similar to the C API of MySQL. When using the application, it is necessary to include the TDengine header file, which lists the function prototypes of the provided API; the application must also link to the corresponding dynamic library on the platform.