TDengine Rust 连接器入门指南

本文档帮助你快速上手 TDengine 官方 Rust 连接器 taos。从零开始，只需几分钟即可完成连接、建库建表、写入数据和查询数据。

前置条件

在开始之前，请确保：

1. TDengine 服务已启动：可以是本地安装的 TDengine，也可以是远程服务器。
2. Rust 环境就绪 ：需要 Rust 1.70 及以上版本。运行 rustc --version 检查版本。
3. （仅原生连接）客户端驱动已安装 ：
   • Linux：安装后 libtaos.so 位于 /usr/lib/
   • macOS：安装后 libtaos.dylib 位于 /usr/local/lib/
   • Windows：安装后 taos.dll 位于 C:\Windows\System32\

:::tip

如果你使用 WebSocket 连接 ，无需安装客户端驱动，跨平台更方便。

:::

第一步：创建项目

打开终端，运行：

cargo new tdengine_demo
cd tdengine_demo

第二步：添加依赖

编辑 Cargo.toml，在 [dependencies] 下添加：

[dependencies]
taos = "*"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
anyhow = "1"

依赖	说明
taos	TDengine 官方 Rust 连接器
tokio	异步运行时
anyhow	简化错误处理

第三步：选择连接方式

TDengine Rust 连接器支持两种连接方式，通过 DSN（连接字符串）来区分：

WebSocket 连接：

ws://localhost:6041

• 默认端口：6041
• 无需安装客户端驱动
• 支持所有平台

Natvie 连接：

taos://localhost:6030

• 默认端口：6030
• 需要安装客户端驱动
• 性能更高

DSN 完整格式：

<driver>://[<user>:<password>@]<host>:<port>[/<database>]

示例：ws://root:taosdata@192.168.1.100:6041/test

第四步：编写代码

将 src/main.rs 替换为以下内容：

use taos::*;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // ============================================
    // 1. 建立连接
    // ============================================
    // WebSocket 连接使用 "ws://localhost:6041"
    // 原生连接使用 "taos://localhost:6030"
    let dsn = "ws://localhost:6041";
    
    let taos = TaosBuilder::from_dsn(dsn)?.build().await?;
    println!("✅ 连接成功：{}", dsn);

    // ============================================
    // 2. 创建数据库
    // ============================================
    taos.exec("CREATE DATABASE IF NOT EXISTS demo").await?;
    taos.exec("USE demo").await?;
    println!("✅ 数据库 demo 已创建");

    // ============================================
    // 3. 创建超级表
    // ============================================
    // 超级表：定义数据结构和标签
    // - ts: 时间戳（必须）
    // - temperature, humidity: 采集的指标
    // - location: 标签，用于区分不同设备
    taos.exec(
        "CREATE STABLE IF NOT EXISTS sensors (
            ts TIMESTAMP,
            temperature FLOAT,
            humidity INT
        ) TAGS (
            location VARCHAR(64)
        )"
    ).await?;
    println!("✅ 超级表 sensors 已创建");

    // ============================================
    // 4. 写入数据
    // ============================================
    // 使用超级表自动创建子表并插入数据
    let affected = taos.exec(
        "INSERT INTO 
            d001 USING sensors TAGS('北京') VALUES (NOW, 25.5, 60) (NOW+1s, 25.8, 58)
            d002 USING sensors TAGS('上海') VALUES (NOW, 27.3, 70) (NOW+1s, 27.1, 72)"
    ).await?;
    println!("✅ 写入 {} 行数据", affected);

    // ============================================
    // 5. 查询数据
    // ============================================
    let mut result = taos.query(
        "SELECT ts, temperature, humidity, location FROM sensors ORDER BY ts DESC LIMIT 10"
    ).await?;

    // 打印列名
    println!("\n📊 查询结果：");
    println!("{:<25} {:>12} {:>10} {:>10}", "时间", "温度", "湿度", "位置");
    println!("{}", "-".repeat(60));

    // 遍历结果
    let mut rows = result.rows();
    while let Some(row) = rows.try_next().await? {
        let mut ts = String::new();
        let mut temp = String::new();
        let mut humi = String::new();
        let mut loc = String::new();
        
        for (_col, (name, value)) in row.enumerate() {
            match name {
                "ts" => ts = format!("{}", value),
                "temperature" => temp = format!("{}", value),
                "humidity" => humi = format!("{}", value),
                "location" => loc = format!("{}", value),
                _ => {}
            }
        }
        println!("{:<25} {:>12} {:>10} {:>10}", ts, temp, humi, loc);
    }

    // ============================================
    // 6. 清理（可选）
    // ============================================
    // taos.exec("DROP DATABASE demo").await?;

    Ok(())
}

第五步：运行程序

cargo run

预期输出：

✅ 连接成功：ws://localhost:6041
✅ 数据库 demo 已创建
✅ 超级表 sensors 已创建
✅ 写入 4 行数据

📊 查询结果：
时间                            温度       湿度       位置
------------------------------------------------------------
2026-01-08 10:00:01.000        27.1         72         上海
2026-01-08 10:00:01.000        25.8         58         北京
2026-01-08 10:00:00.000        27.3         70         上海
2026-01-08 10:00:00.000        25.5         60         北京

核心概念速查

TDengine 数据模型

数据库 (Database)
  └── 超级表 (Super Table) ← 定义表结构和标签
        ├── 子表1 (Sub Table) ← 具体设备，继承超级表结构
        ├── 子表2
        └── ...

常用 API

方法	用途	示例
TaosBuilder::from_dsn()	创建连接构建器	TaosBuilder::from_dsn("ws://...")
.build().await	建立连接	builder.build().await?
.exec()	执行写入/DDL	taos.exec("INSERT...").await?
.query()	执行查询	taos.query("SELECT...").await?
.exec_many()	批量执行	taos.exec_many(["SQL1", "SQL2"]).await?

数据类型对照

TDengine 类型	Rust 类型
TIMESTAMP	Timestamp
INT	i32
BIGINT	i64
FLOAT	f32
DOUBLE	f64
BOOL	bool
VARCHAR/NCHAR	String
BINARY	Vec<u8>

常见问题

1. 连接失败

原生连接报错 "找不到动态库"

• 确认已安装 TDengine 客户端
• 检查动态库路径是否正确

连接超时

• 检查 TDengine 服务是否启动
• 确认端口正确：原生 6030，WebSocket 6041
• 检查防火墙设置

2. 查询返回空

• 确认数据库和表名正确
• 检查是否已写入数据
• 使用 taos CLI 工具验证数据

3. 如何开启调试日志

在运行前设置环境变量：

RUST_LOG=taos=debug cargo run

资料

• 📖 完整 API 文档
• 💡 示例代码

---

关于 TDengine

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