连接器参考手册

TDengine 提供了丰富的应用程序开发接口，为了便于用户快速开发自己的应用，TDengine 支持了多种编程语言的连接器，其中官方连接器包括支持 C/C++、Java、Python、Go、Node.js、C# 和 Rust 的连接器。这些连接器支持使用原生接口（taosc）和 WebSocket 接口连接 TDengine 集群。社区开发者也贡献了多个非官方连接器，例如 ADO.NET 连接器、Lua 连接器和 PHP 连接器。

支持的平台

目前 TDengine 的原生接口连接器可支持的平台包括：X64/ARM64 等硬件平台，以及 Linux/Win64 等开发环境。对照矩阵如下：

CPU	OS	Java	Python	Go	Node.js	C#	Rust	C/C++
X86 64bit	Linux	●	●	●	●	●	●	●
X86 64bit	Win64	●	●	●	●	●	●	●
X86 64bit	macOS	●	●	●	○	○	●	●
ARM64	Linux	●	●	●	●	○	○	●
ARM64	macOS	●	●	●	○	○	●	●

其中 ● 表示官方测试验证通过，○ 表示非官方测试验证通过，-- 表示未经验证。

使用 REST 连接由于不依赖客户端驱动可以支持更广泛的操作系统。

版本支持

TDengine 版本更新往往会增加新的功能特性，列表中的连接器版本为连接器最佳适配版本。

TDengine 版本	Java	Python	Go	C#	Node.js	Rust	C/C++
3.3.0.0 及以上	3.3.0及以上	taospy 2.7.15及以上，taos-ws-py 0.3.2及以上	3.5.5及以上	3.1.3及以上	3.1.0及以上	当前版本	与 TDengine 相同版本
3.0.0.0 及以上	3.0.2以上	当前版本	3.0 分支	3.0.0	3.1.0	当前版本	与 TDengine 相同版本
2.4.0.14 及以上	2.0.38	当前版本	develop 分支	1.0.2 - 1.0.6	2.0.10 - 2.0.12	当前版本	与 TDengine 相同版本
2.4.0.4 - 2.4.0.13	2.0.37	当前版本	develop 分支	1.0.2 - 1.0.6	2.0.10 - 2.0.12	当前版本	与 TDengine 相同版本
2.2.x.x	2.0.36	当前版本	master 分支	n/a	2.0.7 - 2.0.9	当前版本	与 TDengine 相同版本
2.0.x.x	2.0.34	当前版本	master 分支	n/a	2.0.1 - 2.0.6	当前版本	与 TDengine 相同版本

功能特性

连接器对 TDengine 功能特性的支持对照如下：

使用原生接口（taosc）

功能特性	Java	Python	Go	C#	Rust	C/C++
连接管理	支持	支持	支持	支持	支持	支持
执行 SQL	支持	支持	支持	支持	支持	支持
参数绑定	支持	支持	支持	支持	支持	支持
数据订阅（TMQ）	支持	支持	支持	支持	支持	支持
无模式写入	支持	支持	支持	支持	支持	支持

info

由于不同编程语言数据库框架规范不同，并不意味着所有 C/C++ 接口都需要对应封装支持。

使用 http REST 接口

功能特性	Java	Python	Go
连接管理	支持	支持	支持
执行 SQL	支持	支持	支持

使用 WebSocket 接口

功能特性	Java	Python	Go	C#	Node.js	Rust	C/C++
连接管理	支持	支持	支持	支持	支持	支持	支持
执行 SQL	支持	支持	支持	支持	支持	支持	支持
参数绑定	支持	支持	支持	支持	支持	支持	支持
数据订阅（TMQ）	支持	支持	支持	支持	支持	支持	支持
无模式写入	支持	支持	支持	支持	支持	支持	支持

warning

• 无论选用何种编程语言的连接器，2.0 及以上版本的 TDengine 推荐数据库应用的每个线程都建立一个独立的连接，或基于线程建立连接池，以避免连接内的“USE statement”状态量在线程之间相互干扰（但连接的查询和写入操作都是线程安全的）。

安装客户端驱动

info

只有在没有安装 TDengine 服务端软件的系统上使用原生接口连接器才需要安装客户端驱动。

安装步骤

Linux

1. 下载客户端安装包

下载 TDengine

输入您的电子邮箱以接收下载链接

同意涛思数据通过此邮件地址联系我

请勾选同意，便于我们通过邮件发送安装包给您。

2. 解压缩软件包

   将软件包放置在当前用户可读写的任意目录下，然后执行下面的命令：tar -xzvf TDengine-client-VERSION.tar.gz 其中 VERSION 需要替换为实际版本的字符串。

