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. 安装连接器

# 原生连接pip3installtaospy# WebSocket 连接（推荐，可选装）pip3installtaos-ws-py

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

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

4.1 WebSocket（推荐）

保存为quickstart_ws.py并运行。

importtaoswsdefmain()->None:# WebSocket 连接依赖 taosAdapter 的 WebSocket 服务。conn=Nonehost="localhost"port=6041try: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")forrowinresult:print(row)finally:ifconnisnotNone:conn.close()if__name__=="__main__":main()

运行：

python3 quickstart_ws.py

4.2 原生连接（Native）

保存为quickstart_native.py并运行。

importtaosdefmain()->None:# 原生连接依赖 TDengine 客户端驱动（libtaos.so/taos.dll）。conn=Nonehost="localhost"port=6030try: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")forrowinresult.fetch_all():print(row)finally:ifconnisnotNone: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 提供实时分析、可视化、事件管理与报警等功能。