TDengine Rust 连接器入门指南

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

前置条件

在开始之前，请确保：

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

:::tip

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

:::

第一步：创建项目

打开终端，运行：

bash 复制代码

cargo new tdengine_demo
cd tdengine_demo

第二步：添加依赖

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

toml 复制代码

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

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

第三步：选择连接方式

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

WebSocket 连接：

text 复制代码

ws://localhost:6041

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

Natvie 连接：

text 复制代码

taos://localhost:6030

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

DSN 完整格式：

text 复制代码

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

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

第四步：编写代码

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

rust 复制代码

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(())
}

第五步：运行程序

bash 复制代码

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. 如何开启调试日志

在运行前设置环境变量：

bash 复制代码

RUST_LOG=taos=debug cargo run

资料

📖 完整 API 文档
💡 示例代码

关于 TDengine

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