使用说明

获取连接

如下所示配置即可获取 TDengine Connection：

  1. Class.forName("com.taosdata.jdbc.TSDBDriver");
  2. String jdbcUrl = "jdbc:TAOS://127.0.0.1:6030/log?user=root&password=taosdata";
  3. Connection conn = DriverManager.getConnection(jdbcUrl);

端口 6030 为默认连接端口，JDBC URL 中的 log 为系统本身的监控数据库。

TDengine 的 JDBC URL 规范格式为： jdbc:TSDB://{host_ip}:{port}/[database_name]?[user={user}|&password={password}|&charset={charset}|&cfgdir={config_dir}|&locale={locale}|&timezone={timezone}]

其中，{} 中的内容必须，[] 中为可选。配置参数说明如下：

  • user：登录 TDengine 用户名，默认值 root。
  • password：用户登录密码，默认值 taosdata。
  • charset：客户端使用的字符集，默认值为系统字符集。
  • cfgdir：客户端配置文件目录路径，Linux OS 上默认值 /etc/taos ，Windows OS 上默认值 C:/TDengine/cfg。
  • locale：客户端语言环境，默认值系统当前 locale。
  • timezone：客户端使用的时区，默认值为系统当前时区。

以上参数可以在 3 处配置，优先级由高到低分别如下：

  1. JDBC URL 参数 如上所述，可以在 JDBC URL 的参数中指定。
  2. java.sql.DriverManager.getConnection(String jdbcUrl, Properties connProps)
  1. public Connection getConn() throws Exception{
  2.   Class.forName("com.taosdata.jdbc.TSDBDriver");
  3.   String jdbcUrl = "jdbc:TAOS://127.0.0.1:0/log?user=root&password=taosdata";
  4.   Properties connProps = new Properties();
  5.   connProps.setProperty(TSDBDriver.PROPERTY_KEY_USER, "root");
  6.   connProps.setProperty(TSDBDriver.PROPERTY_KEY_PASSWORD, "taosdata");
  7.   connProps.setProperty(TSDBDriver.PROPERTY_KEY_CONFIG_DIR, "/etc/taos");
  8.   connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8");
  9.   connProps.setProperty(TSDBDriver.PROPERTY_KEY_LOCALE, "en_US.UTF-8");
  10.   connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8");
  11.   Connection conn = DriverManager.getConnection(jdbcUrl, connProps);
  12.   return conn;
  13. }

  1. 客户端配置文件 taos.cfg

    linux 系统默认配置文件为 /var/lib/taos/taos.cfg，windows 系统默认配置文件路径为 C:\TDengine\cfg\taos.cfg。

  1. # client default username
  2. # defaultUser           root
  4. # client default password
  5. # defaultPass           taosdata
  7. # default system charset
  8. # charset               UTF-8
  10. # system locale
  11. # locale                en_US.UTF-8

更多详细配置请参考客户端配置

创建数据库和表

  1. Statement stmt = conn.createStatement();
  3. // create database
  4. stmt.executeUpdate("create database if not exists db");
  6. // use database
  7. stmt.executeUpdate("use db");
  9. // create table
  10. stmt.executeUpdate("create table if not exists tb (ts timestamp, temperature int, humidity float)");

注意：如果不使用 use db 指定数据库，则后续对表的操作都需要增加数据库名称作为前缀，如 db.tb。

插入数据

  1. // insert data
  2. int affectedRows = stmt.executeUpdate("insert into tb values(now, 23, 10.3) (now + 1s, 20, 9.3)");
  4. System.out.println("insert " + affectedRows + " rows.");

now 为系统内部函数，默认为服务器当前时间。 now + 1s 代表服务器当前时间往后加 1 秒，数字后面代表时间单位：a(毫秒), s(秒), m(分), h(小时), d(天)，w(周), n(月), y(年)。

查询数据

  1. // query data
  2. ResultSet resultSet = stmt.executeQuery("select * from tb");
  4. Timestamp ts = null;
  5. int temperature = 0;
  6. float humidity = 0;
  7. while(resultSet.next()){
  9.     ts = resultSet.getTimestamp(1);
  10.     temperature = resultSet.getInt(2);
  11.     humidity = resultSet.getFloat("humidity");
  13.     System.out.printf("%s, %d, %s\n", ts, temperature, humidity);
  14. }

