Skip to main content

建立连接

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

连接方式​

连接器建立连接的方式，TDengine 提供三种:

  1. 通过客户端驱动程序 taosc 直接与服务端程序 taosd 建立连接，这种连接方式下文中简称 “原生连接”。
  2. 通过 taosAdapter 组件提供的 REST API 建立与 taosd 的连接，这种连接方式下文中简称 “REST 连接”
  3. 通过 taosAdapter 组件提供的 WebSocket API 建立与 taosd 的连接，这种连接方式下文中简称 “WebSocket 连接”

TDengine connection type

无论使用何种方式建立连接，连接器都提供了相同或相似的 API 操作数据库，都可以执行 SQL 语句，只是初始化连接的方式稍有不同，用户在使用上不会感到什么差别。 各种连接方式和各语言连接器支持情况请参考：连接器功能特性

关键不同点在于：

  1. 使用 原生连接，需要保证客户端的驱动程序 taosc 和服务端的 TDengine 版本配套。
  2. 使用 REST 连接，用户无需安装客户端驱动程序 taosc，具有跨平台易用的优势，但是无法体验数据订阅和二进制数据类型等功能。另外与 原生连接 和 WebSocket 连接相比，REST连接的性能最低。REST 接口是无状态的。在使用 REST 连接时，需要在 SQL 中指定表、超级表的数据库名称。
  3. 使用 WebSocket 连接，用户也无需安装客户端驱动程序 taosc。
  4. 连接云服务实例，必须使用 REST 连接 或 WebSocket 连接。

推荐使用 WebSocket 连接

安装客户端驱动 taosc​

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

安装步骤​

  1. 下载客户端安装包
下载 TDengine
TDengine Database
输入您的电子邮箱以接收下载链接
同意涛思数据通过此邮件地址联系我

请勾选同意，便于我们通过邮件发送安装包给您。

    1. 解压缩软件包

      将软件包放置在当前用户可读写的任意目录下，然后执行下面的命令：tar -xzvf TDengine-client-VERSION.tar.gz 其中 VERSION 需要替换为实际版本的字符串。

    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

    tip
    1. 如本机没有部署 TDengine 服务，仅安装了应用驱动，则 taos.cfg 中仅需配置 firstEP，无需在本机配置 FQDN。
    2. 为防止与服务器端连接时出现“Unable to resolve FQDN”错误，建议确认本机的 /etc/hosts 文件已经配置了服务器正确的 FQDN 值，或配置好了 DNS 服务。

    安装验证​

    以上安装和配置完成后，并确认 TDengine 服务已经正常启动运行，此时可以执行安装包里带有的 TDengine 命令行程序 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.3.3</version>
    </dependency>

    建立连接​

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

    连接参数​

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

    Java 连接器建立连接的参数有 URL 和 Properties。
    TDengine 的 JDBC URL 规范格式为： jdbc:[TAOS|TAOS-WS|TAOS-RS]://[host_name]:[port]/[database_name]?[user={user}|&password={password}|&charset={charset}|&cfgdir={config_dir}|&locale={locale}|&timezone={timezone}|&batchfetch={batchfetch}]

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

    WebSocket 连接​

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

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

    查看源码

    原生连接​

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

    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;
        }
    }

    查看源码

    REST 连接​

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

    public static void main(String[] args) throws Exception {
        String jdbcUrl = "jdbc:TAOS-RS://localhost:6041?user=root&password=taosdata";
        try (Connection conn = DriverManager.getConnection(jdbcUrl)) {
            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;
        }
    }

    查看源码

    tip

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

    连接池​

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

    HikariCP

    使用示例如下：

    public static void main(String[] args) throws Exception {
        HikariConfig config = new HikariConfig();
        // jdbc properties
        config.setJdbcUrl("jdbc:TAOS://127.0.0.1:6030/log");
        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
        config.setConnectionTestQuery("SELECT SERVER_VERSION()"); // validation query

        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://127.0.0.1:6030/log";

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

        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 使用问题请查看官方说明。

    TDengine Database
    TDengine 核心是一款高性能、集群开源、云原生的时序数据库（Time Series Database，TSDB），专为物联网、工业互联网、电力、IT 运维等场景设计并优化，具有极强的弹性伸缩能力。同时它还带有内建的缓存、流式计算、数据订阅等系统功能，能大幅减少系统设计的复杂度，降低研发和运营成本，是一个高性能、分布式的物联网、工业大数据平台。
    产品
    TDengine Enterprise
    TDengine Cloud
    学习
    文档
    博客
    资源
    公司
    关于我们
    技术支持
    新闻动态
    联系我们
    招贤纳士
    服务条款
    隐私
    场景
    物联网
    工业互联网
    车联网
    IT 运维
    电力能源
    金融
    TDengine Database
    TDengine Database
    加小 T 为好友
    即可加入物联网大数据技术前沿群
    点击填写表单
    获得解决方案专家帮助
    © 2023 涛思数据
    京公网安备 11010502047618号
    新版时序数据库 TDengine v3.0