# 开始使用 JDBC 3.x 驱动程序
<a name="jdbc-v3-driver-getting-started"></a>

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

**Topics**
+ [安装说明](#jdbc-v3-driver-installation-instructions)
+ [运行驱动程序](#jdbc-v3-driver-running-the-driver)
+ [配置驱动程序](#jdbc-v3-driver-configuring-the-driver)
+ [从 Athena JDBC 版本 2 驱动程序升级](#jdbc-v3-driver-upgrading-from-the-athena-jdbc-v2-driver-to-v3)

## 安装说明
<a name="jdbc-v3-driver-installation-instructions"></a>

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

### 在自定义应用程序中
<a name="jdbc-v3-driver-installation-in-a-custom-application"></a>

下载包含驱动程序 jar 及其依赖项的 `.zip` 文件。每个依赖项都有自己的 `.jar` 文件。将驱动程序 jar 作为依赖项添加到自定义应用程序中。根据您是否已经将这些依赖项从其他来源添加到应用程序中，选择性地添加驱动程序 jar 的依赖项。

### 在第三方 SQL 客户端中
<a name="jdbc-v3-driver-installation-in-a-third-party-sql-client"></a>

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

## 运行驱动程序
<a name="jdbc-v3-driver-running-the-driver"></a>

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

### 在自定义应用程序中
<a name="jdbc-v3-driver-running-in-a-custom-application"></a>

使用 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 客户端中
<a name="jdbc-v3-driver-running-in-a-third-party-sql-client"></a>

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

## 配置驱动程序
<a name="jdbc-v3-driver-configuring-the-driver"></a>

您可以使用连接参数来配置 Amazon Athena JDBC 驱动程序。有关受支持的连接参数，请参阅 [Amazon Athena JDBC 3.x 连接参数](jdbc-v3-driver-connection-parameters.md)。

### 在自定义应用程序中
<a name="jdbc-v3-driver-configuring-in-a-custom-application"></a>

要在自定义应用程序中设置 JDBC 驱动程序的连接参数，请执行以下任一操作：
+ 将参数名称及其值添加到 `Properties` 对象中。在调用 `Connection#connect` 时，请将该对象与 URL 一起传递。有关示例，请参阅[运行驱动程序](#jdbc-v3-driver-running-the-driver)中的示例 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 客户端中
<a name="jdbc-v3-driver-configuring-in-a-third-party-sql-client"></a>

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

## 从 Athena JDBC 版本 2 驱动程序升级
<a name="jdbc-v3-driver-upgrading-from-the-athena-jdbc-v2-driver-to-v3"></a>

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

### 驱动程序类
<a name="jdbc-v3-driver-upgrading-driver-class"></a>

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

### 连接字符串
<a name="jdbc-v3-driver-upgrading-connection-string"></a>

版本 3 驱动程序在 JDBC 连接字符串 URL 的开头使用 `jdbc:athena://` 作为协议。版本 3 驱动程序也支持版本 2 协议 `jdbc:awsathena://`，但不推荐使用版本 2 协议。为避免未定义的行为，如果版本 2（或接受以 `jdbc:awsathena://` 开头的连接字符串的任何其他驱动程序）已注册到 [DriverManager](https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html) 类，则版本 3 不接受以 `jdbc:awsathena://` 开头的连接字符串。

### 凭证提供程序
<a name="jdbc-v3-driver-upgrading-credentials-providers"></a>

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

为版本 2 驱动程序编写的自定义凭证提供程序需要进行修改，以便版本 3 驱动程序实现来自新 适用于 Java 的 AWS SDK 的 [AwsCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/AwsCredentialsProvider.html) 接口，而不是来自以前 适用于 Java 的 AWS SDK 的 [AWSCredentialsProvider](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/AWSCredentialsProvider.html) 接口。

JDBC 3.x 驱动程序不支持 `PropertiesFileCredentialsProvider`。该提供程序曾在 JDBC 2.x 驱动程序中使用，但属于适用于 Java 的 AWS SDK 的先前版本，该版本的支持即将结束。要在 JDBC 3.x 驱动程序中实现相同的功能，请改用 [AWS 配置文件凭证](jdbc-v3-driver-aws-configuration-profile-credentials.md) 提供程序。

### 日志级别
<a name="jdbc-v3-driver-upgrading-log-level"></a>

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


****  

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

### 查询 ID 检索
<a name="jdbc-v3-driver-upgrading-query-id-retrieval"></a>

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

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