TDengine 连接指南：从客户端安装到多语言连接器接入的完整实战-迪斯科星球

TDengine 连接指南：从客户端安装到多语言连接器接入的完整实战

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine

TDengine 作为面向工业物联网（IIoT）场景的高性能时序数据库，为开发者提供了丰富的应用开发接口。本文以官方开发者指南中的《Connecting to TDengine》为核心，系统讲解 TDengine 的三种访问方式（WebSocket 连接、原生连接、REST API）、客户端驱动 taosc 与各语言连接器的安装步骤、连接参数详解、建立连接的代码示例以及连接池的使用方法，并结合本仓库中的真实源码与示例帮助读者快速落地第一个 TDengine 应用。

一、连接方式总览：三种访问 TDengine 的途径

TDengine 的官方连接器覆盖 C/C++、Java、Python、Go、Node.js、C#、Rust 等主流语言，社区开发者还贡献了 ADO.NET、Lua、PHP 等非官方连接器。这些连接器通过原生接口或WebSocket 接口接入 TDengine 集群；此外，用户还可以直接调用 taosAdapter 提供的 REST API 完成数据写入与查询。官方文档将连接方式归纳为以下三种（详见连接方式说明与上图架构）：

WebSocket 连接：通过连接器与 taosAdapter 组件提供的 WebSocket API 建立与 taosd 的连接。该方式提供兼容性保证——所有支持 WebSocket 连接的连接器均兼容 TDengine 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 连接。
原生连接：通过客户端驱动 taosc 与服务器程序 taosd 直接建立连接。注意：Go、C#、Java 的原生连接已废弃，将于 2027-01-01 停止支持；C/C++、Python、Rust 的原生连接仍会继续支持。
REST API：应用使用 HTTP 客户端直接调用 taosAdapter 提供的 REST API 访问 taosd，无需安装任何连接器。但 REST 方式仅提供执行 SQL 的功能，不支持参数绑定与数据订阅；且 Java、Python、Go 的 REST 连接同样已废弃，将于 2027-01-01 停止支持，官方建议迁移至 WebSocket 连接。

关于各语言连接方式的能力矩阵，可参见连接器特性总览。从官方架构图可以看出，无论采用哪种连接方式，客户端与服务端之间最终都经由 taosAdapter 或 taosd 完成协议适配与数据处理。

关于废弃与迁移：官方在连接废弃声明中给出了明确迁移路径，例如 Java 将jdbc:TAOS://改为jdbc:TAOS-WS://、端口由 6030 改为 6041；C# 将连接串中的protocol=Native改为protocol=WebSocket；Go 将驱动名与 DSN 协议头由taosSql+tcp(6030)改为taosWS+ws(6041)。因此，新项目应优先采用 WebSocket 连接。

二、安装客户端驱动 taosc

如果你选择原生连接，且应用与服务端不在一台机器上，需要先安装客户端驱动 taosc；否则可以跳过此步。为避免客户端驱动与服务端不兼容，请务必保持客户端与服务端版本一致（自 3.4.0.0 起企业版与社区版不完全兼容，混用会报 "Edition not compatible" 错误）。

2.1 安装步骤

Linux

下载客户端安装包；
解压：tar -xzvf tdengine-tsdb-enterprise-client-<VERSION>-linux-x64.tar.gz，解压后目录中包含install_client.sh（安装脚本）、package.tar.gz（驱动安装包）、driver（应用驱动）、examples（各语言示例程序）；
运行install_client.sh完成安装；
编辑taos.cfg（默认路径/etc/taos/taos.cfg），将firstEP改为 TDengine 服务器的 End Point，例如h1.tdengine.com:6030。

Windows：解压安装包后按安装向导执行，驱动taos.dll随包提供。

macOS：下载对应平台的客户端安装包，解压后运行安装脚本，同样需配置taos.cfg的firstEP。

关于taos.cfg的客户端相关配置，本仓库的 taos.cfg 模板给出了完整参考。对纯客户端场景而言，最关键的是以下两项：

firstEp：客户端或 CLI 启动时连接到的集群中第一个 dnode 的 End Point，格式为hostname:6030；若仅安装应用驱动且 TDengine 服务不在本机，只需配置firstEP，无需配置本机 FQDN；
secondEp：当firstEp不可用时的备选 dnode 地址。

注意事项：

