TDengine 连接器全解析：WebSocket、原生连接与 REST API 的选型、安装与兼容矩阵

• 数据库
• 时序数据库
• 物联网
• 大数据
• 实时分析
• 云原生

TDengine 为开发者提供了覆盖 C/C++、Java、Python、Go、Node.js、C#、Rust 等主流语言的官方连接器，支持通过原生接口（Native RPC）、WebSocket 接口以及 REST API 三种方式访问 TDengine TSDB 集群。本文以官方开发者指南《Client Libraries》为核心，系统梳理三种连接方式的工作原理、平台与版本兼容矩阵、特性支持差异，以及客户端驱动（taosc）在 Linux / Windows / macOS 上的完整安装与验证流程，帮助你在实际项目中快速做出连接方案选型并完成环境搭建。

连接方式总览：三种访问 TDengine 的途径

TDengine TSDB 提供了丰富的应用开发接口。官方连接器覆盖 C/C++、Java、Python、Go、Node.js、C# 和 Rust 七种语言；社区开发者还贡献了 ADO.NET、Lua、PHP 等非官方连接器。所有连接器均支持通过原生接口和WebSocket 接口连接 TDengine TSDB 集群，此外用户还可以直接调用 taosAdapter 提供的 REST API 完成数据写入与查询。

下图展示了 TDengine 客户端与服务器之间三种连接方式的整体架构：

从架构图可以看出，访问 TDengine TSDB 共有三条路径：

1. WebSocket 连接：连接器通过 taosAdapter 组件提供的 WebSocket API 与 taosd 建立连接，下文统称 "WebSocket 连接"。该方式提供兼容性保证——所有支持此连接方式的连接器均与 TDengine TSDB 3.3.6.0 及更高版本的服务端兼容。享受该保证需要满足各连接器的最低版本要求：Rust 无特殊要求，Java ≥ 3.6.0，Go ≥ 3.7.0，Python（taos-ws-py）≥ 0.6.1，Node.js ≥ 3.2.2，C# ≥ 3.1.7，C/C++/ODBC ≥ 3.3.6.0。官方推荐优先使用 WebSocket 连接。
2. 原生连接：连接器通过客户端驱动 taosc 与服务器程序 taosd 建立直接连接，下文统称 "原生连接"。
3. REST API：不使用连接器，直接通过 HTTP 客户端调用 taosAdapter 组件提供的 REST API 与 taosd 通信，下文统称 "REST API"。

注意：客户端驱动 taosc 内部包含 C 原生连接器和 WebSocket 连接器，因此 C/C++ 语言开发的应用必须依赖客户端驱动 taosc。

对于 WebSocket 连接与原生连接，各连接器提供了相同或相近的数据库操作 API，唯一细微差别在于连接初始化方式，因此使用者在日常开发中几乎感知不到差异。两种连接方式的关键区别总结如下：

重要迁移提示：Go、C#、Java 连接器的原生连接已标记为弃用，将于 2027-01-01 停止支持，请提前迁移至 WebSocket 连接；同样，Java、Python、Go 的 REST 连接也已弃用，将于同一日期停止支持，请迁移到 WebSocket 连接。

REST API 方式的限制也需要留意：它只提供执行 SQL 的功能，不支持参数绑定（Parameter Binding）和数据订阅（TMQ）。

支持的平台与硬件架构

TDengine 连接器覆盖广泛的硬件平台与开发环境，包括 X64/X86/ARM64/ARM32/MIPS/LoongArch64（或 Loong64）等硬件平台，以及 Linux/Win64/Win32/macOS 等开发环境。官方兼容性矩阵如下（● 表示官方测试验证通过，○ 表示非官方测试验证通过，-- 表示未验证）：

从矩阵可以看到：C/C++、JDBC、Python、Go、Node.js 在全部五种平台组合上均通过官方验证；C# 与 Rust 在部分组合上仅通过非官方验证（C# 的 macOS/ARM64 组合未验证）；REST API 本身与具体语言无关，在所有平台组合上均通过官方验证。

连接器与 TDengine 版本匹配关系

TDengine 版本更新时常伴随新功能引入。下表给出了各 TDengine 版本对应的最佳连接器版本，是选型时的直接依据：