查询和操作关系型数据库一致，使用下标获取返回字段内容时从 1 开始，建议使用字段名称获取。

关闭资源

  1. resultSet.close();
  2. stmt.close();
  3. conn.close();

注意务必要将 connection 进行关闭，否则会出现连接泄露。

与连接池使用

HikariCP

  • 引入相应 HikariCP maven 依赖：
  1. <dependency>
  2.     <groupId>com.zaxxer</groupId>
  3.     <artifactId>HikariCP</artifactId>
  4.     <version>3.4.1</version>
  5. </dependency>
  • 使用示例如下：
  1.  public static void main(String[] args) throws SQLException {
  2.     HikariConfig config = new HikariConfig();
  3.     config.setJdbcUrl("jdbc:TAOS://127.0.0.1:6030/log");
  4.     config.setUsername("root");
  5.     config.setPassword("taosdata");
  7.     config.setMinimumIdle(3);           //minimum number of idle connection
  8.     config.setMaximumPoolSize(10);      //maximum number of connection in the pool
  9.     config.setConnectionTimeout(10000); //maximum wait milliseconds for get connection from pool
  10.     config.setIdleTimeout(60000);       // max idle time for recycle idle connection 
  11.     config.setConnectionTestQuery("describe log.dn"); //validation query
  12.     config.setValidationTimeout(3000);   //validation query timeout
  14.     HikariDataSource ds = new HikariDataSource(config); //create datasource
  16.     Connection  connection = ds.getConnection(); // get connection
  17.     Statement statement = connection.createStatement(); // get statement
  19.     //query or insert 
  20.     // ...
  22.     connection.close(); // put back to conneciton pool
  23. }

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

Druid

  • 引入相应 Druid maven 依赖：
  1. <dependency>
  2.     <groupId>com.alibaba</groupId>
  3.     <artifactId>druid</artifactId>
  4.     <version>1.1.20</version>
  5. </dependency>
  • 使用示例如下：
  1. public static void main(String[] args) throws Exception {
  2.     Properties properties = new Properties();
  3.     properties.put("driverClassName","com.taosdata.jdbc.TSDBDriver");
  4.     properties.put("url","jdbc:TAOS://127.0.0.1:6030/log");
  5.     properties.put("username","root");
  6.     properties.put("password","taosdata");
  8.     properties.put("maxActive","10"); //maximum number of connection in the pool
  9.     properties.put("initialSize","3");//initial number of connection
  10.     properties.put("maxWait","10000");//maximum wait milliseconds for get connection from pool
  11.     properties.put("minIdle","3");//minimum number of connection in the pool
  13.     properties.put("timeBetweenEvictionRunsMillis","3000");// the interval milliseconds to test connection
  15.     properties.put("minEvictableIdleTimeMillis","60000");//the minimum milliseconds to keep idle
  16.     properties.put("maxEvictableIdleTimeMillis","90000");//the maximum milliseconds to keep idle
  18.     properties.put("validationQuery","describe log.dn"); //validation query
  19.     properties.put("testWhileIdle","true"); // test connection while idle
  20.     properties.put("testOnBorrow","false"); // don't need while testWhileIdle is true
  21.     properties.put("testOnReturn","false"); // don't need while testWhileIdle is true
  23.     //create druid datasource
  24.     DataSource ds = DruidDataSourceFactory.createDataSource(properties);
  25.     Connection  connection = ds.getConnection(); // get connection
  26.     Statement statement = connection.createStatement(); // get statement
  28.     //query or insert 
  29.     // ...
  31.     connection.close(); // put back to conneciton pool
  32. }

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

注意事项

  • TDengine v1.6.4.1 版本开始提供了一个专门用于心跳检测的函数 select server_status()，所以在使用连接池时推荐使用 select server_status() 进行 Validation Query。

如下所示，select server_status() 执行成功会返回 1。

  1. taos> select server_status();
  2. server_status()|
  3. ================
  4. 1              |
  5. Query OK, 1 row(s) in set (0.000141s)