若服务端启用 TLS，客户端需按需配置 WebSocket 相关 TLS 参数。例如wsTlsMode（0 为关闭 TLS，1 为启用但不校验证书，2 为启用并校验证书但不校验主机名，3 为启用并校验证书与主机名）、wsTlsCa（CA 证书文件路径或 PEM 格式证书内容）、wsTlsVersion（默认 TLSv1.3）等，这些参数同样定义于 taos.cfg 模板的 WebSocket 配置段；
为避免连接服务器时出现 "Unable to resolve FQDN" 错误，建议确保本机/etc/hosts已配置服务端正确的 FQDN 值，或 DNS 服务配置正确。

2.2 安装验证

安装并确认 TDengine 服务正常启动后，在 Linux/macOS shell 中直接执行taos，进入 TDengine CLI 接口：

$ taos taos> show databases; name | ================================= information_schema | performance_schema | db | Query OK, 3 rows in database (0.019154s) taos>

Windows 下则在 cmd 中进入C:\TDengine目录执行taos.exe，同样执行show databases;验证连通性。看到数据库列表即表示客户端驱动安装成功且能正常连接服务端。

三、安装各语言连接器

3.1 Java（taos-jdbcdriver）

使用 Maven 管理项目时，在pom.xml中添加如下依赖（仓库示例见 JDBCDemo）：

<dependency> <groupId>com.taosdata.jdbc</groupId> <artifactId>taos-jdbcdriver</artifactId> <version>3.8.3</version> </dependency>

3.2 Python（taospy / taos-ws-py）

预安装准备：

新版taospy需要 Python 3.6.2+，旧版taospy需要 Python 3.7+，taos-ws-py需要 Python 3.7+；
安装 pip；
若使用原生连接，还需先安装客户端驱动 taosc（客户端软件包包含动态链接库libtaos.so或taos.dll及 TDengine CLI）。

使用 pip 安装：

先卸载旧版本：

pip3 uninstall taos taospy pip3 uninstall taos taos-ws-py

安装taospy（原生连接）：

# 最新版本 pip3 install taospy # 指定版本 pip3 install taospy==2.8.9

安装taos-ws-py（WebSocket 连接）：

pip3 install taos-ws-py

同时安装两者：

pip3 install taospy[ws]

安装验证：原生连接需同时验证客户端驱动与 Python 连接器，在 Python 交互 Shell 中执行import taos成功即安装正确；WebSocket 连接只需验证import taosws。

3.3 Go（driver-go）

编辑go.mod添加依赖：

module goexample go 1.17 require github.com/taosdata/driver-go/v3 latest

注意：driver-go 使用 cgo 封装 taosc API，cgo 需要 GCC 编译 C 源码，请确保系统已安装 GCC。

3.4 Rust（taos）

编辑Cargo.toml：

[dependencies] taos = { version = "*"}

Rust 连接器通过不同 feature 区分连接方式，默认同时支持原生与 WebSocket 连接。若只需 WebSocket 连接，可只启用wsfeature：

taos = { version = "*", default-features = false, features = ["ws"] }

3.5 Node.js（@tdengine/websocket）

需要 Node.js 14 及以上版本；
安装命令：npm install @tdengine/websocket；
Node.js 目前仅支持 WebSocket 连接。

安装验证：创建验证目录（如~/tdengine-test），下载nodejsChecker.js源码（仓库示例见 docs/examples/node），依次执行：

npm init -y npm install @tdengine/websocket node nodejsChecker.js

命令行将输出 nodejsChecker.js 连接 TDengine 实例并执行简单插入、查询操作的结果。

3.6 C#（TDengine.Connector）

在项目配置文件（如csharp.csproj）中添加包引用：

<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <OutputType>Exe</OutputType> <TargetFramework>net6.0</TargetFramework> <ImplicitUsings>enable</ImplicitUsings> <Nullable>enable</Nullable> <StartupObject>TDengineExample.AsyncQueryExample</StartupObject> </PropertyGroup> <ItemGroup> <PackageReference Include="TDengine.Connector" Version="3.2.0" /> </ItemGroup> </Project>

也可通过 dotnet 命令添加：dotnet add package TDengine.Connector。示例代码基于 dotnet6.0，使用其他版本时可能需要相应调整。

3.7 C 连接器

