跳到主要内容

建立连接

TDengine TSDB 提供了丰富的应用程序开发接口。为便于用户快速开发应用，它支持多种编程语言的连接器，其中官方连接器包括 C/C++、Java、Python、Go、Node.js、C# 和 Rust；社区开发者也贡献了多个非官方连接器，例如 ADO.NET、Lua 和 PHP 连接器。这些连接器支持通过原生接口和 WebSocket 接口连接 TDengine TSDB 集群。另外，用户还可以直接调用 taosAdapter 提供的 REST API 接口访问 TDengine TSDB，进行数据写入和查询操作。

连接方式​

下图为 TDengine TSDB 客户端和服务端连接方式的架构图： TDengine TSDB connection architecture

如上面的架构图所示，我们有三种方式来访问 TDengine TSDB：

  1. WebSocket 连接：通过连接器使用 taosAdapter 组件提供的 WebSocket API 建立与 taosd 的连接，这种连接方式下文中简称"WebSocket 连接"。该方式提供兼容性保证——所有支持该连接方式的连接器均兼容 TDengine TSDB 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 连接。

  2. 原生连接：通过连接器使用客户端驱动程序 taosc 直接与服务端程序 taosd 建立连接，这种连接方式下文中简称"原生连接"。

    废弃通知

    以下连接方式将于 2027-01-01 下线

    原生连接（Java、C#、Go）​

    请迁移到 WebSocket 连接方式：

    • Java: 将 jdbc:TAOS:// 改为 jdbc:TAOS-WS://，端口从 6030 改为 6041，其余配置请仔细阅读 JDBC 驱动。

    • C#: 将连接字符串中的 protocol=Native 改为 protocol=WebSocket，端口从 6030 改为 6041。

    • Go:

      Go Native 迁移到 WebSocket 快速指南

      1. 执行 SQL：database/sql 代码无需修改，主要替换驱动名称和 DSN 协议头：从 taosSql + tcp(6030) 到：taosWS + ws(6041)。 2. 数据订阅：af/tmq 迁移到 ws/tmq。 3. STMT 和 Schemaless：af 迁移到 ws/unified。

    C/C++、Python、Rust 的原生连接继续支持，不受影响，但仍然建议使用 WebSocket 连接方式以获得更好的兼容性。

    REST 连接（Java、Python、Go）​

    请迁移到 WebSocket 连接方式：

    • Java: 将 jdbc:TAOS-RS:// 改为 jdbc:TAOS-WS://，其余配置请仔细阅读 JDBC 驱动。

    • Python:

      taosrest 迁移到 taos-ws-py 快速指南
      步骤 1：连接方式替换​

      taosrest 通常使用 url + user/password 参数连接：

      from taosrest import connect

      conn = connect(url="http://localhost:6041", user="root", password="taosdata")

      迁移为 taosws 的 WebSocket DSN：

      import taosws

      conn = taosws.connect("ws://root:taosdata@localhost:6041")
      步骤 2：执行 SQL 方式替换​

      taosrest 常见写法是通过 cursor 执行：

      cursor = conn.cursor()
      cursor.execute("CREATE DATABASE IF NOT EXISTS demo")
      cursor.execute("USE demo")
      cursor.execute("CREATE TABLE IF NOT EXISTS t (ts TIMESTAMP, v INT)")
      cursor.execute("INSERT INTO t VALUES (now, 1)")

      迁移到 taosws 时，可继续使用 cursor 风格，做到最小改动迁移：

      cursor = conn.cursor()
      cursor.execute("CREATE DATABASE IF NOT EXISTS demo")
      cursor.execute("USE demo")
      cursor.execute("CREATE TABLE IF NOT EXISTS t (ts TIMESTAMP, v INT)")
      cursor.execute("INSERT INTO t VALUES (now, 1)")
      步骤 3：查询结果读取方式替换​

      taosrest 常见写法：

      cursor.execute("SELECT * FROM demo.t")
      rows = cursor.fetchall()
      for row in rows:
          print(row)

      taosws 读取查询结果时，也可保持 cursor 风格：

      cursor = conn.cursor()
      cursor.execute("SELECT * FROM demo.t")
      rows = cursor.fetchall()
      for row in rows:
        print(row)

    • Go: database/sql 代码无需修改，主要替换驱动名称和 DSN 协议头：从 taosRestful + http(6041) 到 taosWS + ws(6041)。

  3. REST API：不使用连接器，通过 HTTP 客户端直接调用 taosAdapter 组件提供的 REST API 建立与 taosd 的连接，这种连接方式下文中简称"REST API"。

备注：客户端驱动程序 taosc 包含了 C 原生和 WebSocket 连接器，使用 C/C++ 语言开发的应用都需要依赖客户端驱动程序 taosc。

对于 WebSocket 连接和原生连接，连接器都提供了相同或相似的 API 操作数据库，只是初始化连接的方式稍有不同，用户在使用上不会感到什么差别。 各种连接方式和各语言连接器支持情况请参考 连接器功能特性。

