View a markdown version of this page

开始使用 JDBC 3.x 驱动程序 - Amazon Athena
安装说明运行驱动程序配置驱动程序从 Athena JDBC 版本 2 驱动程序升级

开始使用 JDBC 3.x 驱动程序

参照本节中的信息开始使用 Amazon Athena JDBC 3.x 驱动程序。

安装说明

您可以在自定义应用程序中或通过第三方 SQL 客户端使用 JDBC 3.x 驱动程序。

在自定义应用程序中

下载包含驱动程序及其依赖项的 .zip 文件。将驱动程序 .jar 文件和 runtime-dependencies 目录中的所有其他 .jar 文件添加到自定义应用程序的 Java 类路径中。只有当您的应用程序已经提供了该依赖项的兼容版本时，才省略 .jar 文件。AthenaStreamingJavaClient-2.0.jar 文件提供了 software.amazon.awssdk.services.athenastreaming.AthenaStreamingAsyncClient 类。除非您的应用程序已经提供了该类，否则请包含此文件。

在第三方 SQL 客户端中

下载驱动程序 uber jar 文件，然后按照客户端的说明将其添加到该第三方 SQL 客户端。

运行驱动程序

要运行驱动程序，您可以使用自定义应用程序或第三方 SQL 客户端。

在自定义应用程序中

使用 JDBC 接口与程序中的 JDBC 驱动程序进行交互。以下代码显示了一个自定义 Java 应用程序示例。

public static void main(String args[]) throws SQLException {
    Properties connectionParameters = new Properties();
    connectionParameters.setProperty("Workgroup", "primary");
    connectionParameters.setProperty("Region", "us-east-2");
    connectionParameters.setProperty("Catalog", "AwsDataCatalog");
    connectionParameters.setProperty("Database","sampledatabase");
    connectionParameters.setProperty("OutputLocation","s3://amzn-s3-demo-bucket");
    connectionParameters.setProperty("CredentialsProvider","DefaultChain");
    String url = "jdbc:athena://";
    AthenaDriver driver = new AthenaDriver();
    Connection connection = driver.connect(url, connectionParameters);
    Statement statement = connection.createStatement();
    String query = "SELECT * from sample_table LIMIT 10";
    ResultSet resultSet = statement.executeQuery(query);
    printResults(resultSet); // A custom-defined method for iterating over a
                             // result set and printing its contents
}

在第三方 SQL 客户端中

请按照自己正在使用的 SQL 客户端的文档进行操作。您通常可以使用 SQL 客户端的图形用户界面来输入和提交查询，查询结果显示在同一个界面中。

配置驱动程序

您可以使用连接参数来配置 Amazon Athena JDBC 驱动程序。有关受支持的连接参数，请参阅 Amazon Athena JDBC 3.x 连接参数。

在自定义应用程序中

要在自定义应用程序中设置 JDBC 驱动程序的连接参数，请执行以下任一操作：

  • 将参数名称及其值添加到 Properties 对象中。在调用 Connection#connect 时，请将该对象与 URL 一起传递。有关示例，请参阅运行驱动程序中的示例 Java 应用程序。

  • 在连接字符串（URL）中，使用以下格式将参数名称及其值直接添加到协议前缀之后。

    <parameterName>=<parameterValue>;

    在每个参数名/参数值对的末尾使用分号，分号后面不留空格，如下例所示。

    String url = "jdbc:athena://WorkGroup=primary;Region=us-east-1;...;";AthenaDriver driver = new AthenaDriver();Connection connection = driver.connect(url, null);
    注意

    如果在连接字符串和 Properties 对象中都指定了参数，则优先使用连接字符串中的值。不建议在这两个地方指定相同的参数。

  • 将参数值作为参数添加到 AthenaDataSource 的方法中，如下例所示。

    AthenaDataSource dataSource = new AthenaDataSource();
    dataSource.setWorkGroup("primary");
    dataSource.setRegion("us-east-2");
    ...
    Connection connection = dataSource.getConnection();
    ...

在第三方 SQL 客户端中