如果已安装 TDengine 服务端软件或客户端驱动 taosc，则 C 连接器已随之安装，无需额外操作。C/C++ 应用必须依赖客户端驱动 taosc（taosc 本身包含 C 原生与 WebSocket 两种连接器）。

3.8 REST API

使用 REST API 访问 TDengine无需安装任何驱动或连接器，应用直接通过 HTTP 与 taosAdapter 建立连接即可，建议配合连接池管理连接。

四、连接参数详解

建立连接前，先了解各语言连接器使用的连接参数。以下内容均以默认配置（FQDN 为 localhost、serverPort 为 6030）为前提展开。

4.1 Java（JDBC URL 与 Properties）

TDengine 的 JDBC URL 格式为：

jdbc:[TAOS|TAOS-WS]://[host_name]:[port]/[database_name]?[user={user}&password={password}&charset={charset}&cfgdir={config_dir}&locale={locale}&timezone={timezone}&batchfetch={batchfetch}&varcharAsString=true]

其中jdbc:TAOS://走原生连接（端口 6030），jdbc:TAOS-WS://走 WebSocket 连接（端口 6041）。URL 与 Properties 参数的详细说明见 Java 连接器 URL 规范。

4.2 Python（connect() 参数）

Python 连接器使用connect()方法建立连接：

url：taosAdapter WebSocket 服务的 URL，默认为localhost:6041；
user：TDengine 用户名，默认root；
password：TDengine 用户密码，默认taosdata；
timeout：HTTP 请求超时时间（秒），默认socket._GLOBAL_DEFAULT_TIMEOUT，一般无需配置。

详细参数说明见 Python 连接器 URL 规范。

4.3 Go（DSN）

Go 连接器的数据源名称（DSN）采用通用格式（类似 PEAR DB，但无类型前缀，方括号内为可选）：

[username[:password]@][protocol[(address)]]/[dbname][?param1=value1&...&paramN=valueN]

完整 DSN 格式：

username:password@protocol(address)/dbname?param=value

使用 IPv6 地址（v3.7.1+ 支持）时地址需加方括号，例如：

root:taosdata@ws([::1]:6041)/testdb

自v3.8.0起，Go 连接器通过ws/unified统一 WebSocket 访问，taosWS仍作为标准接口可用。注意：多端点故障转移（failover）由taosWS与ws/unified共同支持，例如root:taosdata@ws(localhost:6041,localhost:6042)/testdb；其中taosWS为标准接口且支持官方连接池，ws/unified为统一接口但不支持官方连接池。

支持的 DSN 参数：

原生连接：

cfg：指定 taos.cfg 所在目录；
cgoThread：可并发执行的 cgo 操作数，默认等于系统核数；
cgoAsyncHandlerPoolSize：异步函数处理器大小，默认 10000；
timezone：连接使用的时区，SQL 解析与查询结果都会按此时区转换，仅支持 IANA 时区格式且特殊字符需编码，例如上海时区写作timezone=Asia%2FShanghai。

WebSocket 连接：

enableCompression：是否发送压缩数据，默认false（不压缩）；
readTimeout：读取数据超时，默认5m；
writeTimeout：写入数据超时，默认10s；
timezone：同上；
token：云服务使用的 token；
bearerToken：认证用 token；
totpCode：双因素认证使用的 TOTP 码；
skipVerify：wss 连接是否跳过 TLS 证书校验，默认false（v3.8.1 起支持，生产环境不建议开启）；
autoReconnect：是否启用自动重连，默认false（v3.8.0 起支持）；
chanLength：消息通道长度，默认 1（v3.8.0 起支持）；
reconnectIntervalMs：重连间隔（毫秒），默认 2000（v3.8.0 起支持）；
reconnectRetryCount：重连重试次数，默认 3（v3.8.0 起支持）。

注意：重连成功后，连接上的当前 DB 会丢失，请在 DSN 中指定 DB，并避免后续切换数据库。

4.4 Rust（DSN）

Rust 连接器使用 DSN 创建连接，基本结构为：

<driver>[+<protocol>]://[[<username>:<password>@]<host>:<port>][/<database>][?<p1>=<v1>[&<p2>=<v2>]]

DSN 与连接特性的详细说明见 Rust 连接器连接特性。

4.5 Node.js（DSN）

Node.js 连接器使用 DSN 创建连接，基本结构为：

