连接器参考手册

TDengine TSDB 提供了丰富的应用程序开发接口。为便于用户快速开发应用，它支持多种编程语言的连接器，其中官方连接器包括 C/C++、Java、Python、Go、Node.js、C# 和 Rust；社区开发者也贡献了多个非官方连接器，例如 ADO.NET、Lua 和 PHP 连接器。这些连接器支持通过原生接口和 WebSocket 接口连接 TDengine TSDB 集群。另外，用户还可以直接调用 taosAdapter 提供的 REST API 接口访问 TDengine TSDB，进行数据写入和查询操作。

连接方式

下图为 TDengine TSDB 客户端和服务端连接方式的架构图： TDengine TSDB connection architecture

如上面的架构图所示，我们有三种方式来访问 TDengine TSDB：

WebSocket 连接：通过连接器使用 taosAdapter 组件提供的 WebSocket API 建立与 taosd 的连接，这种连接方式下文中简称“WebSocket 连接”。 推荐使用 WebSocket 连接。
原生连接：通过连接器使用客户端驱动程序 taosc 直接与服务端程序 taosd 建立连接，这种连接方式下文中简称“原生连接”。
REST API：不使用连接器，通过 HTTP 客户端直接调用 taosAdapter 组件提供的 REST API 建立与 taosd 的连接，这种连接方式下文中简称“REST API”。

备注：客户端驱动程序 taosc 包含了 C 原生和 WebSocket 连接器，使用 C/C++ 语言开发的应用都需要依赖客户端驱动程序 taosc。

对于 WebSocket 连接和原生连接，连接器都提供了相同或相似的 API 操作数据库，只是初始化连接的方式稍有不同，用户在使用上不会感到什么差别。各种连接方式和各语言连接器支持情况请参考连接器功能特性。

关键不同点在于：

使用原生连接，需要保证客户端的驱动程序 taosc 和服务端的 TDengine TSDB 版本保持一致。
使用 WebSocket 连接，除 C/C++ 和 ODBC 连接器外，用户无需安装客户端驱动程序 taosc。即使依赖客户端驱动程序 taosc，也无需保证其和服务端的 TDengine TSDB 版本保持一致。
连接云服务实例，必须使用 WebSocket 连接。
REST API 仅提供执行 SQL 功能，不支持参数绑定和数据订阅。

支持的平台

目前 TDengine TSDB 的连接器可支持的平台广泛，目前包括：X64/X86/ARM64/ARM32/MIPS/LoongArch64(或 Loong64) 等硬件平台，以及 Linux/Win64/Win32/macOS 等开发环境。

对照矩阵如下：

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

CPU	X64 64bit	X64 64bit	X64 64bit	ARM64	ARM64
OS	Linux	Win64	macOS	Linux	macOS
C/C++	●	●	●	●	●
JDBC	●	●	●	●	●
Python	●	●	●	●	●
Go	●	●	●	●	●
NodeJs	●	●	●	●	●
C#	●	●	○	○	○
Rust	●	●	●	○	●
REST API	●	●	●	●	●

版本支持

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

TDengine TSDB 版本	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 TSDB 相同版本
3.0.0.0 及以上	3.0.2 以上	当前版本	3.0 分支	3.0.0	3.1.0	当前版本	与 TDengine TSDB 相同版本
2.4.0.14 及以上	2.0.38	当前版本	develop 分支	1.0.2 - 1.0.6	2.0.10 - 2.0.12	当前版本	与 TDengine TSDB 相同版本
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 TSDB 相同版本
2.2.x.x	2.0.36	当前版本	master 分支	n/a	2.0.7 - 2.0.9	当前版本	与 TDengine TSDB 相同版本
2.0.x.x	2.0.34	当前版本	master 分支	n/a	2.0.1 - 2.0.6	当前版本	与 TDengine TSDB 相同版本

功能特性

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

WebSocket/原生连接

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

备注：Node.js 连接器不支持原生连接。

信息

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

注意

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

REST API

支持 执行 SQL

安装客户端驱动

信息

在没有安装 TDengine TSDB 服务端软件的系统上使用原生接口连接器或使用 C/C++ WebSocket 连接器，才需要安装客户端驱动。

安装步骤

Linux
Windows
MacOS

下载客户端安装包

解压缩软件包

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

解压软件包之后，会在解压目录下看到以下文件 (目录)：
- install_client.sh：安装脚本，用于应用驱动程序
- package.tar.gz：应用驱动安装包
- driver：TDengine 应用驱动 driver
- examples: 各种编程语言的示例程序 (c/C#/go/JDBC/MATLAB/python/R) 运行 install_client.sh 进行安装。
配置 taos.cfg

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

提示

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

下载客户端安装包

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

默认安装路径为：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: 卸载程序
配置 taos.cfg

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

提示

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

下载客户端安装包

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

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

提示

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

安装验证

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

Linux
Windows
MacOS

在 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>

在 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 shell 下直接执行 taos 连接到 TDengine 服务，进入到 TDengine CLI 界面，示例如下：

$ taos

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

taos>

连接器参考手册

连接方式

支持的平台

版本支持

功能特性

WebSocket/原生连接

REST API

安装客户端驱动

安装步骤

安装验证

📄️ Go

📄️ C/C++

📄️ Java

📄️ Rust

📄️ Python

📄️ Node.js

📄️ C#

📄️ R

📄️ ODBC

📄️ REST API

支持和反馈

连接方式​

支持的平台​

版本支持​

功能特性​

WebSocket/原生 连接​

REST API​

安装客户端驱动​

安装步骤​

安装验证​

📄️ Go

📄️ C/C++

📄️ Java

📄️ Rust

📄️ Python

📄️ Node.js

📄️ C#

📄️ R

📄️ ODBC

📄️ REST API

支持和反馈

连接方式

支持的平台

版本支持

功能特性

WebSocket/原生连接

REST API

安装客户端驱动

安装步骤

安装验证