跳到主要内容

连接器参考手册

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：

  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 建立连接，这种连接方式下文中简称"原生连接"。

    废弃通知

    以下连接方式将于 2027-01-01 下线

    原生连接（Java、C#、Go）​

    请迁移到 WebSocket 连接方式：

    • Java: 将 jdbc:TAOS:// 改为 jdbc:TAOS-WS://，端口从 6030 改为 6041，其余配置请仔细阅读 JDBC 驱动。

    • C#: 将连接字符串中的 protocol=Native 改为 protocol=WebSocket，端口从 6030 改为 6041。

    • Go:

      Go Native 迁移到 WebSocket 快速指南

      1. 执行 SQL：database/sql 代码无需修改，主要替换驱动名称和 DSN 协议头：从 taosSql + tcp(6030) 到：taosWS + ws(6041)。 2. 数据订阅：af/tmq 迁移到 ws/tmq。 3. STMT 和 Schemaless：af 迁移到 ws/unified。

    C/C++、Python、Rust 的原生连接继续支持，不受影响，但仍然建议使用 WebSocket 连接方式以获得更好的兼容性。

    REST 连接（Java、Python、Go）​

    请迁移到 WebSocket 连接方式：

    • Java: 将 jdbc:TAOS-RS:// 改为 jdbc:TAOS-WS://，其余配置请仔细阅读 JDBC 驱动。

    • Python:

      taosrest 迁移到 taos-ws-py 快速指南
      步骤 1：连接方式替换​

      taosrest 通常使用 url + user/password 参数连接：

      from taosrest import connect

      conn = connect(url="http://localhost:6041", user="root", password="taosdata")

      迁移为 taosws 的 WebSocket DSN：

      import taosws

      conn = taosws.connect("ws://root:taosdata@localhost:6041")
      步骤 2：执行 SQL 方式替换​

      taosrest 常见写法是通过 cursor 执行：

      cursor = conn.cursor()
      cursor.execute("CREATE DATABASE IF NOT EXISTS demo")
      cursor.execute("USE demo")
      cursor.execute("CREATE TABLE IF NOT EXISTS t (ts TIMESTAMP, v INT)")
      cursor.execute("INSERT INTO t VALUES (now, 1)")

      迁移到 taosws 时，可继续使用 cursor 风格，做到最小改动迁移：

      cursor = conn.cursor()
      cursor.execute("CREATE DATABASE IF NOT EXISTS demo")
      cursor.execute("USE demo")
      cursor.execute("CREATE TABLE IF NOT EXISTS t (ts TIMESTAMP, v INT)")
      cursor.execute("INSERT INTO t VALUES (now, 1)")
      步骤 3：查询结果读取方式替换​

      taosrest 常见写法：

      cursor.execute("SELECT * FROM demo.t")
      rows = cursor.fetchall()
      for row in rows:
          print(row)

      taosws 读取查询结果时，也可保持 cursor 风格：

      cursor = conn.cursor()
      cursor.execute("SELECT * FROM demo.t")
      rows = cursor.fetchall()
      for row in rows:
        print(row)

    • Go: database/sql 代码无需修改，主要替换驱动名称和 DSN 协议头：从 taosRestful + http(6041) 到 taosWS + ws(6041)。

  3. REST API：不使用连接器，通过 HTTP 客户端直接调用 taosAdapter 组件提供的 REST API 建立与 taosd 的连接，这种连接方式下文中简称"REST API"。

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

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

关键不同点在于：

  1. 推荐使用 WebSocket 连接：

    • 除 C/C++ 和 ODBC 连接器外，用户无需安装客户端驱动程序 taosc
    • 提供兼容性保证，无需保证客户端和服务端版本一致
    • 连接云服务实例必须使用 WebSocket 连接

  2. 原生连接（即将废弃）：

    • 使用 Go、C#、Java 连接器的用户需注意，原生连接将于 2027-01-01 下线，请提前迁移
    • 需要保证客户端驱动程序 taosc 和服务端版本保持一致
    • C/C++、Python、Rust 的原生连接继续支持

  3. REST API：

    • 仅提供执行 SQL 功能，不支持参数绑定和数据订阅

支持的平台​

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

对照矩阵如下：

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

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

版本支持​

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

TDengine TSDB 版本JavaPythonGoC#Node.jsRustC/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.03.1.0当前版本与 TDengine TSDB 相同版本
2.4.0.14 及以上2.0.38当前版本develop 分支1.0.2 - 1.0.62.0.10 - 2.0.12当前版本与 TDengine TSDB 相同版本
2.4.0.4 - 2.4.0.132.0.37当前版本develop 分支1.0.2 - 1.0.62.0.10 - 2.0.12当前版本与 TDengine TSDB 相同版本
2.2.x.x2.0.36当前版本master 分支n/a2.0.7 - 2.0.9当前版本与 TDengine TSDB 相同版本
2.0.x.x2.0.34当前版本master 分支n/a2.0.1 - 2.0.6当前版本与 TDengine TSDB 相同版本

功能特性​

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

WebSocket/原生 连接​

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

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

信息

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

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

REST API​

支持 执行 SQL

安装客户端驱动​

信息

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

安装步骤​

  1. 下载客户端安装包

    1. 解压缩软件包

      将软件包放置在当前用户可读写的任意目录下，然后执行下面的命令

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

    2. 执行安装脚本

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

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

    3. 配置 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 服务。

    安装验证​

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

    在 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>
    SOC 2 Certified
    ISO 27001 Certified
    ISO 27017 Certified
    TDengine 专为物联网IoT平台、工业大数据平台设计。其中，TDengine TSDB 是一款高性能、分布式的时序数据库（Time Series Database），同时它还带有内建的缓存、流式计算、数据订阅等系统功能；TDengine IDMP 是一款AI原生工业数据管理平台，它通过树状层次结构建立数据目录，对数据进行标准化、情景化，并通过 AI 提供实时分析、可视化、事件管理与报警等功能。
    产品
    TDengine TSDB
    TDengine IDMP
    TDengine Cloud
    学习
    TSDB 文档
    IDMP 文档
    博客
    资源
    公司
    关于我们
    技术支持
    新闻动态
    安全性
    联系我们
    招贤纳士
    服务条款
    隐私
    场景
    物联网
    工业互联网
    车联网
    IT 运维
    电力能源
    金融
    TDengine AI Chat
    点击使用 AI 问答
    TDengine 的智能助手
    TDengine Database
    加小 T 为好友
    即可加入物联网大数据技术前沿群
    点击填写表单
    获得解决方案专家帮助
    © 2017-2026 涛思数据
    京公网安备 11010502047618号
    新版时序数据库 TDengine Database v3.0