需要注意，C/C++ 连接器（即客户端驱动 taosc）的版本号与 TDengine 服务器版本严格对应。尽管在前三段版本号相同（仅第四段不同）时，较低版本的客户端驱动可以兼容较高版本的服务器，但官方强烈建议使用与 TDengine 服务器相同版本的客户端驱动，且强烈不建议使用较高版本的客户端驱动访问较低版本的服务器。从源码结构看，客户端驱动的发布与服务器版本保持一致，例如 include/client/taos.h 定义了 C 语言连接 API，其二进制随各发行版同步打包。

特性支持矩阵：WebSocket 与原生连接

下表展示了不同连接器对 TDengine TSDB 核心特性的支持情况（针对 WebSocket/原生连接）：

注意：Node.js 连接器不支持原生连接，仅支持 WebSocket 连接。

此外还有两点需要了解：

• 由于各编程语言数据库框架规范存在差异，并不意味着所有 C/C++ 接口都需要在其他语言的连接器中提供对应的封装支持。
• 无论使用哪种编程语言的连接器，对于 TDengine TSDB 2.0 及以上版本，都建议数据库应用的每个线程建立独立的连接，或创建基于线程的连接池，以避免线程之间共享连接时 "USE statement" 状态互相干扰（不过，连接的查询和写入操作本身是线程安全的）。

对于 REST API 方式，特性支持相对有限：仅支持执行 SQL（Execute SQL），不支持参数绑定与数据订阅。

安装客户端驱动（taosc）

只有在以下两种场景下才需要单独安装客户端驱动：

• 使用原生接口连接器，且当前系统未安装 TDengine 服务器软件；
• 使用C/C++ WebSocket 连接器。

如果你使用其他语言的 WebSocket 连接器（如 Java、Python、Go、Node.js、C#、Rust），则无需安装客户端驱动。下面按操作系统分别给出安装步骤。

Linux 安装步骤

1. 下载客户端安装包：获取 TDengine TSDB 企业版客户端（Linux-Generic 平台）安装包。
2. 解压软件包：将安装包放到当前用户具有读写权限的任意目录，执行：

   tar -xzvf tdengine-tsdb-enterprise-client-{{VERSION}}-linux-x64.tar.gz

3. 运行安装脚本：解压后，解压目录中会看到以下文件（目录）：
   • install_client.sh：安装脚本，用于应用驱动程序；
   • package.tar.gz：应用驱动安装包；
   • driver：TDengine 应用驱动；
   • examples：各编程语言的示例程序。 运行install_client.sh完成安装。
4. 配置 taos.cfg：编辑taos.cfg文件（默认路径/etc/taos/taos.cfg），将firstEP改为 TDengine 服务器的 End Point，例如h1.tdengine.com:6030。

提示：

1. 从 3.4.0.0 版本开始，企业版与社区版不完全兼容。为避免两者互联出现兼容性问题，请确保安装与服务器对应的客户端驱动。使用社区版驱动连接企业版服务器会报错 "Edition not compatible"，反之亦然。
2. 如果 TDengine 服务未部署在本机、仅安装应用驱动，则taos.cfg中只需配置firstEP，本机无需配置FQDN。
3. 为避免连接服务器时出现 "Unable to resolve FQDN" 错误，建议确保本机/etc/hosts文件已配置服务器的正确 FQDN 值，或正确配置 DNS 服务。

Windows 安装步骤

1. 下载客户端安装包：获取 TDengine TSDB 企业版客户端（Windows 平台）安装包。
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。

提示：

1. 企业版与社区版 3.4.0.0 起不完全兼容，请使用与服务器对应的客户端驱动，否则报错 "Edition not compatible"。
2. 如果使用 FQDN 连接服务器，请确保本地网络 DNS 配置正确，或在 hosts 文件中添加 FQDN 解析记录，例如编辑C:\Windows\system32\drivers\etc\hosts，添加类似192.168.1.99 h1.taos.com的记录。
3. 卸载：运行unins000.exe即可卸载 TDengine 应用驱动。

macOS 安装步骤

1. 下载客户端安装包：获取 TDengine TSDB 企业版客户端（macOS 平台）安装包。
2. 运行安装程序：按提示选择默认值完成安装。若安装被阻止，可右键或按住 Ctrl 点击安装包，然后选择Open（打开）。
3. 配置 taos.cfg：编辑taos.cfg文件（默认路径/etc/taos/taos.cfg），将firstEP改为 TDengine 服务器的 End Point，例如h1.tdengine.com:6030。