[+<protocol>]://[[<username>:<password>@]<host>:<port>][/<database>][?<p1>=<v1>[&<p2>=<v2>]]

protocol：使用 websocket 协议建立连接，例如ws://localhost:6041；
username/password：数据库用户名与密码；
host/port：host_name支持合法域名或 IP 地址，@tdengine/websocket同时支持 IPv4 与 IPv6，IPv6 地址必须使用方括号（如[::1]或[2001:db8:1234:5678::1]）以避免端口解析冲突；
database：数据库名；
params：其他参数，例如 token。

完整 DSN 示例：

// IPV4: ws://root:taosdata@localhost:6041 // IPV6: ws://root:taosdata@[::1]:6041

4.6 C#（ConnectionStringBuilder）

C# 连接器通过 ConnectionStringBuilder 以键值对方式设置连接参数，键值间以分号;分隔。单地址示例：

"protocol=WebSocket;host=127.0.0.1;port=6041;useSSL=false"

自TDengine.Connector3.2.0 起，WebSocket 连接支持通过逗号分隔的host列表实现故障转移，初始连接会自动尝试配置的各地址，断线后的重连故障转移需设置autoReconnect=true：

"protocol=WebSocket;host=adapter-a:6041,adapter-b:6041;username=root;password=taosdata;autoReconnect=true;reconnectRetryCount=3;reconnectIntervalMs=2000"

支持的参数：

公共参数：
- host：原生连接仅支持单地址；WebSocket 在 3.2.0 及以后支持单地址或逗号分隔的地址列表。单地址格式包括host、host:port、裸 IPv62001:db8::1、[2001:db8::1]、[2001:db8::1]:6041。多地址列表中 IPv6 项必须加方括号，例如host=[::1]:6041,[::1]:6042；
- port：共享回退端口，仅应用于未显式指定端口的地址。WebSocket 下若地址与port均未指定端口，默认6041，useSSL=true时默认443；原生连接通常使用6030；
- username/password：连接用户名与密码；
- protocol：连接协议，支持Native与WebSocket，默认Native；
- db：要连接的数据库；
- timezone：解析结果集中时间值使用的时区，默认本机时区；
- connectionTimezone：连接级时区设置，3.1.8 起支持，需要 .NET 6+ 且为 IANA 时区格式，不能与timezone同时使用；
- bearerToken：TDengine TSDB 认证 token，3.1.10 起支持。
WebSocket 专用参数：
- connTimeout：连接超时，默认 1 分钟；
- readTimeout：读超时，默认 5 分钟；
- writeTimeout：发送超时，默认 10 秒；
- token：连接 TDengine 云服务的 token；
- useSSL：是否使用 SSL/TLS WebSocket 连接，默认false；
- enableCompression：是否启用 WebSocket 压缩，默认false；
- autoReconnect：是否自动重连，默认false。3.2.0 及以后配置多个 WebSocket 地址时，该参数控制当前连接不可用后的运行时故障转移；
- reconnectRetryCount：重连轮数，默认 3；
- reconnectIntervalMs：重连轮间隔（毫秒），默认 2000。

注意：WebSocket 故障转移自 3.2.0 起可用，连接器采用**最少连接数（Least Connections）**算法选择地址，优先选择活动连接数最少的节点。原生连接不支持多地址故障转移，若protocol=Native且host包含多个地址，打开连接会抛出ArgumentException。

4.7 C（taos_connect() 参数）

C/C++ 连接器使用taos_connect()函数与 TDengine 数据库建立连接：

host：数据库服务器的主机名或 IP 地址，本地数据库可用"localhost"；
user：数据库登录用户名；
passwd：用户名对应的登录密码；
db：连接时使用的默认数据库名，不指定时传NULL或空字符串；
port：数据库服务器监听的端口号，原生连接默认6030，WebSocket 连接默认6041。

WebSocket 连接需先调用taos_options(TSDB_OPTION_DRIVER, "websocket")设置驱动类型，再调用taos_connect()建立连接。原生连接还提供taos_connect_auth()函数，使用 MD5 加密密码建立连接，功能与taos_connect()相同，区别在于密码处理方式——taos_connect_auth()需要密码的 MD5 加密字符串。

4.8 REST API

通过 REST API 访问时，应用直接与 taosAdapter 建立 HTTP 连接，建议使用连接池管理连接。具体请求参数参见 REST API HTTP 请求格式。

