全部产品
Search
文档中心

TSQL JDBC支持

更新时间: 2022-01-20

阿里云时间序列数据库 TSDB的SQL查询引擎支持JDBC协议,用户可以使用常见的支持JDBC访问方式的客户端来访问TSDB,或者也可以在自己的Java应用程序里,通过JDBC协议,使用TSQL查询TSDB时序数据。

用户可以在自己的实例控制台上查看到JDBC访问信息(需要TSDB实例的版本满足要求):TSQL jdbc url

接下来会简要介绍如何在Java应用程序里,如何通过JDBC协议进行TSQL查询获取TSDB数据库的数据。

一. JDBC连接示例

1. Driver依赖引入

运行时要求:

  • Java 1.8 Runtime。

  • 配置实例JBDC访问, 获取JDBC URL。

  • 配置实例网络黑白名单, 确保应用客户端可以正常访问实例。

TSQL的JDBC driver的依赖已经发布到Maven仓库, 这里以Maven来管理项目(tsql_jdbc_app)为例,把下面的内容加入的pom.xml。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.alibaba.tsdb.tsql</groupId>
    <artifactId>tsql_jdbc_app</artifactId>
    <version>1.0-SNAPSHOT</version>

    <dependencies>
        <!-- https://mvnrepository.com/artifact/org.apache.drill.exec/drill-jdbc -->
        <dependency>
            <groupId>org.apache.drill.exec</groupId>
            <artifactId>drill-jdbc-all</artifactId>
            <version>1.15.0</version>
            <exclusions>
                <exclusion>
                    <groupId>org.slf4j</groupId>
                    <artifactId>log4j-over-slf4j</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <artifactId>maven-assembly-plugin</artifactId>
                <configuration>
                    <archive>
                        <manifest>
                            <mainClass>com.alibaba.tsdb.tsql.TsqlJdbcSampleApp</mainClass>
                        </manifest>
                    </archive>
                    <descriptorRefs>
                        <descriptorRef>jar-with-dependencies</descriptorRef>
                    </descriptorRefs>
                </configuration>
                <executions>
                    <execution>
                        <id>make-assembly</id> <!-- this is used for inheritance merges -->
                        <phase>package</phase> <!-- bind to the packaging phase -->
                        <goals>
                            <goal>single</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>
说明

注意上面的内容,其目的是我们可以获得一个包括把所有依赖jar,以及我们的应用程序的.class合成一个jar包。

2. JDBC 连接示例代码

请注意,这仅仅是示例,在你的应用中,你需要修改相应的参数。

  • host:在第一步中申请的TSDB实例的hostname或IP地址。

  • port:在阿里云TSDB时序数据库上,缺省的JDBC端口是3306。

  • sql:所需要执行的TSQL查询语句。

在Java应用项目下,创建一个package com.alibaba.tsdb.tsql, 并创建一个Java 源文件TsqlJdbcSampleApp.code-demo

完整代码:

package com.alibaba.tsdb.tsql;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class TsqlJdbcSampleApp {
    public static void main(String[] args) throws Exception {
        Connection connection = null;
        Statement stmt = null;

        try {
            // step 1: Register JDBC driver
            Class.forName("org.apache.drill.jdbc.Driver");

            // hostname or address of TSDB instance.
            String host = "ts-uf64t3199j58j8251.tsql.hitsdb.rds.aliyuncs.com";
            // port for TSQL JDBC service
            int port = 3306;

            String jdbcUrl = String.format("jdbc:drill:drillbit=%s:%s", host, port);

            // step 2: Open connection
            System.out.println("Connecting to database @ " + jdbcUrl + "  ...");
            connection = DriverManager.getConnection(jdbcUrl);

            // step 3: Create a statement
            System.out.println("Creating statement ...");
            stmt = connection.createStatement();


            // step 4: Execute a query using the statement.
            String sql = "select hostname, `timestamp`, `value` " +
                "from tsdb.`cpu.usage_system` " +
                "where `timestamp` between '2019-03-01' and '2019-03-01 00:05:00'";

            ResultSet rs = stmt.executeQuery(sql);

            // step 5: Extract data from ResultSet.
            int row = 0;
            System.out.println("hostname\ttimestamp\tvalue");
            System.out.println("-----------------------------------------------------");
            while (rs.next()) {
                row++;
                System.out.println(rs.getString("hostname") + "\t" + rs.getTimestamp("timestamp") + "\t" +rs.getDouble("value"));
            }
            System.out.println("-----------------------------------------------------");
            System.out.println( row + "rows returned");

        } catch(SQLException se){
            //Handle errors for JDBC
            se.printStackTrace();
        }catch(Exception e){
            //Handle errors for Class.forName
            e.printStackTrace();
        }finally{
            //finally block used to close resources
            try{
                if(stmt!=null)
                    stmt.close();
            }catch(SQLException se2){
            }// nothing we can do
            try{
                if(connection!=null)
                    connection.close();
            }catch(SQLException se){
                se.printStackTrace();
            }//end finally try
        }//end try
        System.out.println("Goodbye!");
    }
}

3. 编译与执行

在项目根目录下,执行下面的Maven命令 maven clean install

执行完成后, 你将在项目目录/targets下获得一个可执行Jar文件:tsql_jdbc_app-1.0-SNAPSHOT-jar-with-dependencies.jar

执行该应用程序:

java -jar target/tsql_jdbc_app-1.0-SNAPSHOT-jar-with-dependencies.jar

下图显示了我们刚才讲了的TSQL JDBC应用程序的部分查询结果。jdbc-results

说明

通过以上的步骤,你可以使用JDBC协议,编写Java应用程序,进行时序数据查询。

二. JDBC协议使用限制

TSQL的JDBC协议存在功能限制。在使用TSQL JDBC协议前请对照检查,具体限制和说明如下:

  1. TSQL 目前仅支持时序数据查询和时序元数据查询,不支持数据写入,修改和删除

  2. TSDB没有事务(Transaction)的支持。

具体JDBC API的限制说明如下:

Interfae

Method

TSDB JDBC支持情况

Connection

setAutoCommit(boolean)

仅允许true作为传入参数

Connection

getAutoCommit()

返回true

Connection

commit()

调用会引发异常: SQLFeatureNotSupportedException

Connection

rollback()

调用会引发异常:SQLFeatureNotSupportedException

Connection

setTransactionIsolation(int level)

仅允许TRANSACTION_NONE

Connection

getTransactionIsolation()

仅允许TRANSACTION_NONE

Connection

setSavePoint()

调用会引发异常 SQLFeatureNotSupportedException

Connection

setSavePoint(String name)

调用会引发异常 SQLFeatureNotSupportedException

Connection

rollback(Savepoint savepoint)

调用会引发异常 SQLFeatureNotSupportedException

Connection

releaseSavePoint(Savepoint savepoint)

调用会引发异常 SQLFeatureNotSupportedException

Connection

setNetworkTimeout()

调用会引发异常 SQLFeatureNotSupportedException

Connection

getNetworkTimeout()

调用会引发异常 SQLFeatureNotSupportedException