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 提供两种:

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

无论使用何种方式建立连接,连接器都提供了相同或相似的 API 操作数据库,都可以执行 SQL 语句,只是初始化连接的方式稍有不同,用户在使用上不会感到什么差别。

关键不同点在于:

  1. 使用 REST 连接,用户无需安装客户端驱动程序 taosc,具有跨平台易用的优势,但性能要下降 30%左右。
  2. 使用原生连接可以体验 TDengine 的全部功能,如参数绑定接口订阅等等。

安装客户端驱动 taosc

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

安装步骤

  1. 下载客户端安装包

    所有下载

    1. 解压缩软件包

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

    2. 执行安装脚本

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

      • _ install_client.sh_:安装脚本,用于应用驱动程序
      • _ taos.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
    Welcome to the TDengine shell from Linux, Client Version:2.0.5.0
    Copyright (c) 2017 by TAOS Data, Inc. All rights reserved.
    taos> show databases;
    name | created_time | ntables | vgroups | replica | quorum | days | keep1,keep2,keep(D) | cache(MB)| blocks | minrows | maxrows | wallevel | fsync | comp | precision | status |
    =========================================================================================================================================================================================================================
    test | 2020-10-14 10:35:48.617 | 10 | 1 | 1 | 1 | 2 | 3650,3650,3650 | 16| 6 | 100 | 4096 | 1 | 3000 | 2 | ms | ready |
    log | 2020-10-12 09:08:21.651 | 4 | 1 | 1 | 1 | 10 | 30,30,30 | 1| 3 | 100 | 4096 | 1 | 3000 | 2 | us | ready |
    Query OK, 2 row(s) in set (0.001198s)
    taos>

    安装连接器

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

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

    建立连接

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

    原生连接
    package com.taos.example;

    import java.sql.Connection;
    import java.sql.DriverManager;
    import java.sql.SQLException;
    import java.util.Properties;

    import com.taosdata.jdbc.TSDBDriver;

    public class JNIConnectExample {
    public static void main(String[] args) throws SQLException {
    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");
    Connection conn = DriverManager.getConnection(jdbcUrl, connProps);
    System.out.println("Connected");
    conn.close();
    }
    }

    // use
    // String jdbcUrl = "jdbc:TAOS://localhost:6030/dbName?user=root&password=taosdata";
    // if you want to connect a specified database named "dbName".

    查看源码

    REST 连接
    public static void main(String[] args) throws SQLException {
    String jdbcUrl = "jdbc:TAOS-RS://localhost:6041?user=root&password=taosdata";
    Connection conn = DriverManager.getConnection(jdbcUrl);
    System.out.println("Connected");
    conn.close();
    }

    查看源码

    使用 REST 连接时,如果查询数据量比较大,还可开启批量拉取功能。

    开启批量拉取功能
    public static void main(String[] args) throws SQLException {
    String jdbcUrl = "jdbc:TAOS-RS://localhost:6041?user=root&password=taosdata";
    Properties connProps = new Properties();
    connProps.setProperty(TSDBDriver.PROPERTY_KEY_BATCH_LOAD, "true");
    Connection conn = DriverManager.getConnection(jdbcUrl, connProps);
    System.out.println("Connected");
    conn.close();
    }

    查看源码

    更多连接参数配置,参考Java 连接器

    tip

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