按照自己正在使用的 SQL 客户端的说明进行操作。客户端通常会提供一个图形用户界面，用于输入参数名称及其值。

从 Athena JDBC 版本 2 驱动程序升级

大多数 JDBC 版本 3 的连接参数都向后兼容版本 2（Simba）JDBC 驱动程序。这表示版本 2 的连接字符串可以在版本 3 的驱动程序中重用。不过，某些连接参数已发生更改。此处对这些更改进行了介绍。在升级到 JDBC 驱动程序版本 3 时，如有必要，请更新现有配置。

驱动程序类

部分 BI 工具会要求您提供 JDBC 驱动程序 .jar 文件中的驱动程序类。大多数工具都会自动找到这个类。这个类在版本 3 驱动程序中的完全限定名称是 com.amazon.athena.jdbc.AthenaDriver。在版本 2 驱动程序中，这个类是 com.simba.athena.jdbc.Driver。

连接字符串

版本 3 驱动程序在 JDBC 连接字符串 URL 的开头使用 jdbc:athena:// 作为协议。版本 3 驱动程序也支持版本 2 协议 jdbc:awsathena://，但不推荐使用版本 2 协议。为避免未定义的行为，如果版本 2（或接受以 jdbc:awsathena:// 开头的连接字符串的任何其他驱动程序）已注册到 DriverManager 类，则版本 3 不接受以 jdbc:awsathena:// 开头的连接字符串。

字符串列元数据

使用 JDBC 3.x 驱动程序，您将无法再使用 JDBC 2.x StringColumnLength 连接参数。相反，您可以通过标准 JDBC 元数据方法（包括 ResultSetMetaData.getPrecision 和 ResultSetMetaData.getColumnDisplaySize）来获取 Athena 提供的精度。由于 Athena string 类型是无界的，因此其报告的精度可以达到 2147483647。

如果您的应用程序从 JDBC 元数据中分配固定大小的缓冲区，请将其配置为使用可变大小的缓冲区。如果您的应用程序需要有界列元数据，请在查询中将该列转换为 varchar(n)，或通过视图公开该转换。为 n 选择一个能保留所有预期数据的值，因为转换为较小的大小可能会截断值。

凭证提供程序

版本 2 驱动程序使用完全限定名称来标识不同的凭证提供程序（例如：com.simba.athena.amazonaws.auth.DefaultAWSCredentialsProviderChain）。版本 3 驱动程序使用较短的名称（例如：DefaultChain）。每个凭证提供程序的相应部分中会对新名称进行描述。

为版本 2 驱动程序编写的自定义凭证提供程序需要进行修改，以便版本 3 驱动程序实现来自新 适用于 Java 的 AWS SDK 的 AwsCredentialsProvider 接口，而不是来自以前 适用于 Java 的 AWS SDK 的 AWSCredentialsProvider 接口。

JDBC 3.x 驱动程序不支持 PropertiesFileCredentialsProvider。该提供程序曾在 JDBC 2.x 驱动程序中使用，但属于适用于 Java 的 AWS SDK 的先前版本，该版本的支持即将结束。要在 JDBC 3.x 驱动程序中实现相同的功能，请改用 AWS 配置文件凭证 提供程序。

日志级别

下表显示了 JDBC 版本 2 和版本 3 驱动程序中 LogLevel 参数的差异。

JDBC 驱动程序版本 参数名称 参数类型 默认值 可能的值 连接字符串示例
v2 LogLevel 可选 0 0-6 LogLevel=6;
v3 LogLevel 可选 TRACE OFF、ERROR、WARN、INFO、DEBUG、TRACE LogLevel=INFO;

查询 ID 检索

在版本 2 驱动程序中，您将 Statement 实例解包到 com.interfaces.core.IStatementQueryInfoProvider。该接口有两种方法：#getPReparedQueryId 和 #getQueryId。您可以使用这些方法来获取已运行查询的查询执行 ID。

在版本 3 驱动程序中，您将 Statement、PreparedStatement 和 ResultSet 实例解包到 com.amazon.athena.jdbc.AthenaResultSet 接口。该接口有一种方法：#getQueryExecutionId。