五、建立 WebSocket 连接（推荐）

WebSocket 连接各语言示例的整体流程主要包含"建立数据库连接"与"异常处理"两个环节。完整可运行示例均已收录在本仓库 docs/examples 目录下。

5.1 Java

参考仓库示例 WSConnectExample.java：

public static void main(String[] args) throws Exception { // 如需连接指定数据库 "dbName"，可使用： // String jdbcUrl = "jdbc:TAOS-WS://localhost:6041/dbName?user=root&password=taosdata&varcharAsString=true"; String jdbcUrl = "jdbc:TAOS-WS://localhost:6041?user=root&password=taosdata&varcharAsString=true"; Properties connProps = new Properties(); connProps.setProperty(TSDBDriver.PROPERTY_KEY_ENABLE_AUTO_RECONNECT, "true"); connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8"); connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8"); try (Connection conn = DriverManager.getConnection(jdbcUrl, connProps)) { System.out.println("Connected to " + jdbcUrl + " successfully."); // 在这里执行 SQL } catch (Exception ex) { // 异常信息参见 JDBC 规范 System.out.printf("Failed to connect to %s, %sErrMessage: %s%n", jdbcUrl, ex instanceof SQLException ? "ErrCode: " + ((SQLException) ex).getErrorCode() + ", " : "", ex.getMessage()); throw ex; } }

5.2 Python

参考仓库示例 connect_websocket_examples.py：

import taosws def create_connection(): conn = None host = "localhost" port = 6041 try: conn = taosws.connect( user="root", password="taosdata", host=host, port=port, ) print(f"Connected to {host}:{port} successfully.") except Exception as err: print(f"Failed to connect to {host}:{port} , ErrMessage:{err}") raise err return conn

SQLAlchemy 场景下，可通过hosts参数配置多个服务器地址实现负载均衡与故障转移，多地址用英文逗号分隔，格式为hosts=<host1>:<port1>,<host2>:<port2>,...。仓库示例 sqlalchemy_demo.py 展示了完整用法：

import taosws from sqlalchemy import create_engine # 使用 WebSocket 连接创建 SQLAlchemy engine # 若使用原生连接，将 `taosws` 换成 `taos` engine = create_engine(url="taosws://root:taosdata@?hosts=localhost:6041,127.0.0.1:6041&timezone=Asia/Shanghai", pool_size=10, max_overflow=20)

5.3 Go

taosWS标准接口示例（参考 docs/examples/go/connect/wsexample/main.go）：

package main import ( "database/sql" "fmt" "log" _ "github.com/taosdata/driver-go/v3/taosWS" ) func main() { // 如需连接指定数据库 "dbName"，可使用： // var taosDSN = "root:taosdata@ws(localhost:6041)/dbName" var taosDSN = "root:taosdata@ws(localhost:6041)/" taos, err := sql.Open("taosWS", taosDSN) if err != nil { log.Fatalln("Failed to connect to " + taosDSN + "; ErrMessage: " + err.Error()) } fmt.Println("Connected to " + taosDSN + " successfully.") defer taos.Close() }

自v3.8.0起，也可通过ws/unified统一接口创建连接（参考 docs/examples/go/connect/unified/main.go）：

var taosDSN = "root:taosdata@ws(localhost:6041)/" taos, err := unified.Open(taosDSN) if err != nil { log.Fatalln("Failed to connect to " + taosDSN + "; ErrMessage: " + err.Error()) } fmt.Println("Connected to " + taosDSN + " successfully.") defer taos.Close()

5.4 Rust

参考仓库示例 connect.rs：

use taos::*; #[tokio::main] async fn main() -> anyhow::Result<()> { let dsn = "ws://localhost:6041"; match TaosBuilder::from_dsn(dsn)?.build().await { Ok(_taos) => { println!("Connected to {} successfully.", dsn); Ok(()) } Err(err) => { eprintln!("Failed to connect to {}, ErrMessage: {}", dsn, err); return Err(err.into()); } } }

5.5 Node.js

参考仓库示例 sql_example.js：

const taos = require("@tdengine/websocket"); let dsn = 'ws://localhost:6041'; async function createConnect() { try { let conf = new taos.WSConfig(dsn); conf.setUser('root'); conf.setPwd('taosdata'); conf.setDb('power'); conn = await taos.sqlConnect(conf); console.log("Connected to " + dsn + " successfully."); return conn; } catch (err) { console.log("Failed to connect to " + dsn + ", ErrCode: " + err.code + ", ErrMessage: " + err.message); throw err; } }

5.6 C#

参考仓库示例 Program.cs：

using System; using TDengine.Driver; using TDengine.Driver.Client; static void Main(string[] args) { var connectionString = "protocol=WebSocket;host=localhost;port=6041;useSSL=false;username=root;password=taosdata"; try { var builder = new ConnectionStringBuilder(connectionString); // 使用 using 块打开连接，会自动关闭连接 using (var client = DbDriver.Open(builder)) { Console.WriteLine("Connected to " + connectionString + " successfully."); } } catch (TDengineError e) { Console.WriteLine("Failed to connect to " + connectionString + "; ErrCode:" + e.Code + "; ErrMessage: " + e.Error); throw; } }

自TDengine.Connector3.2.0 起，可通过逗号分隔的host列表启用 WebSocket 故障转移。IPv6 多地址列表中每项必须加方括号，例如host=[::1]:6041,[2001:db8::2]:6041：

using var client = DbDriver.Open(new ConnectionStringBuilder( "protocol=WebSocket;" + "host=adapter-a:6041,adapter-b:6041;" + "username=root;" + "password=taosdata;" + "autoReconnect=true;" + "reconnectRetryCount=3;" + "reconnectIntervalMs=2000;"));

5.7 C

C 语言的 WebSocket 连接需先设置驱动类型。仓库示例 connect_example.c 展示了taos_options_connection(TSDB_OPTION_CONNECTION_USER_IP, ...)等连接级选项的设置方法，以及taos_query(taos, "show connections")的连接验证方式；完整的taos_connect()参数说明见本文 4.7 节。

六、原生连接（C/C++、Python、Rust 继续支持）

废弃声明：Go、C#、Java 的原生连接已废弃，将于2027-01-01停止支持，请提前迁移至 WebSocket 连接（迁移方式见本文第一节）。C/C++、Python、Rust 的原生连接将继续支持，但官方仍建议优先使用 WebSocket 以获得更好的兼容性。

原生连接的代码示例同样遵循"建立连接 + 异常处理"的模式，Node.js 不支持原生连接。

6.1 C（原生连接核心示例）

C 语言原生连接是理解 taosc 客户端驱动最直接的入口。仓库示例 connect_example.c（编译命令：gcc connect_example.c -o connect_example -ltaos）：

#include <stdio.h> #include <stdlib.h> #include <string.h> #include <taos.h> int main() { int32_t code = 0; const char *host = "localhost"; const char *user = "root"; const char *passwd = "taosdata"; const char *db = NULL; // 不连接默认库时设为 NULL 或 "" uint16_t port = 6030; // 0 表示使用默认端口 TAOS *taos = taos_connect(host, user, passwd, db, port); if (taos == NULL) { fprintf(stderr, "Failed to connect to %s:%hu, ErrCode: 0x%x, ErrMessage: %s.\n", host, port, taos_errno(NULL), taos_errstr(NULL)); taos_cleanup(); return -1; } // 连接建立后在此编写读写代码 taos_close(taos); taos_cleanup(); }

仓库还提供了基于OPTIONS结构体的进阶示例 taos_connect_with_example.c（编译命令：gcc -o taos_connect_with_example taos_connect_with_example.c -ltaos），通过taos_set_option逐一设置 ip、user、pass、port、charset、timezone、userIp、userApp、connectorInfo 等选项，再调用taos_connect_with(&opt)完成连接——当应用需要精确控制字符集、时区、客户端来源信息时，这种写法更为灵活。

6.2 其他语言原生连接

Java 原生连接示例见仓库 JNIConnectExample.java（JDBC URL 前缀为jdbc:TAOS://，端口 6030）；Python 原生连接使用taospy包；Go 原生连接示例见 docs/examples/go/connect/cgoexample（驱动名taosSql+tcp(6030)）；Rust 原生连接示例见 docs/examples/rust/nativeexample；C# 原生连接示例见 docs/examples/csharp/connect。

连接失败排查提示：若连接失败，大多数情况下是 FQDN 配置错误或防火墙设置问题，详细排查方法见 FAQ 中的 "Unable to establish connection" 一节。

七、使用连接池管理连接

部分连接器自带连接池，或可与现有连接池组件配合使用。使用连接池后，应用可以快速从池中获取可用连接，避免每次操作都创建和销毁连接的额外开销，既降低资源消耗又提升响应速度；同时连接池还支持连接管理（如限制最大连接数、检查连接有效性等），保证连接使用的高效与可靠。官方建议使用连接池管理连接。

7.1 Java（HikariCP / Druid）

HikariCP示例见仓库 HikariDemo.java。通过HikariDataSource.getConnection()获取连接后，使用完毕需调用close()方法——该操作实际上并非关闭连接，而是将其归还连接池。

Druid示例见仓库 DruidDemo.java。

7.2 Python（SQLAlchemy / DBUtils）

SQLAlchemy 连接池示例（推荐）见仓库 sqlalchemy_demo.py，其中create_engine(url="taosws://root:taosdata@?hosts=localhost:6041,127.0.0.1:6041&timezone=Asia/Shanghai", pool_size=10, max_overflow=20)同时展示了连接池大小配置与多地址负载均衡。DBUtils 连接池示例见仓库 dbutils_demo.py。

7.3 Go（database/sql 内置连接池）

使用sql.Open创建的连接本身已实现连接池，可通过 API 设置连接池参数，示例见 docs/examples/go/connect/connpool/main.go。

7.4 Rust（deadpool 异步连接池）

在复杂应用中建议启用连接池，taos连接池在异步模式下基于deadpool实现。

使用默认参数创建连接池：

let pool: Pool<TaosBuilder> = TaosBuilder::from_dsn("taos:///") .unwrap() .pool() .unwrap();

使用连接池构造函数自定义参数：

let pool: Pool<TaosBuilder> = Pool::builder(Manager::from_dsn("taos:///").unwrap().0) .max_size(88) // 最大连接数 .build() .unwrap();

从连接池获取连接对象：

let taos = pool.get().await?;

八、连接故障排查速查

连接遇到问题时，可按官方 FAQ（docs/en/16-faq/01-faq.md）建议的顺序排查：

检查网络环境：云服务器检查安全组是否放行 6030/6041 端口的 TCP/UDP 访问；本地虚拟机确认网络可 ping 通，尽量避免使用localhost作为主机名；NAT 网络环境确保服务器能向客户端回包；
核对版本：客户端与服务端版本号必须完全一致，TDengine TSDB-OSS 与 TDengine TSDB-Enterprise 不可混用；
检查服务状态：在服务器上执行systemctl status taosd，未运行时先启动；
确认 FQDN：客户端指定的服务器 FQDN 必须正确（服务器上可用hostname -f查看）；
验证 DNS 与 hosts：ping服务器 FQDN，无响应时检查网络、DNS 设置或客户端 hosts 文件；集群场景下客户端必须能 ping 通所有节点的 FQDN；
检查防火墙（Ubuntu 用ufw status，CentOS 用firewall-cmd --list-port），确保集群内所有主机 6030/6041 端口 TCP/UDP 互通；
检查动态库路径：Linux 下确认libtaos.so位于/usr/local/taos/driver且该目录在LD_LIBRARY_PATH中；macOS 下确认libtaos.dylib位于/usr/local/lib；Windows 下确认C:\TDengine\driver\taos.dll在系统库搜索目录中（建议放入C:\Windows\System32）；
使用工具验证端口连通性：Linux/macOS 可用nc -vuz {hostIP} {port}检查 UDP、nc {hostIP} {port}检查 TCP；Windows 可用Test-NetConnection -ComputerName {fqdn} -Port {port}。

此外，若应用需要更高级的安全能力（如 token 轮换、全链路鉴权），可进一步参考客户端与连接器安全与全链路鉴权两份安全指南。

总结

本文完整梳理了从客户端驱动 taosc 安装、各语言连接器接入，到连接参数详解、WebSocket/原生连接代码示例、连接池实践与故障排查的完整链路。核心要点可归纳为：新项目优先选择 WebSocket 连接（无需安装客户端驱动、有版本兼容性保证）；Go/C#/Java 的原生连接与 Java/Python/Go 的 REST 连接将于 2027-01-01 停止支持，需提前迁移；无论何种语言，生产环境都应通过连接池管理连接以提升资源利用效率。文中所引用的全部示例代码均可在本仓库 docs/examples 目录下找到可直接运行的完整版本。

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析