TDengine Python 连接器入门指南

TDengine Python 连接器入门指南

本文面向 TDengine 初学者，目标是让你在 5～10 分钟内完成：安装连接器 → 建立连接 → 建库建表 → 写入 → 查询，并掌握连接器的基本使用方式与常见问题排查。

说明：TDengine 官方 Python 连接器为 taospy。其中：

• 原生连接对应 taospy 包的 taos 模块。
• WebSocket 连接对应可选包 taos-ws-py，使用 taosws 模块（推荐）。

1. 选择连接方式

taospy 提供两种连接方式，建议优先使用 WebSocket 连接：

• WebSocket 连接（推荐） ：通过 taosAdapter 的 WebSocket 接口访问 TDengine，依赖更轻且在并发/IO 密集场景更友好。
• 原生连接（Native） ：Python 进程需加载 TDengine 客户端驱动（libtaos.so/taos.dll），本地依赖更多。

连接方式的详细介绍见：

• 连接方式

2. 环境准备

在运行示例前，请确认：

• TDengine TSDB 服务端已启动，并且你的程序能访问到它。
• 若使用 WebSocket 连接 ：确保 taosAdapter 的 WebSocket 服务可用（示例默认 localhost:6041）。
• 若使用 原生连接：确保已安装 TDengine TSDB 客户端驱动，且 Python 能正确加载。

3. 安装连接器

# 原生连接
pip3 install taospy

# WebSocket 连接（推荐，可选装）
pip3 install taos-ws-py

4. 第一个程序：建库建表、写入、查询

下面提供两份"最小可运行"示例，你可以任选其一。

4.1 WebSocket（推荐）

保存为 quickstart_ws.py 并运行。

import taosws


def main() -> None:
    # WebSocket 连接依赖 taosAdapter 的 WebSocket 服务。
    conn = None
    host = "localhost"
    port = 6041

    try:
        conn = taosws.connect(
            user="root",
            password="taosdata",
            host=host,
            port=port,
        )

        conn.execute("CREATE DATABASE IF NOT EXISTS demo")
        conn.execute("USE demo")
        conn.execute(
            "CREATE STABLE IF NOT EXISTS meters (ts TIMESTAMP, current FLOAT, voltage INT) TAGS (location BINARY(24))"
        )
        conn.execute("CREATE TABLE IF NOT EXISTS d0 USING meters TAGS('beijing')")
        conn.execute("INSERT INTO d0 VALUES (NOW, 10.2, 220) (NOW + 1s, 10.3, 221)")

        result = conn.query("SELECT * FROM meters LIMIT 5")
        for row in result:
            print(row)

    finally:
        if conn is not None:
            conn.close()


if __name__ == "__main__":
    main()

运行：

python3 quickstart_ws.py

4.2 原生连接（Native）

保存为 quickstart_native.py 并运行。

import taos


def main() -> None:
    # 原生连接依赖 TDengine 客户端驱动（libtaos.so/taos.dll）。
    conn = None
    host = "localhost"
    port = 6030

    try:
        conn = taos.connect(
            user="root",
            password="taosdata",
            host=host,
            port=port,
        )

        conn.execute("CREATE DATABASE IF NOT EXISTS demo")
        conn.execute("USE demo")
        conn.execute(
            "CREATE STABLE IF NOT EXISTS meters (ts TIMESTAMP, current FLOAT, voltage INT) TAGS (location BINARY(24))"
        )
        conn.execute("CREATE TABLE IF NOT EXISTS d0 USING meters TAGS('beijing')")
        conn.execute("INSERT INTO d0 VALUES (NOW, 10.2, 220) (NOW + 1s, 10.3, 221)")

        result = conn.query("SELECT * FROM meters LIMIT 5")
        for row in result.fetch_all():
            print(row)

    finally:
        if conn is not None:
            conn.close()


if __name__ == "__main__":
    main()

运行：

python3 quickstart_native.py

5. 连接器基本用法速记

• 建立连接：
  • WebSocket：taosws.connect(user=..., password=..., host=..., port=...)
  • 原生：taos.connect(user=..., password=..., host=..., port=...)
• 执行 SQL：conn.execute(sql)
• 查询：conn.query(sql)
  • WebSocket 返回结果可直接迭代 for row in result:
  • 原生示例里通过 result.fetch_all() 获取全部记录

6. 异常与排查（最常见）

TDengine Python 连接器的数据库操作如果出现异常，会直接抛出给应用层处理。常见排查路径：

• ConnectionError（连接失败）：检查服务端是否启动、账号密码是否正确、host/port 是否可达；WebSocket 还需要确认 taosAdapter 是否可用。
• InterfaceError（原生接口/驱动不兼容）：通常是 taosc 或客户端驱动版本过低或不匹配，升级 TDengine 客户端组件。
• ProgrammingError / QueryError（SQL/查询错误）：检查 SQL 是否正确、库表是否存在、数据类型是否匹配；结合错误码定位。

参考：

• 错误码

7. 下一步（进阶能力入口）

当你能跑通上面的"建库建表、写入、查询"后，建议按需求继续：

• 高效批量写入：了解参数绑定（stmt / stmt2）。
• 无模式写入：了解 schemaless 写入。
• 消息订阅：了解 TMQ（创建 Consumer、subscribe、poll、commit）。
• 连接参数与 URL 规范：了解 WebSocket DSN（ws://...）与超时/重试/时区等参数。

---

关于 TDengine

TDengine 专为物联网IoT平台、工业大数据平台设计。其中，TDengine TSDB 是一款高性能、分布式的时序数据库（Time Series Database），同时它还带有内建的缓存、流式计算、数据订阅等系统功能；TDengine IDMP 是一款AI原生工业数据管理平台，它通过树状层次结构建立数据目录，对数据进行标准化、情景化，并通过 AI 提供实时分析、可视化、事件管理与报警等功能。