Skip to main content

Connector Reference Guide

TDengine provides a rich set of APIs (application development interface). To facilitate users to develop their applications quickly, TDengine supports client libraries for multiple programming languages, including official libraries for C/C++, Java, Python, Go, Node.js, C#, and Rust. These client libraries support connecting to TDengine clusters using both native interfaces (taosc) and REST interfaces (not supported in a few languages yet). Community developers have also contributed several unofficial client libraries, such as the ADO.NET, Lua, and PHP libraries.

TDengine client library connections

Supported platforms

Currently, TDengine's native interface client libraries can support platforms such as x64 and ARM hardware platforms and Linux/Windows/macOS development environments. The comparison matrix is as follows.

CPUOSJavaPythonGoNode.jsC#RustC/C++
X86 64bitLinux
X86 64bitWin64
X86 64bitmacOS
ARM64Linux
ARM64macOS

Where ● means the official test verification passed, ○ means the unofficial test verification passed, -- means no assurance.

Using REST connection can support a broader range of operating systems as it does not rely on client drivers.

Version support

TDengine version updates often add new features, and the client library versions in the list are the best-fit versions of the library.

TDengine VersionsJavaPythonGoC#Node.jsRust
3.0.0.0 and later3.0.2 +latest version3.0 branch3.0.03.0.0current version
**2.4.0.14 and up **2.0.38latest versiondevelop branch1.0.2 - 1.0.62.0.10 - 2.0.12current version
**2.4.0.4 - 2.4.0.13 **2.0.37latest versiondevelop branch1.0.2 - 1.0.62.0.10 - 2.0.12current version
**2.2.x.x **2.0.36latest versionmaster branchn/a2.0.7 - 2.0.9current version
**2.0.x.x **2.0.34latest versionmaster branchn/a2.0.1 - 2.0.6current version

Functional Features

Comparing the client library support for TDengine functional features as follows.

Using the native interface (taosc)

Functional FeaturesJavaPythonGoC#Node.jsRust
Connection ManagementSupportSupportSupportSupportSupportSupport
Regular QuerySupportSupportSupportSupportSupportSupport
Parameter BindingSupportSupportSupportSupportSupportSupport
Subscription (TMQ)SupportSupportSupportSupportSupportSupport
SchemalessSupportSupportSupportSupportSupportSupport
info

The different database framework specifications for various programming languages do not mean that all C/C++ interfaces need a wrapper.

Use HTTP Interfaces (REST or WebSocket)

Functional FeaturesJavaPythonGoC#Node.jsRust
Connection ManagementSupportSupportSupportSupportSupportSupport
Regular QuerySupportSupportSupportSupportSupportSupport
Parameter BindingSupportSupportSupportSupportNot SupportedSupport
**Subscription (TMQ) **SupportSupportSupportSupportNot SupportedSupport
SchemalessSupportSupportSupportSupportNot SupportedNot Supported
**Bulk Pulling (based on WebSocket) **SupportSupportSupportSupportSupportSupport
warning
  • Regardless of the programming language chosen for the client library, TDengine versions 2.0 and above recommend that each thread of a database application create a separate connection. Or create a connection pool based on threads to avoid interference between threads with the "USE statement" state within a connection (but the connection's query and write operations are thread-safe).

Install Client Driver

info

The client driver needs to be installed if you use the native interface connection on a system that does not have the TDengine server software installed.

Install

  1. Download the client installation package
    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 completing the above installation and configuration and you have confirmed that the TDengine service is up and running, you can execute the TDengine CLI tool to log in.

    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>