3. 执行安装脚本

   解压软件包之后，会在解压目录下看到以下文件(目录)：

   • _ install_client.sh_：安装脚本，用于应用驱动程序
   • _ package.tar.gz_：应用驱动安装包
   • _ driver_：TDengine 应用驱动 driver
   • examples: 各种编程语言的示例程序(c/C#/go/JDBC/MATLAB/python/R) 运行 install_client.sh 进行安装。

4. 配置 taos.cfg

   编辑 taos.cfg 文件（默认路径/etc/taos/taos.cfg），将 firstEP 修改为 TDengine 服务器的 End Point，例如：h1.tdengine.com:6030

tip

1. 如本机没有部署 TDengine 服务，仅安装了应用驱动，则 taos.cfg 中仅需配置 firstEP，无需在本机配置 FQDN。
2. 为防止与服务器端连接时出现“Unable to resolve FQDN”错误，建议确认本机的 /etc/hosts 文件已经配置了服务器正确的 FQDN 值，或配置好了 DNS 服务。

Windows

1. 下载客户端安装包

   下载 TDengine

   

   输入您的电子邮箱以接收下载链接

   同意涛思数据通过此邮件地址联系我

   请勾选同意，便于我们通过邮件发送安装包给您。

2. 执行安装程序，按提示选择默认值，完成安装

3. 安装路径

   默认安装路径为：C:\TDengine，其中包括以下文件(目录)：

   • taos.exe：TDengine CLI 命令行程序
   • taosadapter.exe：提供 RESTful 服务和接受其他多种软件写入请求的服务端可执行文件
   • taosBenchmark.exe：TDengine 测试程序
   • cfg : 配置文件目录
   • driver: 应用驱动动态链接库
   • examples: 示例程序 bash/C/C#/go/JDBC/Python/Node.js
   • include: 头文件
   • log : 日志文件
   • unins000.exe: 卸载程序

4. 配置 taos.cfg

   编辑 taos.cfg 文件（默认路径 C:\TDengine\cfg\taos.cfg），将 firstEP 修改为 TDengine 服务器的 End Point，例如：h1.tdengine.com:6030。

tip

1. 如利用 FQDN 连接服务器，必须确认本机网络环境 DNS 已配置好，或在 hosts 文件中添加 FQDN 寻址记录, 如编辑 C:\Windows\system32\drivers\etc\hosts，添加类似如下的记录：192.168.1.99 h1.taos.com
2. 卸载：运行 unins000.exe 可卸载 TDengine 应用驱动。

MacOS

1. 下载客户端安装包

   下载 TDengine

   

   输入您的电子邮箱以接收下载链接

   同意涛思数据通过此邮件地址联系我

   请勾选同意，便于我们通过邮件发送安装包给您。

2. 执行安装程序，按提示选择默认值，完成安装。如果安装被阻止，可以右键或者按 Ctrl 点击安装包，选择 打开。

3. 配置 taos.cfg

   编辑 taos.cfg 文件（默认路径/etc/taos/taos.cfg），将 firstEP 修改为 TDengine 服务器的 End Point，例如：h1.tdengine.com:6030

tip

1. 如本机没有部署 TDengine 服务，仅安装了应用驱动，则 taos.cfg 中仅需配置 firstEP，无需在本机配置 FQDN。
2. 为防止与服务器端连接时出现“Unable to resolve FQDN”错误，建议确认本机的 /etc/hosts 文件已经配置了服务器正确的 FQDN 值，或配置好了 DNS 服务。

安装验证

以上安装和配置完成后，并确认 TDengine 服务已经正常启动运行，此时可以执行 TDengine CLI 工具进行登录。

Linux

在 Linux shell 下直接执行 taos 连接到 TDengine 服务，进入到 TDengine CLI 界面，示例如下：

$ taos

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

taos>

Windows

在 cmd 下进入到 C:\TDengine 目录下直接执行 taos.exe，连接到 TDengine 服务，进入到 TDengine CLI 界面，示例如下：

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   |
===============================================================================================================================================================================================================================================================================================================================================================================================================================
 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 |
 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 |
 test                           | 2022-08-04 16:46:40.506 |       2 |                     0 |       1 | off    | 14400m     | 5256000m,5256000m,5256000m     |          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.123000s)

taos>

MacOS

在 macOS shell 下直接执行 taos 连接到 TDengine 服务，进入到 TDengine CLI 界面，示例如下：

$ taos

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

taos>

📄️ Go

driver-go 是 TDengine 的官方 Go 语言连接器，实现了 Go 语言 database/sql 包的接口。Go 开发人员可以通过它开发存取 TDengine 集群数据的应用软件。

📄️ C/C++

C/C++ 开发人员可以使用 TDengine 的客户端驱动，即 C/C++连接器 （以下都用 TDengine 客户端驱动表示），开发自己的应用来连接 TDengine 集群完成数据存储、查询以及其他功能。TDengine 客户端驱动的 API 类似于 MySQL 的 C API。应用程序使用时，需要包含 TDengine 头文件，里面列出了提供的 API 的函数原型；应用程序还要链接到所在平台上对应的动态库。

📄️ Java

TDengine Java 连接器基于标准 JDBC API 实现, 并提供原生连接与 REST连接两种连接器。

📄️ Rust

Crates.io Crates.io docs.rs

📄️ Python

taospy 是 TDengine 的官方 Python 连接器。taospy 提供了丰富的 API， 使得 Python 应用可以很方便地使用 TDengine。tasopy 对 TDengine 的原生接口和 REST 接口都进行了封装， 分别对应 tasopy 的两个子模块：taos 和 taosrest。除了对原生接口和 REST 接口的封装，taospy 还提供了符合 Python 数据访问规范(PEP 249)的编程接口。这使得 taospy 和很多第三方工具集成变得简单，比如 SQLAlchemy 和 pandas

📄️ Node.js

@tdengine/websocket 是 TDengine 的官方 Node.js 语言连接器。Node.js 开发人员可以通过它开发存取 TDengine 数据库的应用软件。

📄️ C#

TDengine.Connector 是 TDengine 提供的 C# 语言连接器。C# 开发人员可以通过它开发存取 TDengine 集群数据的 C# 应用软件。

📄️ R

通过 R 语言中的 RJDBC 库可以使 R 语言程序支持访问 TDengine 数据。以下是安装过程、配置过程以及 R 语言示例代码。

📄️ PHP

php-tdengine 是由社区贡献的 PHP 连接器扩展，还特别支持了 Swoole 协程化。

📄️ ODBC

TDengine ODBC 是为 TDengine 实现的 ODBC 驱动程序，支持 Windows 系统的应用（如 PowerBI 等）以及用户自定义开发的应用程序，通过 ODBC 标准接口访问本地、远程和云服务的 TDengine 数据库。

📄️ REST API

详细介绍 TDengine 提供的 RESTful API.