关键不同点在于：

  1. 推荐使用 WebSocket 连接：

    • 除 C/C++ 和 ODBC 连接器外，用户无需安装客户端驱动程序 taosc
    • 提供兼容性保证，无需保证客户端和服务端版本一致
    • 连接云服务实例必须使用 WebSocket 连接

  2. 原生连接（即将废弃）：

    • 使用 Go、C#、Java 连接器的用户需注意，原生连接将于 2027-01-01 下线，请提前迁移
    • 需要保证客户端驱动程序 taosc 和服务端版本保持一致
    • C/C++、Python、Rust 的原生连接继续支持

  3. REST API：

    • 仅提供执行 SQL 功能，不支持参数绑定和数据订阅

安装客户端驱动 taosc​

如果选择原生连接，而且应用程序不在 TDengine TSDB 同一台服务器上运行，你需要先安装客户端驱动，否则可以跳过此一步。为避免客户端驱动和服务端不兼容，请使用一致的版本。

推荐使用 WebSocket 连接，无需安装客户端驱动。

安装步骤​

  1. 下载客户端安装包

    1. 解压缩软件包

      将软件包放置在当前用户可读写的任意目录下，然后执行下面的命令

      tar -xzvf tdengine-tsdb-enterprise-client-{{VERSION}}-linux-x64.tar.gz

    2. 执行安装脚本

      解压软件包之后，会在解压目录下看到以下文件 (目录)：

      • install_client.sh：安装脚本，用于应用驱动程序
      • package.tar.gz：应用驱动安装包
      • driver：TDengine 应用驱动 driver
      • examples: 各种编程语言的示例程序 (c/C#/go/JDBC/MATLAB/python/R) 运行 install_client.sh 进行安装。

    3. 配置 taos.cfg

      编辑 taos.cfg 文件（默认路径/etc/taos/taos.cfg），将 firstEP 修改为 TDengine 服务器的 End Point，例如：h1.tdengine.com:6030

    提示
    1. 自 3.4.0.0 版开始，企业版与社区版不完全兼容，为避免二者互联导致兼容性问题，请务必安装与服务端对应的客户端驱动。当使用社区版驱动连接企业版服务端或使用企业版驱动连接社区版服务端时，会返回错误“Edition not compatible”。
    2. 如本机没有部署 TDengine 服务，仅安装了应用驱动，则 taos.cfg 中仅需配置 firstEP，无需在本机配置 FQDN。
    3. 为防止与服务器端连接时出现“Unable to resolve FQDN”错误，建议确认本机的 /etc/hosts 文件已经配置了服务器正确的 FQDN 值，或配置好了 DNS 服务。

    安装验证​

    以上安装和配置完成后，并确认 TDengine TSDB 服务已经正常启动运行，此时可以执行安装包里带有的 TDengine TSDB 命令行程序 taos 进行登录。

    在 Linux shell 下直接执行 taos 连接到 TDengine 服务，进入到 TDengine CLI 界面，示例如下：

    $ taos

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

    taos>

    安装连接器​

    如果使用 Maven 管理项目，只需在 pom.xml 中加入以下依赖。

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

    建立连接​

    在执行这一步之前，请确保有一个正在运行的，且可以访问到的 TDengine TSDB，而且服务端的 FQDN 配置正确。以下示例代码，都假设 TDengine TSDB 安装在本机，且 FQDN（默认 localhost）和 serverPort（默认 6030）都使用默认配置。

    连接参数​

    连接的配置项较多，因此在建立连接之前，我们能先介绍一下各语言连接器建立连接使用的参数。

    Java 连接器建立连接的参数有 URL 和 Properties。TDengine TSDB 的 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]

    URL 和 Properties 的详细参数说明和如何使用详见 url 规范

    WebSocket 连接​

    下面是各语言连接器建立 WebSocket 连接代码样例。演示了如何使用 WebSocket 连接方式连接到 TDengine TSDB 数据库，并对连接设定一些参数。整个过程主要涉及到数据库连接的建立和异常处理。

    public static void main(String[] args) throws Exception {
    // use
    // String jdbcUrl =
    // "jdbc:TAOS-WS://localhost:6041/dbName?user=root&password=taosdata&varcharAsString=true";
    // if you want to connect a specified database named "dbName".
    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.");

        // you can use the connection for execute SQL here

    } catch (Exception ex) {
        // please refer to the JDBC specifications for detailed exceptions info
        System.out.printf("Failed to connect to %s, %sErrMessage: %s%n",
                jdbcUrl,
                ex instanceof SQLException ? "ErrCode: " + ((SQLException) ex).getErrorCode() + ", " : "",
                ex.getMessage());
        // Print stack trace for context in examples. Use logging in production.
        ex.printStackTrace();
        throw ex;
    }
    }

    查看源码

    原生连接​

    Go/C#/Java 已废弃，2027-01-01 下线

    下面是各语言连接器建立原生连接代码样例。演示了如何使用原生连接方式连接到 TDengine TSDB 数据库，并对连接设定一些参数。整个过程主要涉及到数据库连接的建立和异常处理。

    public static void main(String[] args) throws Exception {
        // use
        // String jdbcUrl =
        // "jdbc:TAOS://localhost:6030/dbName?user=root&password=taosdata";
        // if you want to connect a specified database named "dbName".
        String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata";
        Properties connProps = new Properties();
        connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8");
        connProps.setProperty(TSDBDriver.PROPERTY_KEY_LOCALE, "en_US.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.");

            // you can use the connection for execute SQL here

        } catch (Exception ex) {
            // please refer to the JDBC specifications for detailed exceptions info
            System.out.printf("Failed to connect to %s, %sErrMessage: %s%n",
                    jdbcUrl,
                    ex instanceof SQLException ? "ErrCode: " + ((SQLException) ex).getErrorCode() + ", " : "",
                    ex.getMessage());
            // Print stack trace for context in examples. Use logging in production.
            ex.printStackTrace();
            throw ex;
        }
    }

    查看源码

    提示

    如果建立连接失败，大部分情况下是 FQDN 或防火墙的配置不正确，详细的排查方法请看 《常见问题及反馈》 中的“遇到错误 Unable to establish connection, 我怎么办？”

    连接池​

    有些连接器提供了连接池，或者可以与已有的连接池组件配合使用。使用连接池，应用程序可以快速地从连接池中获取可用连接，避免了每次操作时创建和销毁连接的开销。这不仅减少了资源消耗，还提高了响应速度。此外，连接池还支持对连接的管理，如最大连接数限制、连接的有效性检查，确保了连接的高效和可靠使用。我们推荐使用连接池管理连接。
    下面是各语言连接器的连接池支持代码样例。

    HikariCP

    使用示例如下：

    public static void main(String[] args) throws Exception {
        HikariConfig config = new HikariConfig();
        // jdbc properties
        config.setJdbcUrl("jdbc:TAOS-WS://127.0.0.1:6041/log?varcharAsString=true");
        config.setUsername("root");
        config.setPassword("taosdata");
        // connection pool configurations
        config.setMinimumIdle(10); // minimum number of idle connection
        config.setMaximumPoolSize(10); // maximum number of connection in the pool
        config.setConnectionTimeout(30000); // maximum wait milliseconds for get connection from pool
        config.setMaxLifetime(0); // maximum life time for each connection
        config.setIdleTimeout(0); // max idle time for recycle idle connection

        HikariDataSource dataSource = new HikariDataSource(config); // create datasource

        Connection connection = dataSource.getConnection(); // get connection
        Statement statement = connection.createStatement(); // get statement

        // query or insert
        // ...
        statement.close();
        connection.close(); // put back to connection pool
        dataSource.close();
    }

    查看源码

    通过 HikariDataSource.getConnection() 获取连接后，使用完成后需要调用 close() 方法，实际上它并不会关闭连接，只是放回连接池中。 更多 HikariCP 使用问题请查看 官方说明。

    Druid

    使用示例如下：

    public static void main(String[] args) throws Exception {
        String url = "jdbc:TAOS-WS://127.0.0.1:6041/log?varcharAsString=true";

        DruidDataSource dataSource = new DruidDataSource();
        // jdbc properties
        dataSource.setDriverClassName("com.taosdata.jdbc.ws.WebSocketDriver");
        dataSource.setUrl(url);
        dataSource.setUsername("root");
        dataSource.setPassword("taosdata");
        // pool configurations
        dataSource.setInitialSize(10);
        dataSource.setMinIdle(10);
        dataSource.setMaxActive(10);
        dataSource.setMaxWait(30000);

        Connection connection = dataSource.getConnection(); // get connection
        Statement statement = connection.createStatement(); // get statement
        // query or insert
        // ...

        statement.close();
        connection.close(); // put back to connection pool
        dataSource.close();
    }

    查看源码

    更多 druid 使用问题请查看 官方说明。

    SOC 2 Certified
    ISO 27001 Certified
    ISO 27017 Certified
    TDengine 专为物联网IoT平台、工业大数据平台设计。其中，TDengine TSDB 是一款高性能、分布式的时序数据库（Time Series Database），同时它还带有内建的缓存、流式计算、数据订阅等系统功能；TDengine IDMP 是一款AI原生工业数据管理平台，它通过树状层次结构建立数据目录，对数据进行标准化、情景化，并通过 AI 提供实时分析、可视化、事件管理与报警等功能。
    产品
    TDengine TSDB
    TDengine IDMP
    TDengine Cloud
    学习
    TSDB 文档
    IDMP 文档
    博客
    资源
    公司
    关于我们
    技术支持
    新闻动态
    安全性
    联系我们
    招贤纳士
    服务条款
    隐私
    场景
    物联网
    工业互联网
    车联网
    IT 运维
    电力能源
    金融
    TDengine AI Chat
    点击使用 AI 问答
    TDengine 的智能助手
    TDengine Database
    加小 T 为好友
    即可加入物联网大数据技术前沿群
    点击填写表单
    获得解决方案专家帮助
    © 2017-2026 涛思数据
    京公网安备 11010502047618号
    新版时序数据库 TDengine Database v3.0