提示：与 Linux 类似，企业版与社区版 3.4.0.0 起不完全兼容；若 TDengine 服务未部署在本机，taos.cfg只需配置firstEP；为避免 "Unable to resolve FQDN" 错误，请确保/etc/hosts已配置服务器 FQDN 或 DNS 服务正确。

安装验证

完成上述安装与配置、并确认 TDengine 服务已正常启动后，可以使用 TDengine CLI 工具登录验证。

Linux / 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>

Windows 验证

在 cmd 中进入C:\TDengine目录，直接执行taos.exe连接 TDengine 服务：

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>

若能看到information_schema、performance_schema等数据库列表，即表示客户端驱动安装成功、与服务器的连接配置正确。

各语言连接器开发指南导航

在连接方案选定、客户端驱动就绪之后，可以进一步参考针对各语言的具体开发指南，它们与本页同属一个文档目录，包含完整的 API 使用示例：

• C/C++ 连接器：以taos.h头文件与taos动态库为基础，taos_connect()默认走原生连接，通过taos_options(TSDB_OPTION_DRIVER, "websocket")切换为 WebSocket 连接；该选项必须在程序开头调用且只能调用一次。
• Java 连接器
• Go 连接器
• Rust 连接器
• Python 连接器（taospy / taos-ws-py）
• Node.js 连接器（仅支持 WebSocket 连接）
• C# 连接器
• R 语言连接器
• ODBC 连接器
• REST API 参考

以 C/C++ 为例，无论采用哪种连接方式，都需要包含taos.h头文件并链接taos动态库：

#include "taos.h"

安装 TDengine 客户端或服务器后，头文件与动态库的位置如下：

对应的连接示例：

// 原生连接（TDengine 默认连接方式） TAOS *taos = taos_connect(ip, user, password, database, port); // WebSocket 连接：先设置驱动类型，再调用 taos_connect taos_options(TSDB_OPTION_DRIVER, "websocket"); TAOS *taos = taos_connect(ip, user, password, database, port);

从源码结构看，C 客户端驱动的 API 原型定义于 include/client/taos.h，各语言连接器的原生封装实现集中维护在 source/client/wrapper 目录（含 JNI 等包装层），可作为深入理解连接器内部机制的起点。

REST API 快速验证

REST API 不依赖任何 TDengine 库，只要开发语言支持 HTTP 协议即可使用，且由 taosAdapter 提供，使用前必须确保 taosAdapter 已运行。在 Linux 下 taosAdapter 默认由 systemd 管理，可用systemctl start taosadapter启动。

以 Ubuntu 环境下的curl为例（请确认已安装 curl），验证 RESTful 接口是否正常工作。下面的示例列出所有数据库，请将h1.tdengine.com和 6041（默认端口）替换为实际运行的 TDengine 服务 FQDN 与端口：

curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" \ -d "select name, ntables, status from information_schema.ins_databases;" \ h1.tdengine.com:6041/rest/sql

返回code: 0即表示验证通过。注意 RESTful 接口是无状态的，USE db_name命令不会生效，所有表名、超级表名的引用都需要带数据库名前缀；也可以在 RESTful URL 中指定 db_name，此时 SQL 未指定库名前缀时会使用 URL 中的 db_name。

小结：如何选择合适的连接方式

综合本文内容，连接方案选型可以遵循以下原则：

1. 新项目优先选择 WebSocket 连接：它提供版本兼容性保证、无需安装客户端驱动（除 C/C++ 与 ODBC 外）、是连接云服务实例的唯一途径，也是官方明确推荐的连接方式。
2. 使用 Java、Python、Go 的连接器时注意迁移窗口：Go、C#、Java 的原生连接以及 Java、Python、Go 的 REST 连接均计划于 2027-01-01 停止支持，相关应用应尽早迁移到 WebSocket 连接。
3. C/C++、Python、Rust 的原生连接将继续支持：如果追求最低通信开销或已有基于 taosc 的应用，可以继续使用原生连接，但务必保持客户端驱动与服务器版本一致。
4. REST API 适合轻量集成：它只支持执行 SQL，不支持参数绑定与数据订阅，适合脚本、监控集成等简单场景，且无需任何 TDengine 客户端库。

• 数据库
• 时序数据库
• 物联网
• 大数据
• 实时分析
• 云原生