# Athena JDBC 3.x driver
<a name="jdbc-v3-driver"></a>

You can use the Athena JDBC driver to connect to Amazon Athena from many third-party SQL client tools and from custom applications.

## System Requirements
<a name="jdbc-v3-driver-system-requirements"></a>
+ Java 8 (or higher) runtime environment
+ At least 20 MB of available disk space

## Considerations and limitations
<a name="jdbc-v3-driver-considerations-and-limitations"></a>

Following are some considerations and limitations for the Athena JDBC 3.x driver.
+ **Logging** – The 3.x driver uses [SLF4J](https://www.slf4j.org/manual.html), which is an abstraction layer that enables the use of any one of several logging systems at runtime.
+ **Encryption** – When using the Amazon S3 fetcher with the `CSE_KMS` encryption option, the Amazon S3 client can't decrypt results stored in an Amazon S3 bucket. If you require `CSE_KMS` encryption, you can continue to use the streaming fetcher. Support for `CSE_KMS` encryption with the Amazon S3 fetcher is planned.

## JDBC 3.x driver download
<a name="jdbc-v3-driver-download"></a>

This section contains download and license information for the JDBC 3.x driver.

**Important**  
When you use the JDBC 3.x driver, be sure to note the following requirements:  
**Open port 444** – Keep port 444, which Athena uses to stream query results, open to outbound traffic. When you use a PrivateLink endpoint to connect to Athena, ensure that the security group attached to the PrivateLink endpoint is open to inbound traffic on port 444. 
**athena:GetQueryResultsStream policy** – Add the `athena:GetQueryResultsStream` policy action to the IAM principals that use the JDBC driver. This policy action is not exposed directly with the API. It is used only with the ODBC and JDBC drivers as part of streaming results support. For an example policy, see [AWS managed policy: AWSQuicksightAthenaAccess](security-iam-awsmanpol.md#awsquicksightathenaaccess-managed-policy). 

To download the Amazon Athena 3.x JDBC driver, visit the following links.

### JDBC driver uber jar
<a name="jdbc-v3-driver-download-uber-jar"></a>

The following download packages the driver and all its dependencies in the same `.jar` file. This download is commonly used for third-party SQL clients.

[3.7.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.7.0/athena-jdbc-3.7.0-with-dependencies.jar)

### JDBC driver lean jar
<a name="jdbc-v3-driver-download-lean-jar"></a>

The following download is a `.zip` file that contains the lean `.jar` for the driver and separate `.jar` files for the driver's dependencies. This download is commonly used for custom applications that might have dependencies that conflict with the dependencies that the driver uses. This download is useful if you want to choose which of the driver dependencies to include with the lean jar, and which to exclude if your custom application already contains one or more of them.

[3.7.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.7.0/athena-jdbc-3.7.0-lean-jar-and-separate-dependencies-jars.zip)

### License
<a name="jdbc-v3-driver-license"></a>

The following link contains the license agreement for the JDBC 3.x driver.

[License](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.7.0/LICENSE.txt)

## Trusted identity propagation with JDBC
<a name="jdbc-v3-driver-trusted-identity"></a>

You can now connect to Amazon Athena using JDBC drivers with single sign-on capabilities through AWS Identity and Access Management Identity Center. When you access Athena from tools like PowerBI, Tableau, or DBeaver, your identity and permissions automatically propagate to Athena through IAM Identity Center. For more information, see [Use Trusted identity propagation with Amazon Athena drivers](using-trusted-identity-propagation.md).

**Topics**
+ [

## System Requirements
](#jdbc-v3-driver-system-requirements)
+ [

## Considerations and limitations
](#jdbc-v3-driver-considerations-and-limitations)
+ [

## JDBC 3.x driver download
](#jdbc-v3-driver-download)
+ [

## Trusted identity propagation with JDBC
](#jdbc-v3-driver-trusted-identity)
+ [

# Get started with the JDBC 3.x driver
](jdbc-v3-driver-getting-started.md)
+ [

# Amazon Athena JDBC 3.x connection parameters
](jdbc-v3-driver-connection-parameters.md)
+ [

# Other JDBC 3.x configuration
](jdbc-v3-driver-other-configuration.md)
+ [

# Amazon Athena JDBC 3.x release notes
](jdbc-v3-driver-release-notes.md)
+ [

# Previous versions of the Athena JDBC 3.x driver
](jdbc-v3-driver-previous-versions.md)

# Get started with the JDBC 3.x driver
<a name="jdbc-v3-driver-getting-started"></a>

Use the information in this section to get started with the Amazon Athena JDBC 3.x driver.

**Topics**
+ [

## Installation Instructions
](#jdbc-v3-driver-installation-instructions)
+ [

## Running the driver
](#jdbc-v3-driver-running-the-driver)
+ [

## Configuring the driver
](#jdbc-v3-driver-configuring-the-driver)
+ [

## Upgrading from the Athena JDBC v2 driver
](#jdbc-v3-driver-upgrading-from-the-athena-jdbc-v2-driver-to-v3)

## Installation Instructions
<a name="jdbc-v3-driver-installation-instructions"></a>

You can use the JDBC 3.x driver in custom application or from a third-party SQL client.

### In a custom application
<a name="jdbc-v3-driver-installation-in-a-custom-application"></a>

Download the `.zip` file that contains the driver jar and its dependencies. Each dependency has its own `.jar` file. Add the driver jar as a dependency in your custom application. Selectively add the dependencies of the driver jar based on whether you have already added those dependencies to your application from another source.

### In a third-party SQL client
<a name="jdbc-v3-driver-installation-in-a-third-party-sql-client"></a>

Download the driver uber jar file and add it to the third-party SQL client following the instructions for that client.

## Running the driver
<a name="jdbc-v3-driver-running-the-driver"></a>

To run the driver, you can use a custom application or a third-party SQL client.

### In a custom application
<a name="jdbc-v3-driver-running-in-a-custom-application"></a>

Use the JDBC interface to interact with the JDBC driver from a program. The following code shows a sample custom Java application.

```
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
}
```

### In a third-party SQL client
<a name="jdbc-v3-driver-running-in-a-third-party-sql-client"></a>

Follow the documentation for the SQL client that you are using. Typically, you use the SQL client's graphical user interface to enter and submit the query, and the query results are displayed in the same interface.

## Configuring the driver
<a name="jdbc-v3-driver-configuring-the-driver"></a>

You can use connection parameters to configure the Amazon Athena JDBC driver. For supported connection parameters, see [Amazon Athena JDBC 3.x connection parameters](jdbc-v3-driver-connection-parameters.md).

### In a custom application
<a name="jdbc-v3-driver-configuring-in-a-custom-application"></a>

To set the connection parameters for the JDBC driver in a custom application, do one of the following:
+ Add the parameter names and their values to a `Properties` object. When you call `Connection#connect`, pass that object along with the URL. For an example, see the sample Java application in [Running the driver](#jdbc-v3-driver-running-the-driver).
+ In the connection string (the URL), use the following format to add the parameter names and their values directly after the protocol prefix.

  ```
  <parameterName>=<parameterValue>;
  ```

  Use a semi-colon at the end of each parameter name/parameter value pair, and leave no white space after the semicolon, as in the following example.

  ```
  String url = "jdbc:athena://WorkGroup=primary;Region=us-east-1;...;";AthenaDriver driver = new AthenaDriver();Connection connection = driver.connect(url, null);
  ```
**Note**  
If a parameter is specified both in the connection string and in the `Properties` object, the value in the connection string takes precedence. Specifying the same parameter in both places is not recommended.
+ Add the parameter values as arguments to the methods of `AthenaDataSource`, as in the following example.

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

### In a third-party SQL client
<a name="jdbc-v3-driver-configuring-in-a-third-party-sql-client"></a>

Follow the instructions of the SQL client that you are using. Typically, the client provides a graphical user interface to input the parameter names and their values.

## Upgrading from the Athena JDBC v2 driver
<a name="jdbc-v3-driver-upgrading-from-the-athena-jdbc-v2-driver-to-v3"></a>

Most of the JDBC version 3 connection parameters are backwards-compatible with the version 2 (Simba) JDBC driver. This means that a version 2 connection string can be reused with version 3 of the driver. However, some connection parameters have changed. These changes are described here. When you upgrade to the version 3 JDBC driver, update your existing configuration if necessary.

### Driver class
<a name="jdbc-v3-driver-upgrading-driver-class"></a>

Some BI tools ask you to provide the driver class from the JDBC driver `.jar` file. Most tools find this class automatically. The fully qualified name of the class in the version 3 driver is `com.amazon.athena.jdbc.AthenaDriver`. In the version 2 driver, the class was `com.simba.athena.jdbc.Driver`.

### Connection string
<a name="jdbc-v3-driver-upgrading-connection-string"></a>

The version 3 driver uses `jdbc:athena://` for the protocol at the beginning of the JDBC connection string URL. The version 3 driver also supports the version 2 protocol `jdbc:awsathena://`, but the use of the version 2 protocol is deprecated. To avoid undefined behaviors, version 3 does not accept connection strings that start with `jdbc:awsathena://` if version 2 (or any other driver that accepts connection strings that start with `jdbc:awsathena://`) has been registered with the [DriverManager](https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html) class.

### Credentials providers
<a name="jdbc-v3-driver-upgrading-credentials-providers"></a>

The version 2 driver uses fully qualified names to identify different credentials providers (for example, `com.simba.athena.amazonaws.auth.DefaultAWSCredentialsProviderChain`. The version 3 driver uses shorter names (for example, `DefaultChain`). The new names are described in the corresponding sections for each credentials provider.

Custom credentials providers written for the version 2 driver need to be modified for the version 3 driver to implement the [AwsCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/AwsCredentialsProvider.html) interface from the new AWS SDK for Java instead of the [AWSCredentialsProvider](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/AWSCredentialsProvider.html) interface from the previous AWS SDK for Java.

The `PropertiesFileCredentialsProvider` is not supported in the JDBC 3.x driver. The provider was used in the JDBC 2.x driver but belongs to the previous version of the AWS SDK for Java which is approaching end of support. To achieve the same functionality in the JDBC 3.x driver, use the [AWS configuration profile credentials](jdbc-v3-driver-aws-configuration-profile-credentials.md) provider instead.

### Log level
<a name="jdbc-v3-driver-upgrading-log-level"></a>

The following table shows the differences in the `LogLevel` parameters in the JDBC version 2 and version 3 drivers.


****  

| JDBC driver version | Parameter name | Parameter type | Default value | Possible values | Connection string example | 
| --- | --- | --- | --- | --- | --- | 
| v2 | LogLevel | Optional | 0 | 0-6 | LogLevel=6; | 
| v3 | LogLevel | Optional | TRACE | OFF, ERROR, WARN, INFO, DEBUG, TRACE | LogLevel=INFO; | 

### Query ID retrieval
<a name="jdbc-v3-driver-upgrading-query-id-retrieval"></a>

In the version 2 driver, you unwrap a `Statement` instance to `com.interfaces.core.IStatementQueryInfoProvider`, an interface that has two methods: `#getPReparedQueryId` and `#getQueryId`. You can use these methods to obtain the query execution ID of a query that has run.

In the version 3 driver, you unwrap `Statement`, `PreparedStatement`, and `ResultSet` instances to the `com.amazon.athena.jdbc.AthenaResultSet` interface. The interface has one method: `#getQueryExecutionId`.

# Amazon Athena JDBC 3.x connection parameters
<a name="jdbc-v3-driver-connection-parameters"></a>

Supported connection parameters are divided here into three sections: [Basic connection parameters](jdbc-v3-driver-basic-connection-parameters.md), [Advanced connection parameters](jdbc-v3-driver-advanced-connection-parameters.md), and [Authentication connection parameters](jdbc-v3-driver-authentication-connection-parameters.md). The Advanced connection parameters and Authentication connection parameters sections have subsections that group related parameters together.

**Topics**
+ [

# Basic connection parameters
](jdbc-v3-driver-basic-connection-parameters.md)
+ [

# Advanced connection parameters
](jdbc-v3-driver-advanced-connection-parameters.md)
+ [

# Authentication connection parameters
](jdbc-v3-driver-authentication-connection-parameters.md)

# Basic connection parameters
<a name="jdbc-v3-driver-basic-connection-parameters"></a>

The following sections describe the basic connection parameters for the JDBC 3.x driver.

## Region
<a name="jdbc-v3-driver-region"></a>

The AWS Region where queries will be run. For a list of regions, see [Amazon Athena endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/athena.html).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| Region | AwsRegion (deprecated) | Mandatory (but if not provided, will be searched using the [DefaultAwsRegionProviderChain](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/regions/providers/DefaultAwsRegionProviderChain.html))  | none | 

## Catalog
<a name="jdbc-v3-driver-catalog"></a>

The catalog that contains the databases and the tables that will be accessed with the driver. For information about catalogs, see [DataCatalog](https://docs.aws.amazon.com/athena/latest/APIReference/API_DataCatalog.html).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| Catalog | none | Optional | AwsDataCatalog | 

## Database
<a name="jdbc-v3-driver-database"></a>

The database where queries will run. Tables that are not explicitly qualified with a database name are resolved to this database. For information about databases, see [Database](https://docs.aws.amazon.com/athena/latest/APIReference/API_Database.html).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| Database | Schema | Optional | default | 

## Workgroup
<a name="jdbc-v3-driver-workgroup"></a>

The workgroup in which queries will run. For information about workgroups, see [WorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| WorkGroup | none | Optional | primary | 

## Output location
<a name="jdbc-v3-driver-output-location"></a>

The location in Amazon S3 where query results will be stored. For information about output location, see [ResultConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultConfiguration.html).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| OutputLocation | S3OutputLocation (deprecated) | Mandatory (unless the workgroup specifies an output location) | none | 

# Advanced connection parameters
<a name="jdbc-v3-driver-advanced-connection-parameters"></a>

The following sections describe the advanced connection parameters for the JDBC 3.x driver.

**Topics**
+ [

## Result encryption parameters
](#jdbc-v3-driver-result-encryption-parameters)
+ [

## Result fetching parameters
](#jdbc-v3-driver-result-fetching-parameters)
+ [

## Result configuration parameters
](#jdbc-v3-driver-result-config)
+ [

## Query result reuse parameters
](#jdbc-v3-driver-query-result-reuse-parameters)
+ [

## Query execution polling parameters
](#jdbc-v3-driver-query-execution-polling-parameters)
+ [

## Endpoint override parameters
](#jdbc-v3-driver-endpoint-override-parameters)
+ [

## Proxy configuration parameters
](#jdbc-v3-driver-proxy-configuration-parameters)
+ [

## Logging parameters
](#jdbc-v3-driver-logging-parameters)
+ [

## Application name
](#jdbc-v3-driver-application-name)
+ [

## Connection test
](#jdbc-v3-driver-connection-test)
+ [

## Number of retries
](#jdbc-v3-driver-number-of-retries)
+ [

## Network timeout
](#jdbc-v3-driver-networktimeoutmillis)

## Result encryption parameters
<a name="jdbc-v3-driver-result-encryption-parameters"></a>

Note the following points:
+ The AWS KMS Key must be specified when `EncryptionOption` is `SSE_KMS` or `CSE_KMS`.
+ The AWS KMS Key cannot be specified when `EncryptionOption` is not specified or when `EncryptionOption` is `SSE_S3`.

### Encryption option
<a name="jdbc-v3-driver-encryption-option"></a>

The type of encryption to be used for query results as they are stored in Amazon S3. For information about query result encryption, see [EncryptionConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EncryptionConfiguration.html) in the *Amazon Athena API Reference*.


****  

| Parameter name | Alias | Parameter type | Default value | Possible values | 
| --- | --- | --- | --- | --- | 
| EncryptionOption | S3OutputEncOption (deprecated) | Optional | none | SSE\$1S3, SSE\$1KMS, CSE\$1KMS | 

### KMS Key
<a name="jdbc-v3-driver-kms-key"></a>

The KMS key ARN or ID, if `SSE_KMS` or `CSE_KMS` is chosen as the encryption option. For more information, see [EncryptionConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EncryptionConfiguration.html) in the *Amazon Athena API Reference*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| KmsKey | S3OutputEncKMSKey (deprecated) | Optional | none | 

## Result fetching parameters
<a name="jdbc-v3-driver-result-fetching-parameters"></a>

### Result fetcher
<a name="jdbc-v3-driver-result-fetcher"></a>

The fetcher that will be used to download query results.

The default result fetcher, `auto`, downloads query results directly from Amazon S3 without using the Athena APIs. When direct S3 download is not possible, like when query results are encrypted with the `CSE_KMS` option, it automatically falls back to use the `GetQueryResultsStream` API.

Using the `auto` fetcher is recommended in most situations. If your IAM policies, or S3 bucket policies use the [s3:CalledVia](security-iam-athena-calledvia.md) condition to limit access to S3 objects requests from Athena, the `auto` fetcher first attempts to download the results from S3 and then falls back to use the `GetQueryResultsStream` API. In this situation, you can set the ResultFetcher to `GetQueryResultsStream` to avoid an extra API call.


****  

| Parameter name | Alias | Parameter type | Default value | Possible values | 
| --- | --- | --- | --- | --- | 
| ResultFetcher | none | Optional | auto | auto, S3, GetQueryResults, GetQueryResultsStream | 

### Fetch size
<a name="jdbc-v3-driver-fetch-size"></a>

The value of this parameter is used as the minimum for internal buffers and as the target page size when fetching results. The value 0 (zero) means that the driver should use its defaults as described below. The maximum value is 1,000,000.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| FetchSize | RowsToFetchPerBlock (deprecated) | Optional | 0 | 
+ The `GetQueryResults` fetcher will always use a page size of 1,000, which is the maximum value supported by the API call. When the fetch size is higher than 1,000, multiple successive API calls are made to fill the buffer above the minimum.
+ The `GetQueryResultsStream` fetcher will use the configured fetch size as the page size, or 10,000 by default.
+ The `S3` fetcher will use the configured fetch size as the page size, or 10,000 by default.

## Result configuration parameters
<a name="jdbc-v3-driver-result-config"></a>

### Expected bucket owner
<a name="jdbc-v3-driver-exp-bucket-owner"></a>

The account ID of the expected s3 bucket owner. If the account ID that you provide does not match the actual owner of the bucket, the request fails. For more information about verifying s3 bucket owner, see [Verifying bucket ownership](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-owner-condition.html#bucket-owner-condition-use).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| ExpectedBucketOwner | none | Optional | none | 

### Acl option
<a name="jdbc-v3-driver-acl"></a>

Indicates that an Amazon S3 canned ACL should be set to control ownership of stored query results. For more information about `AclOption`, see [AclConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_AclConfiguration.html).


****  

| Parameter name | Alias | Parameter type | Default value | Possible values | 
| --- | --- | --- | --- | --- | 
| AclOption | none | Optional | none | BUCKET\$1OWNER\$1FULL\$1CONTROL | 

## Query result reuse parameters
<a name="jdbc-v3-driver-query-result-reuse-parameters"></a>

### Enable result reuse
<a name="jdbc-v3-driver-enable-result-reuse"></a>

Specifies whether previous results for the same query can be reused when a query is run. For information about query result reuse, see [ResultReuseByAgeConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultReuseByAgeConfiguration.html).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| EnableResultReuseByAge | none | Optional | FALSE | 

### Result reuse max age
<a name="jdbc-v3-driver-result-reuse-max-age"></a>

The maximum age, in minutes, of a previous query result that Athena should consider for reuse. For information about result reuse max age, see [ResultReuseByAgeConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultReuseByAgeConfiguration.html).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| MaxResultReuseAgeInMinutes | none | Optional | 60 | 

## Query execution polling parameters
<a name="jdbc-v3-driver-query-execution-polling-parameters"></a>

### Minimum query execution polling interval
<a name="jdbc-v3-driver-minimum-query-execution-polling-interval"></a>

The minimum time, in milliseconds, to wait before polling Athena for the query execution status.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| MinQueryExecutionPollingIntervalMillis | MinQueryExecutionPollingInterval (deprecated) | Optional | 100 | 

### Maximum query execution polling interval
<a name="jdbc-v3-driver-maximum-query-execution-polling-interval"></a>

The maximum time, in milliseconds, to wait before polling Athena for the query execution status.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| MaxQueryExecutionPollingIntervalMillis | MaxQueryExecutionPollingInterval (deprecated) | Optional | 5000 | 

### Query execution polling interval multiplier
<a name="jdbc-v3-driver-query-execution-polling-interval-multiplier"></a>

The factor for increasing the polling period. By default, polling will begin with the value for `MinQueryExecutionPollingIntervalMillis` and double with each poll until it reaches the value for `MaxQueryExecutionPollingIntervalMillis`.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| QueryExecutionPollingIntervalMultiplier | none | Optional | 2 | 

## Endpoint override parameters
<a name="jdbc-v3-driver-endpoint-override-parameters"></a>

### Athena endpoint override
<a name="jdbc-v3-driver-athena-endpoint-override"></a>

The endpoint that the driver will use to make API calls to Athena.

Note the following points:
+ If the `https://` or `http://` protocols are not specified in the provided URL, the driver inserts the `https://` prefix.
+ If this parameter is not specified, the driver uses a default endpoint.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| AthenaEndpoint | EndpointOverride (deprecated) | Optional | none | 

### Athena streaming service endpoint override
<a name="jdbc-v3-driver-athena-streaming-service-endpoint-override"></a>

The endpoint that the driver will use to download query results when it uses the Athena streaming service. The Athena streaming service is available on port 444.

Note the following points:
+ If the `https://` or `http://` protocols are not specified in the provided URL, the driver inserts the `https://` prefix.
+ If a port is not specified in the provided URL, the driver inserts the streaming service port 444.
+ If the `AthenaStreamingEndpoint` parameter is not specified, the driver uses the `AthenaEndpoint` override. If neither the `AthenaStreamingEndpoint` nor the `AthenaEndpoint` override is specified, the driver uses a default streaming endpoint.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| AthenaStreamingEndpoint | StreamingEndpointOverride (deprecated) | Optional | none | 

### LakeFormation endpoint override
<a name="jdbc-v3-driver-athena-lake-formation-endpoint-override"></a>

The endpoint that the driver will use for the Lake Formation service when using the AWS Lake Formation [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) API to retrieve temporary credentials. If this parameter is not specified, the driver uses a default Lake Formation endpoint.

Note the following points:
+ If the `https://` or `http://` protocols are not specified in the provided URL, the driver inserts the `https://` prefix.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| LakeFormationEndpoint |  LfEndpointOverride (deprecated)  | Optional | none | 

### S3 endpoint override
<a name="jdbc-v3-driver-athena-s3-endpoint-override"></a>

The endpoint that the driver will use to download query results when it uses the Amazon S3 fetcher. If this parameter is not specified, the driver uses a default Amazon S3 endpoint.

Note the following points:
+ If the `https://` or `http://` protocols are not specified in the provided URL, the driver inserts the `https://` prefix.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| S3Endpoint | None | Optional | none | 

### STS endpoint override
<a name="jdbc-v3-driver-athena-sts-endpoint-override"></a>

The endpoint that the driver will use for the AWS STS service when using the AWS STS [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) API to retrieve temporary credentials. If this parameter is not specified, the driver uses a default AWS STS endpoint.

Note the following points:
+ If the `https://` or `http://` protocols are not specified in the provided URL, the driver inserts the `https://` prefix.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| StsEndpoint | StsEndpointOverride(deprecated) | Optional | none | 

### SSO OIDC endpoint override
<a name="jdbc-v3-driver-athena-sso-oidc-endpoint-override"></a>

The endpoint that the driver will use when using `ClientConfiguration.endpointOverride` to override the default HTTP endpoint for SSO OIDC client. For more information, see [ClientConfiguration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| SSOOIDCEndpointOverride |  | Optional | none | 

### SSO Admin endpoint override
<a name="jdbc-v3-driver-athena-sso-admin-endpoint-override"></a>

The endpoint that the driver will use when using `ClientConfiguration.endpointOverride` to override the default HTTP endpoint for SSO Admin client. For more information, see [ClientConfiguration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| SSOAdminEndpointOverride |  | Optional | none | 

## Proxy configuration parameters
<a name="jdbc-v3-driver-proxy-configuration-parameters"></a>

### Proxy host
<a name="jdbc-v3-driver-proxy-host"></a>

The URL of the proxy host. Use this parameter if you require Athena requests to go through a proxy.

**Note**  
 Make sure to include the protocol `https://` or `http://` at the beginning of the URL for `ProxyHost`. 


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| ProxyHost | none | Optional | none | 

### Proxy port
<a name="jdbc-v3-driver-proxy-port"></a>

The port to be used on the proxy host. Use this parameter if you require Athena requests to go through a proxy.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| ProxyPort | none | Optional | none | 

### Proxy username
<a name="jdbc-v3-driver-proxy-username"></a>

The username to authenticate on the proxy server. Use this parameter if you require Athena requests to go through a proxy.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| ProxyUsername | ProxyUID (deprecated) | Optional | none | 

### Proxy password
<a name="jdbc-v3-driver-proxy-password"></a>

The password to authenticate on the proxy server. Use this parameter if you require Athena requests to go through a proxy.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| ProxyPassword | ProxyPWD (deprecated) | Optional | none | 

### Proxy-exempt hosts
<a name="jdbc-v3-driver-proxy-exempt-hosts"></a>

A set of host names that the driver connects to without using a proxy when proxying is enabled (that is, when the `ProxyHost` and `ProxyPort` connection parameters are set). The hosts should be separated by the pipe (`|`) character (for example, `host1.com|host2.com`).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| ProxyExemptHosts | NonProxyHosts | Optional | none | 

### Proxy enabled for identity providers
<a name="jdbc-v3-driver-proxy-enabled-for-identity-providers"></a>

Specifies whether a proxy should be used when the driver connects to an identity provider.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| ProxyEnabledForIdP | UseProxyForIdP | Optional | FALSE | 

## Logging parameters
<a name="jdbc-v3-driver-logging-parameters"></a>

This section describes parameters related to logging.

### Log level
<a name="jdbc-v3-driver-logging-parameters-log-level"></a>

Specifies the level for the driver logging. Nothing is logged unless the `LogPath` parameter is also set.

**Note**  
We recommend setting only the `LogPath` parameter unless you have special requirements. Setting only the `LogPath` parameter enables logging and uses the default `TRACE` log level. The `TRACE` log level provides the most detailed logging.


****  

| Parameter name | Alias | Parameter type | Default value | Possible values | 
| --- | --- | --- | --- | --- | 
| LogLevel | none | Optional | TRACE | OFF, ERROR, WARN, INFO, DEBUG, TRACE | 

### Log path
<a name="jdbc-v3-driver-logging-parameters-log-path"></a>

The path to a directory on the computer that runs the driver where driver logs will be stored. A log file with a unique name will be created within the specified directory. If set, enables driver logging.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| LogPath | none | Optional | none | 

## Application name
<a name="jdbc-v3-driver-application-name"></a>

The name of the application that uses the driver. If a value for this parameter is specified, the value is included in the user agent string of the API calls that the driver makes to Athena.

**Note**  
You can also set the application name by calling `setApplicationName` on the `DataSource` object.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| ApplicationName | none | Optional | none | 

## Connection test
<a name="jdbc-v3-driver-connection-test"></a>

If set to `TRUE`, the driver performs a connection test each time a JDBC connection is created, even if a query is not executed on the connection.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| ConnectionTest | none | Optional | TRUE | 

**Note**  
A connection test submits a `SELECT 1` query to Athena to verify that the connection has been configured correctly. This means that two files will be stored in Amazon S3 (the result set and metadata), and additional charges can apply in accordance with the [Amazon Athena pricing](https://aws.amazon.com/athena/pricing) policy.

## Number of retries
<a name="jdbc-v3-driver-number-of-retries"></a>

The maximum number of times the driver should resend a retriable request to Athena.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| NumRetries | MaxErrorRetry (deprecated) | Optional | none | 

## Network timeout
<a name="jdbc-v3-driver-networktimeoutmillis"></a>

The network timeout controls the amount of time that the driver waits for a network connection to be established. This includes the time it takes to send API requests. In rare circumstances, it may be useful to change the network timeout. For example, you might want to increase the timeout for long garbage collection pauses. Setting this connection parameter is equivalent to using the `setNetworkTimeout` method on a `Connection` object.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
|  NetworkTimeoutMillis  | none | Optional | none | 

# Authentication connection parameters
<a name="jdbc-v3-driver-authentication-connection-parameters"></a>

The Athena JDBC 3.x driver supports several authentication methods. The connection parameters that are required depend on the authentication method that you use.

**Topics**
+ [IAM](jdbc-v3-driver-iam-credentials.md)
+ [Default](jdbc-v3-driver-default-credentials.md)
+ [AWS configuration profile](jdbc-v3-driver-aws-configuration-profile-credentials.md)
+ [Instance profile](jdbc-v3-driver-instance-profile-credentials.md)
+ [Custom](jdbc-v3-driver-custom-credentials.md)
+ [JWT](jdbc-v3-driver-jwt-credentials.md)
+ [JWT trusted identity propagation](jdbc-v3-driver-jwt-tip-credentials.md)
+ [Browser trusted identity propagation](jdbc-v3-driver-browser-oidc-tip-credentials.md)
+ [Azure AD](jdbc-v3-driver-azure-ad-credentials.md)
+ [Okta](jdbc-v3-driver-okta-credentials.md)
+ [Ping](jdbc-v3-driver-ping-credentials.md)
+ [AD FS](jdbc-v3-driver-adfs-credentials.md)
+ [Browser Azure AD](jdbc-v3-driver-browser-azure-ad-credentials.md)
+ [Browser SAML](jdbc-v3-driver-browser-saml-credentials.md)
+ [DataZone IdC](jdbc-v3-driver-datazone-idc.md)
+ [DataZone IAM](jdbc-v3-driver-datazone-iamcp.md)

# IAM credentials
<a name="jdbc-v3-driver-iam-credentials"></a>

You can use your IAM credentials with the JDBC driver to connect to Amazon Athena by setting the following connection parameters.

## User
<a name="jdbc-v3-driver-user"></a>

Your AWS access key ID. For information about access keys, see [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html) in the *IAM User Guide*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| User | AccessKeyId | Required | none | 

## Password
<a name="jdbc-v3-driver-password"></a>

Your AWS secret key ID. For information about access keys, see [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html) in the *IAM User Guide*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| Password | SecretAccessKey | Optional | none | 

## Session token
<a name="jdbc-v3-driver-session-token"></a>

If you use temporary AWS credentials, you must specify a session token. For information about temporary credentials, see [Temporary security credentials in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) in the *IAM User Guide*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| SessionToken | none | Optional | none | 

# Default credentials
<a name="jdbc-v3-driver-default-credentials"></a>

You can use the default credentials that you configure on your client system to connect to Amazon Athena by setting the following connection parameters. For information about using default credentials, see [Using the Default Credential Provider Chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default) in the *AWS SDK for Java Developer Guide*.

## Credentials provider
<a name="jdbc-v3-driver-credentials-provider"></a>

The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `DefaultChain`.


****  

| Parameter name | Alias | Parameter type | Default value | Value to use | 
| --- | --- | --- | --- | --- | 
| CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | DefaultChain | 

# AWS configuration profile credentials
<a name="jdbc-v3-driver-aws-configuration-profile-credentials"></a>

You can use credentials stored in an AWS configuration profile by setting the following connection parameters. AWS configuration profiles are typically stored in files in the `~/.aws` directory). For information about AWS configuration profiles, see [Use profiles](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-profiles.html) in the *AWS SDK for Java Developer Guide*.

## Credentials provider
<a name="jdbc-v3-driver-aws-configuration-profile-credentials-provider"></a>

The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `ProfileCredentials`.


****  

| Parameter name | Alias | Parameter type | Default value | Value to use | 
| --- | --- | --- | --- | --- | 
| CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | ProfileCredentials | 

## Profile name
<a name="jdbc-v3-driver-profile-name"></a>

The name of the AWS configuration profile whose credentials should be used to authenticate the request to Athena.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| ProfileName | none | Required | none | 

**Note**  
The profile name can also be specified as the value of the `CredentialsProviderArguments` parameter, although this use is deprecated.

# Instance profile credentials
<a name="jdbc-v3-driver-instance-profile-credentials"></a>

This authentication type is used on Amazon EC2 instances. An *instance profile* is a profile attached to an Amazon EC2 instance. Using an instance profile credentials provider delegates the management of AWS credentials to the Amazon EC2 Instance Metadata Service. This removes the need for developers to store credentials permanently on the Amazon EC2 instance or worry about rotating or managing temporary credentials.

## Credentials provider
<a name="jdbc-v3-driver-instance-profile-credentials-provider"></a>

The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `InstanceProfile`.


****  

| Parameter name | Alias | Parameter type | Default value | Value to use | 
| --- | --- | --- | --- | --- | 
| CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | InstanceProfile | 

# Custom credentials
<a name="jdbc-v3-driver-custom-credentials"></a>

You can use this authentication type to provide your own credentials by using a Java class that implements the [AwsCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/AwsCredentialsProvider.html) interface.

## Credentials provider
<a name="jdbc-v3-driver-custom-credentials-credentials-provider"></a>

The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to the fully qualified class name of the custom class that implements the [AwsCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/AwsCredentialsProvider.html) interface. At runtime, that class must be on the Java class path of the application that uses the JDBC driver.


****  

| Parameter name | Alias | Parameter type | Default value | Value to use | 
| --- | --- | --- | --- | --- | 
| CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | The fully qualified class name of the custom implementation of AwsCredentialsProvider | 

## Credentials provider arguments
<a name="jdbc-v3-driver-credentials-provider-arguments"></a>

A comma-separated list of string arguments for the custom credentials provider constructor.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| CredentialsProviderArguments | AwsCredentialsProviderArguments (deprecated) | Optional | none | 

# JWT credentials
<a name="jdbc-v3-driver-jwt-credentials"></a>

With this authentication type, you can use a JSON web token (JWT) obtained from an external identity provider as a connection parameter to authenticate with Athena. The external credentials provider must already be federated with AWS.

## Credentials provider
<a name="jdbc-v3-driver-jwt-credentials-provider"></a>

The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `JWT`.


****  

| Parameter name | Alias | Parameter type | Default value | Value to use | 
| --- | --- | --- | --- | --- | 
| CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | JWT | 

## JWT web identity token
<a name="jdbc-v3-driver-jwt-web-identity-token"></a>

The JWT token obtained from an external federated identity provider. This token will be used to authenticate with Athena.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| JwtWebIdentityToken | web\$1identity\$1token (deprecated) | Required | none | 

## JWT role ARN
<a name="jdbc-v3-driver-jwt-role-arn"></a>

The Amazon Resource Name (ARN) of the role to assume. For information about assuming roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| JwtRoleArn | role\$1arn (deprecated) | Required | none | 

## JWT role session name
<a name="jdbc-v3-driver-jwt-role-session-name"></a>

The name of the session when you use JWT credentials for authentication. The name can be any name that you choose.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| JwtRoleSessionName | role\$1session\$1name (deprecated) | Required | none | 

## Role session duration
<a name="jdbc-v3-driver-jwt-role-session-duration"></a>

The duration, in seconds, of the role session. For more information, see [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) in the *AWS Security Token Service API Reference*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| RoleSessionDuration | Duration (deprecated) | Optional | 3600 | 

# JWT with identity center integration
<a name="jdbc-v3-driver-jwt-tip-credentials"></a>

This authentication type allows you to use a JSON web token (JWT) obtained from an external identity provider as a connection parameter to authenticate with Athena. You can use this plugin, to enable support for corporate identities via trusted identity propagation. For more information on how to use trusted identity propagation with drivers, see [Use Trusted identity propagation with Amazon Athena drivers](using-trusted-identity-propagation.md). You can also [configure and deploy resources using CloudFormation](using-trusted-identity-propagation-cloudformation.md).

With trusted identity propagation, identity context is added to an IAM role to identify the user requesting access to AWS resources. For information on enabling and using trusted identity propagation, see [What is trusted identity propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation.html).

## Credentials provider
<a name="jdbc-v3-driver-jwt-tip-credentials-provider"></a>

The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `JWT_TIP`.


****  

| Parameter name | Alias | Parameter type | Default value | Value to use | 
| --- | --- | --- | --- | --- | 
| CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | JWT\$1TIP | 

## JWT web identity token
<a name="jdbc-v3-driver-jwt-tip-web-identity-token"></a>

The JWT token obtained from an external federated identity provider. This token will be used to authenticate with Athena. Token Caching is enabled by default and allows the same Identity Center access token to be used across driver connections. We recommend to provide a fresh JWT token upon "Testing Connection" as the exchanged token is present only during driver instance is active.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| JwtWebIdentityToken | web\$1identity\$1token (deprecated) | Required | none | 

## WorkgroupArn
<a name="jdbc-v3-driver-jwt-tip-workgroup-arn"></a>

The Amazon Resource Name (ARN) of the Amazon Athena workgroup. For more information about workgroups, see [WorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| WorkGroupArn | none | Required | primary | 

## JWT application role ARN
<a name="jdbc-v3-driver-jwt-tip-application-role-arn"></a>

The ARN of the role to assume. This role is used for JWT exchange, getting IAM Identity Center customer managed application ARN through workgroup tags, and getting access role ARN. For more information about assuming roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| ApplicationRoleArn | none | Required | none | 

## JWT role session name
<a name="jdbc-v3-driver-jwt-tip-role-session-name"></a>

The name of the session when authenticating with JWT credentials. It can be any name of your choice.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| JwtRoleSessionName | role\$1session\$1name (deprecated) | Required | none | 

## Role session duration
<a name="jdbc-v3-driver-jwt-tip-session-duration"></a>

The duration, in seconds, of the role session. For more information, see [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| RoleSessionDuration | Duration (deprecated) | Optional | 3600 | 

## JWT access role ARN
<a name="jdbc-v3-driver-jwt-tip-access-role-arn"></a>

The ARN of the role to assume. This is the role assumed by the Athena service to make calls on the behalf of you. For more information about assuming roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| AccessRoleArn | none | Optional | none | 

## IAM Identity Center customer managed application ARN
<a name="jdbc-v3-driver-jwt-tip-customer-idc-application-arn"></a>

The ARN of IAM Identity Center customer managed application. For more information, see [customer managed applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps.html).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| CustomerIdcApplicationArn | none | Optional | none | 

# Browser based with identity center integration
<a name="jdbc-v3-driver-browser-oidc-tip-credentials"></a>

This authentication type allows you to fetch a new JSON web token (JWT) from an external identity provider and authenticate with Athena. You can use this plugin, to enable support for corporate identities via trusted identity propagation. For more information on how to use trusted identity propagation with drivers, see [Use Trusted identity propagation with Amazon Athena drivers](using-trusted-identity-propagation.md). You can also [configure and deploy resources using CloudFormation](using-trusted-identity-propagation-cloudformation.md).

With trusted identity propagation, identity context is added to an IAM role to identify the user requesting access to AWS resources. For information on enabling and using trusted identity propagation, see [What is trusted identity propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation.html).

**Note**  
The plugin is specifically designed for single-user desktop environments. In shared environments like Windows Server, system administrators are responsible for establishing and maintaining security boundaries between users.

## Credentials provider
<a name="jdbc-v3-driver-browser-oidc-tip-credentials-provider"></a>

The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `BrowserOidcTip`.


****  

| Parameter name | Alias | Parameter type | Default value | Value to use | 
| --- | --- | --- | --- | --- | 
| CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | BrowserOidcTip | 

## Idp well known configuration URL
<a name="jdbc-v3-driver-browser-oidc-tip-idp-well-known-config"></a>

The IDP Well Known Configuration URL is the endpoint that provides OpenID Connect configuration details for your identity provider. This URL typically ends with `.well-known/openid-configuration` and contains essential metadata about the authentication endpoints, supported features, and token signing keys. For example, if you're using *Okta*, the URL might look like `https://your-domain.okta.com/.well-known/openid-configuration`.

For troubleshooting: If you receive connection errors, verify that this URL is accessible from your network and returns valid *OpenID Connect* configuration JSON. The URL must be reachable by the client where the driver is installed and should be provided by your identity provider administrator.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| IdpWellKnownConfigurationUrl | none | Required | none | 

## Client identifier
<a name="jdbc-v3-driver-browser-oidc-tip-client-id"></a>

The client identifier issued to the application by the OpenID Connect provider.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| OidcClientId | none | Required | none | 

## WorkgroupArn
<a name="jdbc-v3-driver-browser-oidc-tip-workgroup-arn"></a>

The Amazon Resource Name (ARN) of the Amazon Athena workgroup that contains the trusted identity propagation configuration tags. For more information about workgroups, see [WorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html). 

**Note**  
This parameter is different from the `Workgroup` parameter that specifies where queries will run. You must set both parameters:  
`WorkgroupArn` - Points to the workgroup containing the trusted identity propagation configuration tags
`Workgroup` - Specifies the workgroup where queries will execute
While these typically reference the same workgroup, both parameters must be set explicitly for proper operation.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| WorkGroupArn | none | Required | primary | 

## JWT application role ARN
<a name="jdbc-v3-driver-browser-oidc-tip-application-role-arn"></a>

The ARN of the role that will be assumed in the JWT exchange. This role is used for JWT exchange, getting IAM Identity Center customer managed application ARN through workgroup tags, and getting access role ARN. For more information about assuming roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html). 


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| ApplicationRoleArn | none | Required | none | 

## JWT role session name
<a name="jdbc-v3-driver-browser-oidc-tip-role-session-name"></a>

A name for the IAM session. It can be anything you like, but typically you pass the name or identifier that's associated with the user who is using your application. That way, the temporary security credentials that your application will use are associated with that user. 


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| JwtRoleSessionName | role\$1session\$1name (deprecated) | Required | none | 

## Client secret
<a name="jdbc-v3-driver-browser-oidc-tip-client-secret"></a>

The clientSecret is a confidential key issued by your identity provider that is used to authenticate your application (client). While this parameter is optional and may not be required for all authentication flows, it provides an additional layer of security when used. If your IDP configuration requires a client secret, you must include this parameter with the value provided by your identity provider administrator.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| OidcClientSecret | none | Optional | none | 

## Scope
<a name="jdbc-v3-driver-browser-oidc-tip-scope"></a>

The scope specifies what level of access your application is requesting from the identity provider. You must include `openid` in the scope to receive an ID token containing essential user identity claims. Your scope may need to include additional permissions like `email` or `profile`, depending on which user claims your identity provider (such as *Microsoft Entra ID*) is configured to include in the ID token. These claims are essential for proper *Trusted Identity Propagation* mapping. If user identity mapping fails, verify that your scope includes all necessary permissions and your identity provider is configured to include the required claims in the ID token. These claims must match your *Trusted Token Issuer* mapping configuration in IAM Identity Center. 


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| Scope | none | Optional | openid email offline\$1access | 

## Role session duration
<a name="jdbc-v3-driver-browser-oidc-tip-role-session-duration"></a>

The duration, in seconds, of the role session. For more information, see [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| RoleSessionDuration | Duration (deprecated) | Optional | 3600 | 

## JWT access role ARN
<a name="jdbc-v3-driver-browser-oidc-tip-access-role-arn"></a>

The ARN of the role that Athena assumes to make calls on the behalf of you. For more information about assuming roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. 


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| AccessRoleArn | none | Optional | none | 

## IAM Identity Center customer managed application ARN
<a name="jdbc-v3-driver-browser-oidc-tip-customer-idc-application-arn"></a>

The ARN of IAM Identity Center customer managed application. For more information, see [customer managed applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps.html).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| CustomerIdcApplicationArn | none | Optional | none | 

## Identity provider port number
<a name="jdbc-v3-driver-browser-oidc-tip-idp-port-number"></a>

The local port number to use for the OAuth 2.0 callback server. This is used as redirect\$1uri and you will need to allowlist this in your IDP application. The default generated redirect\$1uri is: http://localhost:7890/athena

**Warning**  
In shared environments like Windows Terminal Servers or Remote Desktop Services, the loopback port (default: 7890) is shared among all users on the same machine. System administrators can mitigate potential port hijacking risks by:  
Configuring different port numbers for different user groups
Using Windows security policies to restrict port access
Implementing network isolation between user sessions
If these security controls cannot be implemented, we recommend using the [JWT trusted identity propagation](jdbc-v3-driver-jwt-tip-credentials.md) plugin instead, which doesn't require a loopback port.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| IdpPortNumber | none | Optional | 7890 | 

## Identity provider response timeout
<a name="jdbc-v3-driver-browser-oidc-tip-idp-response-timeout"></a>

The timeout in seconds to wait for the OAuth 2.0 callback response.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| IdpResponseTimeout | none | Optional | 120 | 

## Enable token caching
<a name="jdbc-v3-driver-browser-oidc-tip-enable-token-caching"></a>

The EnableTokenCaching parameter determines whether the driver caches the authentication token between conections. Setting EnableTokenCaching to true reduces authentication prompts and improves user experience, but should be used cautiously. This setting is best suited for single-user desktop environments. In shared environments like Windows Server, it's recommended to keep this disabled to prevent potential token sharing between users with similar connection strings. 

For enterprise deployments using tools like Tableau Server, we recommend using the [JWT trusted identity propagation](jdbc-v3-driver-jwt-tip-credentials.md) plugin instead of this authentication method. 


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| EnableTokenCaching | none | Optional | FALSE | 

# Azure AD credentials
<a name="jdbc-v3-driver-azure-ad-credentials"></a>

A SAML-based authentication mechanism that enables authentication to Athena using the Azure AD identity provider. This method assumes that a federation has already been set up between Athena and Azure AD.

**Note**  
Some of the parameter names in this section have aliases. The aliases are functional equivalents of the parameter names and have been provided for backward compatibility with the JDBC 2.x driver. Because the parameter names have been improved to follow a clearer, more consistent naming convention, we recommend that you use them instead of the aliases, which have been deprecated. 

## Credentials provider
<a name="jdbc-v3-driver-azure-ad-credentials-provider"></a>

The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `AzureAD`.


****  

| Parameter name | Alias | Parameter type | Default value | Value to use | 
| --- | --- | --- | --- | --- | 
| CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | AzureAD | 

## User
<a name="jdbc-v3-driver-azure-ad-user"></a>

The email address of the Azure AD user to use for authentication with Azure AD.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| User | UID (deprecated) | Required | none | 

## Password
<a name="jdbc-v3-driver-azure-ad-password"></a>

The password for the Azure AD user.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| Password | PWD (deprecated) | Required | none | 

## Azure AD tenant ID
<a name="jdbc-v3-driver-azure-ad-tenant-id"></a>

The tenant ID of your Azure AD application.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| AzureAdTenantId | tenant\$1id (deprecated) | Required | none | 

## Azure AD client ID
<a name="jdbc-v3-driver-azure-ad-client-id"></a>

The client ID of your Azure AD application.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| AzureAdClientId | client\$1id (deprecated) | Required | none | 

## Azure AD client secret
<a name="jdbc-v3-driver-azure-ad-client-secret"></a>

The client secret of your Azure AD application.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| AzureAdClientSecret | client\$1secret (deprecated) | Required | none | 

## Preferred role
<a name="jdbc-v3-driver-preferred-role"></a>

The Amazon Resource Name (ARN) of the role to assume. For information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| PreferredRole | preferred\$1role (deprecated) | Optional | none | 

## Role session duration
<a name="jdbc-v3-driver-role-session-duration"></a>

The duration, in seconds, of the role session. For more information, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| RoleSessionDuration | Duration (deprecated) | Optional | 3600 | 

## Lake Formation enabled
<a name="jdbc-v3-driver-lake-formation-enabled"></a>

Specifies whether to use the [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API action to retrieve temporary IAM credentials instead of the [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API action.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| LakeFormationEnabled | none | Optional | FALSE | 

# Okta credentials
<a name="jdbc-v3-driver-okta-credentials"></a>

A SAML-based authentication mechanism that enables authentication to Athena using the Okta identity provider. This method assumes that a federation has already been set up between Athena and Okta.

## Credentials provider
<a name="jdbc-v3-driver-okta-credentials-provider"></a>

The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `Okta`.


****  

| Parameter name | Alias | Parameter type | Default value | Value to use | 
| --- | --- | --- | --- | --- | 
| CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | Okta | 

## User
<a name="jdbc-v3-driver-okta-user"></a>

The email address of the Okta user to use for authentication with Okta.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| User | UID (deprecated) | Required | none | 

## Password
<a name="jdbc-v3-driver-okta-password"></a>

The password for the Okta user.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| Password | PWD (deprecated) | Required | none | 

## Okta host name
<a name="jdbc-v3-driver-okta-host-name"></a>

The URL for your Okta organization. You can extract the `idp_host` parameter from the **Embed Link** URL in your Okta application. For steps, see [Retrieve ODBC configuration information from Okta](odbc-okta-plugin.md#odbc-okta-plugin-retrieve-odbc-configuration-information-from-okta). The first segment after `https://`, up to and including `okta.com`, is your IdP host (for example, `trial-1234567.okta.com` for a URL that starts with `https://trial-1234567.okta.com`).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| OktaHostName | IdP\$1Host (deprecated) | Required | none | 

## Okta application ID
<a name="jdbc-v3-driver-okta-application-id"></a>

The two-part identifier for your application. You can extract the application ID from the **Embed Link** URL in your Okta application. For steps, see [Retrieve ODBC configuration information from Okta](odbc-okta-plugin.md#odbc-okta-plugin-retrieve-odbc-configuration-information-from-okta). The application ID is the last two segments of the URL, including the forward slash in the middle. The segments are two 20-character strings with a mix of numbers and upper and lowercase letters (for example, `Abc1de2fghi3J45kL678/abc1defghij2klmNo3p4`).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| OktaAppId | App\$1ID (deprecated) | Required | none | 

## Okta application name
<a name="jdbc-v3-driver-okta-application-name"></a>

The name of your Okta application.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| OktaAppName | App\$1Name (deprecated) | Required | none | 

## Okta MFA type
<a name="jdbc-v3-driver-okta-mfa-type"></a>

If you have set up Okta to require multi-factor authentication (MFA), you need to specify the Okta MFA type and additional parameters depending on the second factor that you want to use.

Okta MFA type is the second authentication factor type (after the password) to use to authenticate with Okta. Supported second factors include push notifications delivered through the Okta Verify app and temporary one-time passwords (TOTPs) generated by Okta Verify, Google Authenticator, or sent through SMS. Individual organization security policies determine whether or not MFA is required for user login.


****  

| Parameter name | Alias | Parameter type | Default value | Possible values | 
| --- | --- | --- | --- | --- | 
| OktaMfaType | okta\$1mfa\$1type (deprecated) | Required, if Okta is set up to require MFA | none | oktaverifywithpush, oktaverifywithtotp, googleauthenticator, smsauthentication | 

## Okta phone number
<a name="jdbc-v3-driver-okta-phone-number"></a>

The phone number to which Okta will send a temporary one-time password using SMS when the `smsauthentication` MFA type is chosen. The phone number must be a US or Canadian phone number.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| OktaPhoneNumber | okta\$1phone\$1number (deprecated) | Required, if OktaMfaType is smsauthentication | none | 

## Okta MFA wait time
<a name="jdbc-v3-driver-okta-mfa-wait-time"></a>

The duration, in seconds, to wait for the user to acknowledge a push notification from Okta before the driver throws a timeout exception.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| OktaMfaWaitTime | okta\$1mfa\$1wait\$1time (deprecated) | Optional | 60 | 

## Preferred role
<a name="jdbc-v3-driver-okta-preferred-role"></a>

The Amazon Resource Name (ARN) of the role to assume. For information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| PreferredRole | preferred\$1role (deprecated) | Optional | none | 

## Role session duration
<a name="jdbc-v3-driver-role-okta-session-duration"></a>

The duration, in seconds, of the role session. For more information, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| RoleSessionDuration | Duration (deprecated) | Optional | 3600 | 

## Lake Formation enabled
<a name="jdbc-v3-driver-okta-lake-formation-enabled"></a>

Specifies whether to use the [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API action to retrieve temporary IAM credentials instead of the [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API action.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| LakeFormationEnabled | none | Optional | FALSE | 

# Ping credentials
<a name="jdbc-v3-driver-ping-credentials"></a>

A SAML-based authentication mechanism that enables authentication to Athena using the Ping Federate identity provider. This method assumes that a federation has already been set up between Athena and Ping Federate.

## Credentials provider
<a name="jdbc-v3-driver-ping-credentials-provider"></a>

The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `Ping`.


****  

| Parameter name | Alias | Parameter type | Default value | Value to use | 
| --- | --- | --- | --- | --- | 
| CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | Ping | 

## User
<a name="jdbc-v3-driver-ping-user"></a>

The email address of the Ping Federate user to use for authentication with Ping Federate.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| User | UID (deprecated) | Required | none | 

## Password
<a name="jdbc-v3-driver-ping-password"></a>

The password for the Ping Federate user.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| Password | PWD (deprecated) | Required | none | 

## PingHostName
<a name="jdbc-v3-driver-ping-host-name"></a>

The address for your Ping server. To find your address, visit the following URL and view the **SSO Application Endpoint** field.

```
https://your-pf-host-#:9999/pingfederate/your-pf-app#/spConnections
```


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| PingHostName | IdP\$1Host (deprecated) | Required | none | 

## PingPortNumber
<a name="jdbc-v3-driver-ping-port-number"></a>

The port number to use to connect to your IdP host.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| PingPortNumber | IdP\$1Port (deprecated) | Required | none | 

## PingPartnerSpId
<a name="jdbc-v3-driver-ping-partner-spid"></a>

The service provider address. To find the service provider address, visit the following URL and view the **SSO Application Endpoint** field.

```
https://your-pf-host-#:9999/pingfederate/your-pf-app#/spConnections
```


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
|  PingPartnerSpId  | Partner\$1SPID (deprecated) | Required | none | 

## Preferred role
<a name="jdbc-v3-driver-ping-preferred-role"></a>

The Amazon Resource Name (ARN) of the role to assume. For information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| PreferredRole | preferred\$1role (deprecated) | Optional | none | 

## Role session duration
<a name="jdbc-v3-driver-role-ping-session-duration"></a>

The duration, in seconds, of the role session. For more information, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| RoleSessionDuration | Duration (deprecated) | Optional | 3600 | 

## Lake Formation enabled
<a name="jdbc-v3-driver-ping-lake-formation-enabled"></a>

Specifies whether to use the [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API action to retrieve temporary IAM credentials instead of the [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API action.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| LakeFormationEnabled | none | Optional | FALSE | 

# AD FS credentials
<a name="jdbc-v3-driver-adfs-credentials"></a>

A SAML-based authentication mechanism that enables authentication to Athena using Microsoft Active Directory Federation Services (AD FS). This method assumes that the user has already set up a federation between Athena and AD FS.

## Credentials provider
<a name="jdbc-v3-driver-adfs-credentials-credentials-provider"></a>

The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `ADFS`.


****  

| Parameter name | Alias | Parameter type | Default value | Value to use | 
| --- | --- | --- | --- | --- | 
| CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | ADFS | 

## User
<a name="jdbc-v3-driver-adfs-credentials-user"></a>

The email address of the AD FS user to use for authentication with AD FS.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| User | UID (deprecated) | Required for form-based authentication. Optional for Windows Integrated Authentication. | none | 

## Password
<a name="jdbc-v3-driver-adfs-credentials-password"></a>

The password for the AD FS user.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| Password | PWD (deprecated) | Required for form-based authentication. Optional for Windows Integrated Authentication. | none | 

## ADFS host name
<a name="jdbc-v3-driver-adfs-credentials-adfshostname"></a>

The address for your AD FS server.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| AdfsHostName | IdP\$1Host (deprecated) | Required | none | 

## ADFS port number
<a name="jdbc-v3-driver-adfs-credentials-adfsportnumber"></a>

The port number to use to connect to your AD FS server.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| AdfsPortNumber | IdP\$1Port (deprecated) | Required | none | 

## ADFS relying party
<a name="jdbc-v3-driver-adfs-credentials-adfsrelyingparty"></a>

The trusted relying party. Use this parameter to override the AD FS relying party endpoint URL.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| AdfsRelyingParty | LoginToRP (deprecated) | Optional | urn:amazon:webservices | 

## ADFS WIA enabled
<a name="jdbc-v3-driver-adfs-credentials-adfswiaenabled"></a>

Boolean. Use this parameter to enable Windows Integrated Authentication (WIA) with AD FS.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| AdfsWiaEnabled | none | Optional | FALSE | 

## Preferred role
<a name="jdbc-v3-driver-adfs-credentials-preferred-role"></a>

The Amazon Resource Name (ARN) of the role to assume. For information about ARN roles, see [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| PreferredRole | preferred\$1role (deprecated) | Optional | none | 

## Role session duration
<a name="jdbc-v3-driver-adfs-credentials-role-session-duration"></a>

The duration, in seconds, of the role session. For more information, see [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| RoleSessionDuration | Duration (deprecated) | Optional | 3600 | 

## Lake Formation enabled
<a name="jdbc-v3-driver-adfs-credentials-lake-formation-enabled"></a>

Specifies whether to use the [https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API action to retrieve temporary IAM credentials instead of the [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API action.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| LakeFormationEnabled | none | Optional | FALSE | 

# Browser Azure AD credentials
<a name="jdbc-v3-driver-browser-azure-ad-credentials"></a>

Browser Azure AD is a SAML-based authentication mechanism that works with the Azure AD identity provider and supports multi-factor authentication. Unlike the standard Azure AD authentication mechanism, this mechanism does not require a user name, password, or client secret in the connection parameters. Like the standard Azure AD authentication mechanism, Browser Azure AD also assumes the user has already set up federation between Athena and Azure AD.

## Credentials provider
<a name="jdbc-v3-driver-browser-azure-ad-credentials-provider"></a>

The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `BrowserAzureAD`.


****  

| Parameter name | Alias | Parameter type | Default value | Value to use | 
| --- | --- | --- | --- | --- | 
| CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | BrowserAzureAD | 

## Azure AD tenant ID
<a name="jdbc-v3-driver-browser-azure-ad-azure-ad-tenant-id"></a>

The tenant ID of your Azure AD application


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| AzureAdTenantId | tenant\$1id (deprecated) | Required | none | 

## Azure AD client ID
<a name="jdbc-v3-driver-browser-azure-ad-azure-ad-client-id"></a>

The client ID of your Azure AD application


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| AzureAdClientId | client\$1id (deprecated) | Required | none | 

## Identity provider response timeout
<a name="jdbc-v3-driver-identity-provider-response-timeout"></a>

The duration, in seconds, before the driver stops waiting for the SAML response from Azure AD.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| IdpResponseTimeout | idp\$1response\$1timeout (deprecated) | Optional | 120 | 

## Preferred role
<a name="jdbc-v3-driver-browser-azure-ad-preferred-role"></a>

The Amazon Resource Name (ARN) of the role to assume. For information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| PreferredRole | preferred\$1role (deprecated) | Optional | none | 

## Role session duration
<a name="jdbc-v3-driver-browser-azure-ad-role-session-duration"></a>

The duration, in seconds, of the role session. For more information, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| RoleSessionDuration | Duration (deprecated) | Optional | 3600 | 

## Lake Formation enabled
<a name="jdbc-v3-driver-browser-azure-ad-lake-formation-enabled"></a>

Specifies whether to use the [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API action to retrieve temporary IAM credentials instead of the [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API action.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| LakeFormationEnabled | none | Optional | FALSE | 

# Browser SAML credentials
<a name="jdbc-v3-driver-browser-saml-credentials"></a>

Browser SAML is a generic authentication plugin that can work with SAML-based identity providers and supports multi-factor authentication.

## Credentials provider
<a name="jdbc-v3-driver-browser-saml-credentials-provider"></a>

The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `BrowserSaml`.


****  

| Parameter name | Alias | Parameter type | Default value | Value to use | 
| --- | --- | --- | --- | --- | 
| CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | BrowserSaml | 

## Single sign-on login URL
<a name="jdbc-v3-driver-single-sign-on-login-url"></a>

The single sign-on URL for your application on the SAML-based identity provider.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| SsoLoginUrl | login\$1url (deprecated) | Required | none | 

## Listen port
<a name="jdbc-v3-driver-listen-port"></a>

The port number that is used to listen for the SAML response. This value should match the URL with which you configured the SAML-based identity provider (for example, `http://localhost:7890/athena`).


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| ListenPort | listen\$1port (deprecated) | Optional | 7890 | 

## Identity provider response timeout
<a name="jdbc-v3-driver-single-sign-on-login-url-identity-provider-response-timeout"></a>

The duration, in seconds, before the driver stops waiting for the SAML response from Azure AD.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| IdpResponseTimeout | idp\$1response\$1timeout (deprecated) | Optional | 120 | 

## Preferred role
<a name="jdbc-v3-driver-single-sign-on-login-url-preferred-role"></a>

The Amazon Resource Name (ARN) of the role to assume. For information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| PreferredRole | preferred\$1role (deprecated) | Optional | none | 

## Role session duration
<a name="jdbc-v3-driver-single-sign-on-login-url-role-session-duration"></a>

The duration, in seconds, of the role session. For more information, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| RoleSessionDuration | Duration (deprecated) | Optional | 3600 | 

## Lake Formation enabled
<a name="jdbc-v3-driver-single-sign-on-login-url-lake-formation-enabled"></a>

Specifies whether to use the [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API action to retrieve temporary IAM credentials instead of the [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API action.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| LakeFormationEnabled | none | Optional | FALSE | 

# DataZone IdC Credentials Provider
<a name="jdbc-v3-driver-datazone-idc"></a>

An authentication mechanism that enables connecting to DataZone-governed data in Athena using IAM Identity Center.

## Credentials provider
<a name="jdbc-v3-driver-datazone-idc-credentials-provider"></a>

The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `DataZoneIdc`. Note that the `AWSCredentialsProviderClass` alias is deprecated; use the `CredentialsProvider` parameter name instead.


****  

| Parameter name | Alias | Parameter type | Default value | Value to use | 
| --- | --- | --- | --- | --- | 
| CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | DataZoneIdc | 

## DataZone domain identifier
<a name="jdbc-v3-driver-datazone-idc-datazone-domain-identifier"></a>

Identifier of the DataZone domain to use.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| DataZoneDomainId | none | Required | none | 

## DataZone environment identifier
<a name="jdbc-v3-driver-datazone-idc-datazone-environment-identifier"></a>

Identifier of the DataZone environment to use.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| DataZoneEnvironmentId | none | Required | none | 

## DataZone domain region
<a name="jdbc-v3-driver-datazone-idc-datazone-domain-region"></a>

The AWS Region where your DataZone domain is provisioned.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| DataZoneDomainRegion | none | Required | none | 

## Region
<a name="jdbc-v3-driver-datazone-idc-region"></a>

The AWS Region where your DataZone environment and Athena workgroup are provisioned.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| Region | none | Required | none | 

## IAM Identity Center issuer URL
<a name="jdbc-v3-driver-datazone-idc-iam-identity-center-issuer-url"></a>

The issuer URL of the IAM Identity Center instance that the DataZone domain uses.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| IdentityCenterIssuerUrl | none | Required | none | 

## DataZone endpoint override
<a name="jdbc-v3-driver-datazone-idc-datazone-endpoint-override"></a>

The DataZone API endpoint to be used instead of the default for the provided AWS Region.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| DataZoneEndpointOverride | none | Optional | none | 

## Enable token caching
<a name="jdbc-v3-driver-datazone-idc-enable-token-caching"></a>

When enabled, allows the same IAM Identity Center access token to be used across driver connections. This prevents SQL tools that create multiple driver connections from launching multiple browser windows. If you enable this parameter, we recommend that you close the SQL tool immediately after using it to clear the token cache and require re-authentication.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| EnableTokenCaching | none | Optional | FALSE | 

## Listen port
<a name="jdbc-v3-driver-datazone-idc-listen-port"></a>

The port number that listens for the IAM Identity Center response.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| ListenPort | none | Optional | 8000 | 

## Identity provider response time out
<a name="jdbc-v3-driver-datazone-idc-identity-provider-response-time-out"></a>

The duration, in seconds, before the driver stops waiting for the response from IAM Identity Center.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| IdpResponseTimeout | none | Optional | 120 | 

# DataZone IAM Credentials Provider
<a name="jdbc-v3-driver-datazone-iamcp"></a>

An authentication mechanism that uses IAM credentials to connect to DataZone-governed data in Athena.

## DataZone domain identifier
<a name="jdbc-v3-driver-datazone-iamcp-datazone-domain-identifier"></a>

Identifier of the DataZone domain to use.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| DataZoneDomainId | none | Required | none | 

## DataZone environment identifier
<a name="jdbc-v3-driver-datazone-iamcp-datazone-environment-identifier"></a>

Identifier of the DataZone environment to use.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| DataZoneEnvironmentId | none | Required | none | 

## DataZone domain region
<a name="jdbc-v3-driver-datazone-iamcp-datazone-domain-region"></a>

The AWS Region where your DataZone domain is provisioned.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| DataZoneDomainRegion | none | Required | none | 

## DataZone endpoint override
<a name="jdbc-v3-driver-datazone-iamcp-datazone-endpoint-override"></a>

The DataZone API endpoint to use instead of the endpoint default for the provided AWS Region.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| DataZoneEndpointOverride | none | Optional | none | 

## User
<a name="jdbc-v3-driver-datazone-iamcp-user"></a>

Your AWS access key ID. For more information about access keys, see [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html) in the *IAM User Guide*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| User | AccessKeyId | Optional | none | 

## Password
<a name="jdbc-v3-driver-datazone-iamcp-password"></a>

Your AWS secret key ID. For more information about access keys, see [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html) in the *IAM User Guide*.


****  

| Parameter name | Alias | Parameter type | Default value | 
| --- | --- | --- | --- | 
| Password | SecretAccessKey | Optional | none | 

# Other JDBC 3.x configuration
<a name="jdbc-v3-driver-other-configuration"></a>

The following sections describe some additional configuration settings for the JDBC 3.x driver.

## Network timeout
<a name="jdbc-v3-driver-network-timeout"></a>

The network timeout controls the amount of time in milliseconds that the driver waits for a network connection to be established. This includes the time it takes to send API requests. After this time, the driver throws a timeout exception. In rare circumstances, it may be useful to change the network timeout. For example, you might want to increase the timeout for long garbage collection pauses.

To set it, call the `setNetworkTimeout` method on a JDBC `Connection` object. This value can be changed during the lifecycle of the JDBC connection. For more information, see [setNetworkTimeout](https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html#setNetworkTimeout-java.util.concurrent.Executor-int-) in the Oracle JDBC API documentation. Using the `setNetworkTimeout` method is equivalent to setting the [Network timeout](jdbc-v3-driver-advanced-connection-parameters.md#jdbc-v3-driver-networktimeoutmillis) connection parameter. 

The following example sets the network timeout to 5000 milliseconds.

```
...
AthenaDriver driver = new AthenaDriver();
Connection connection = driver.connect(url, connectionParameters);
connection.setNetworkTimeout(null, 5000);
...
```

## Query timeout
<a name="jdbc-v3-driver-query-timeout"></a>

The amount of time, in seconds, the driver will wait for a query to complete on Athena after a query has been submitted. After this time, the driver attempts to cancel the submitted query and throws a timeout exception.

The query timeout cannot be set as a connection parameter. To set it, call the `setQueryTimeout` method on a JDBC `Statement` object. This value can be changed during the lifecycle of a JDBC statement. The default value of this parameter is `0` (zero). A value of `0` means that queries can run until they complete (subject to [Service Quotas](service-limits.md)).

The following example sets the query timeout to 5 seconds.

```
...
AthenaDriver driver = new AthenaDriver();
Connection connection = driver.connect(url, connectionParameters);
Statement statement = connection.createStatement();
statement.setQueryTimeout(5);
...
```

# Amazon Athena JDBC 3.x release notes
<a name="jdbc-v3-driver-release-notes"></a>

These release notes provide details of improvements and fixes in the Amazon Athena JDBC 3.x driver.

## 3.7.0
<a name="jdbc-v3-driver-release-notes-2025-11-21"></a>

Released 2025-11-21

### Improvements
<a name="jdbc-v3-driver-release-notes-2025-11-21-improvements"></a>
+ **Browser OIDC Trusted identity propagation authentication plugin** – Added a new authentication plugin that enables seamless browser-based authentication with OpenID Connect (OIDC) identity providers. This plugin handles the complete OAuth 2.0 flow through your default browser, automatically fetches the JSON Web Token (JWT), and integrates with trusted identity propagation. Designed specifically for single-user desktop environments, it provides a more streamlined authentication experience compared to manual JWT handling. For more information about trusted identity propagation, see [What is trusted identity propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overview.html).

### Fixes
<a name="jdbc-v3-driver-release-notes-2025-11-21-fixes"></a>
+ **Enhanced timestamp precision support** – The driver now fully supports millisecond and nanosecond precision in timestamp values returned from Athena queries through the `getTimestamp()` method.
+ **Improved complex type handling** – Fixed issues with parsing nested data types (arrays, structs, and maps) in both `DatabaseMetaData#getColumns` and general metadata operations, ensuring accurate type information for complex data structures.
+ **Enhanced error logging** – Improved logging for S3 metadata fetch failures, providing clearer error messages and better diagnostic information.

## 3.6.0
<a name="jdbc-v3-driver-release-notes-2025-09-10"></a>

Released 2025-09-10

### Improvements
<a name="jdbc-v3-driver-release-notes-2025-09-10-improvements"></a>
+ **JWT Trusted identity propagation authentication plugin** – Added a new authentication plugin to support JWT trusted identity propagation integration with JDBC drivers. This authentication type allows you to use a JSON web token (JWT) obtained from an external identity provider as a connection parameter to authenticate with Athena. With trusted identity propagation, identity context is added to an IAM role to identify the user requesting access to AWS resources. For information on enabling and using trusted identity propagation, see [What is trusted identity propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overview.html).
+ **Custom SSO OIDC and SSO admin endpoints support** – Added support for custom SSO OIDC and SSO Admin endpoints in the JDBC driver. This enhancement allows you to specify your own endpoints for SSO services when running JDBC behind VPCs.
+ **AWS SDK version update** – We have updated the AWS SDK version used in the driver to 2.32.16 and have updated the project dependencies for release 3.6.0.

## 3.5.1
<a name="jdbc-v3-driver-release-notes-2025-07-17"></a>

Released 2025-07-17

### Improvements
<a name="jdbc-v3-driver-release-notes-2025-07-17-improvements"></a>
+ **Logging capabilities** – Enhanced S3 fetch logging by elevating log level to `INFO` and adding metrics for row counts, offsets, and object length. Implemented connection lifecycle tracking and optimized overall logging performance.
+ **Special characters handling** – Improved handling of special characters for `LIKE` patterns in schema and catalog names.
+ **Connection state management** – Improved connection state management to prevent potential errors by preventing API calls after connection closure and adding safety checks for query operations during shutdown.

### Fixes
<a name="jdbc-v3-driver-release-notes-2025-07-17-fixes"></a>
+ **DDL query metadata** – Fixed `NoSuchKeyFound` issue with DDL query metadata handling.

## 3.5.0
<a name="jdbc-v3-driver-release-notes-2025-03-18"></a>

Released 2025-03-18

### Improvements
<a name="jdbc-v3-driver-release-notes-2025-03-18-improvements"></a>
+ **Result configuration parameters** – Added support for two new connection parameters `ExpectedBucketOwner` and `AclOption`. For more information, see [Result configuration parameters](jdbc-v3-driver-advanced-connection-parameters.md#jdbc-v3-driver-result-config).
+ **AWS SDK version** – The AWS SDK version used in the driver has been updated to 2.30.22.

## 3.4.0
<a name="jdbc-v3-driver-release-notes-2025-02-18"></a>

Released 2025-02-18

### Improvements
<a name="jdbc-v3-driver-release-notes-2025-02-18-improvements"></a>
+ **Result Fetcher** – The driver now automatically selects the fastest method to download query results. This removes the need to manually configure the fetcher in most situations. For more information, see [Result fetching parameters](jdbc-v3-driver-advanced-connection-parameters.md#jdbc-v3-driver-result-fetching-parameters).

### Fixes
<a name="jdbc-v3-driver-release-notes-2025-02-18-fixes"></a>
+ **ResultSet** – The driver now handles iterating over the result sets of DDL statements that don't produce result objects on S3. It also returns an empty `ResultSet` object instead of null when `GetQueryResultsStream` returns a completely empty page.
+ **ResultsStream** – The result streaming has been optimized by removing unnecessary calls to count the number of rows in internal buffers.
+ **getTables** – The `GetTables` call has been optimized by handling table types based on `ListTableMetadata` and `GetTableMetadata` responses.

## 3.3.0
<a name="jdbc-v3-driver-release-notes-2024-10-30"></a>

Released 2024-10-30

### Improvements
<a name="jdbc-v3-driver-release-notes-2024-10-30-improvements"></a>
+ **DataZone authentication** – Added support for the DataZone authentication plugins `DataZoneIdC` and `DataZoneIAM`. For more information, see [DataZone IdC Credentials Provider](jdbc-v3-driver-datazone-idc.md) and [DataZone IAM Credentials Provider](jdbc-v3-driver-datazone-iamcp.md).
+ **Network timeout** – The network timeout can now be set using the `NetworkTimeoutMillis` connection parameter. Previously it could be set only on the `Connection` object itself. For more information, see [Network timeout](jdbc-v3-driver-other-configuration.md#jdbc-v3-driver-network-timeout).

### Fixes
<a name="jdbc-v3-driver-release-notes-2024-10-30-fixes"></a>
+ **S3 empty object handling** – The driver now handles empty objects in the S3 fetcher instead of throwing an Amazon S3 Range Not Satisfiable exception.
+ **Logging** – The driver no longer logs the message Items requested for query execution [...], but subscription is cancelled after consuming query results.
+ **Empty parameter strings** – The driver now handles empty strings present in a connection parameter as if the parameter were not present. This resolves issues that occurred when some BI tools inadvertently passed empty strings that caused unintended authentication attempts.

## 3.2.2
<a name="jdbc-v3-driver-release-notes-2024-07-29"></a>

Released 2024-07-29

### Improvements
<a name="jdbc-v3-driver-release-notes-2024-07-29-improvements"></a>
+ **Data type mapping** – Improved the compliance with the JDBC spec by changing how the driver maps the `tinyint`, `smallint`, `row`, and `struct` data types to Java objects.
+ **AWS SDK version update** – The AWS SDK version used in the driver has been updated to 2.26.23.

### Fixes
<a name="jdbc-v3-driver-release-notes-2024-07-29-fixes"></a>
+ **Comments** – Fixed an issue with line comments at the end of a statement.
+ **Database listing** – Fixed an issue in which listing databases could enter an infinite loop when the last page returned by the paginated `ListDatabases` API was empty.

## 3.2.1
<a name="jdbc-v3-driver-release-notes-2024-07-03"></a>

Released 2024-07-03

### Improvements
<a name="jdbc-v3-driver-release-notes-2024-07-03-improvements"></a>
+ **JWT credentials provider** – Added support for user-specified session durations. For more information, see [Role session duration](jdbc-v3-driver-jwt-credentials.md#jdbc-v3-driver-jwt-role-session-duration).

### Fixes
<a name="jdbc-v3-driver-release-notes-2024-07-03-fixes"></a>
+ **Thread pool** – Created one `ThreadPoolExecutor` per connection for asynchronous tasks to avoid using the `ForkJoin` pool.
+ **Credential providers** – The proxy host is now parsed to get the scheme and host when the HTTP client is configured for external IdPs.
+ **Default credentials provider** – Ensured the default credentials provider can't be closed by client code.
+ **getColumns** – Fixed an `ORDINAL_COLUMN` column property issue in the `DatabaseMetaData#getColumns` method.
+ **ResultSet** – Added support for `Infinity`, `-Infinity`, and `NaN` to `ResultSet.` Fixed a discrepancy between the column type returned from catalog operations and the result set of a completed query.

## 3.2.0
<a name="jdbc-v3-driver-release-notes-2024-02-26"></a>

Released 2024-04-26

### Improvements
<a name="jdbc-v3-driver-release-notes-2024-02-26-improvements"></a>
+ **Catalog operation performance** – Performance has been improved for catalog operations that do not use wildcard characters.
+ **Minimum polling interval change** – The minimum polling interval default has been modified to reduce the number of API calls the driver makes to Athena. Query completions are still detected as soon as possible.
+ **BI tool discoverability** – The driver has been made more easily discoverable for business intelligence tools.
+ **Data type mapping** – Data type mapping to the Athena `binary`, `array`, and `struct` DDL data types has been improved.
+ **AWS SDK version** – The AWS SDK version used in the driver has been updated to 2.25.34.

### Fixes
<a name="jdbc-v3-driver-release-notes-2024-02-26-fixes"></a>
+ **Federated catalog table listings** – Fixed an issue that caused federated catalogs to return an empty list of tables.
+ **getSchemas** – Fixed an issue that caused the JDBC [DatabaseMetaData\$1getSchemas](https://docs.oracle.com/javase/8/docs/api/java/sql/DatabaseMetaData.html#getSchemas--) method to fetch databases only from the default catalog instead of from all catalogs.
+ **getColumns** – Fixed an issue that caused a null catalog to be returned when the JDBC [DatabaseMetaData\$1getColumns](https://docs.oracle.com/javase/8/docs/api/java/sql/DatabaseMetaData.html#getColumns-java.lang.String-java.lang.String-java.lang.String-java.lang.String-) method was called with a null catalog name.

## 3.1.0
<a name="jdbc-v3-driver-release-notes-2024-02-15"></a>

Released 2024-02-15

### Improvements
<a name="jdbc-v3-driver-release-notes-2024-02-15-improvements"></a>
+ Support added for Microsoft Active Directory Federation Services (AD FS) Windows Integrated Authentication and form-based authentication.
+ For backwards compatibility with version 2.x, the `awsathena` JDBC sub-protocol is now accepted but produces a deprecation warning. Use the `athena` JDBC sub-protocol instead.
+ `AwsDataCatalog` is now the default for the catalog parameter, and `default` is the default for the database parameter. These changes ensure that correct values for the current catalog and database are returned instead of null.
+ In conformance with the JDBC specification, `IS_AUTOINCREMENT` and `IS_GENERATEDCOLUMN` now return an empty string instead of `NO`.
+ The Athena `int` data type now maps to the same JDBC type as Athena `integer` instead of to `other`.
+ When the column metadata from Athena does not contain the optional `precision` and `scale` fields, the driver now returns zero for the corresponding values in a `ResultSet` column.
+ The AWS SDK version has been updated to 2.21.39.

### Fixes
<a name="jdbc-v3-driver-release-notes-2024-02-15-fixes"></a>
+ Fixed an issue with `GetQueryResultsStream` that caused an exception to occur when plain text results from Athena had a column count inconsistent with the column count in Athena result metadata.

## 3.0.0
<a name="jdbc-v3-driver-release-notes-2023-11-16"></a>

Released 2023-11-16

The Athena JDBC 3.x driver is the new generation driver offering better performance and compatibility. The JDBC 3.x driver supports reading query results directly from Amazon S3, which improves the performance of applications that consume large query results. The new driver also has fewer third-party dependencies, which makes integration with BI tools and custom applications easier.

# Previous versions of the Athena JDBC 3.x driver
<a name="jdbc-v3-driver-previous-versions"></a>

We highly recommended that you use the [latest version](jdbc-v3-driver.md) of the JDBC 3.x driver. The latest version of the driver contains the most recent improvements and fixes. Use an older version only if your application experiences incompatibilities with the latest version.

## JDBC driver uber jar
<a name="jdbc-v3-driver-download-uber-jar-previous"></a>

The following download packages the driver and all its dependencies in the same `.jar` file. This download is commonly used for third-party SQL clients.
+ [3.6.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.6.0/athena-jdbc-3.6.0-with-dependencies.jar)
+ [3.5.1 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.5.1/athena-jdbc-3.5.1-with-dependencies.jar)
+ [3.5.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.5.0/athena-jdbc-3.5.0-with-dependencies.jar)
+ [3.4.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.4.0/athena-jdbc-3.4.0-with-dependencies.jar)
+ [3.3.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.3.0/athena-jdbc-3.3.0-with-dependencies.jar)
+ [3.2.2 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.2/athena-jdbc-3.2.2-with-dependencies.jar)
+ [3.2.1 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.1/athena-jdbc-3.2.1-with-dependencies.jar)
+ [3.2.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.0/athena-jdbc-3.2.0-with-dependencies.jar)
+ [3.1.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.1.0/athena-jdbc-3.1.0-with-dependencies.jar)
+ [3.0.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.0.0/athena-jdbc-3.0.0-with-dependencies.jar)

## JDBC driver lean jar
<a name="jdbc-v3-driver-download-lean-jar"></a>

The following download is a `.zip` file that contains the lean `.jar` for the driver and separate `.jar` files for the driver's dependencies. This download is commonly used for custom applications that might have dependencies that conflict with the dependencies that the driver uses. This download is useful if you want to choose which of the driver dependencies to include with the lean jar, and which to exclude if your custom application already contains one or more of them.
+ [3.6.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.6.0/athena-jdbc-3.6.0-lean-jar-and-separate-dependencies-jars.zip)
+ [3.5.1 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.5.1/athena-jdbc-3.5.1-lean-jar-and-separate-dependencies-jars.zip)
+ [3.5.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.5.0/athena-jdbc-3.5.0-lean-jar-and-separate-dependencies-jars.zip)
+ [3.4.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.4.0/athena-jdbc-3.4.0-lean-jar-and-separate-dependencies-jars.zip)
+ [3.3.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.3.0/athena-jdbc-3.3.0-lean-jar-and-separate-dependencies-jars.zip)
+ [3.2.2 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.2/athena-jdbc-3.2.2-lean-jar-and-separate-dependencies-jars.zip)
+ [3.2.1 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.1/athena-jdbc-3.2.1-lean-jar-and-separate-dependencies-jars.zip)
+ [3.2.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.0/athena-jdbc-3.2.0-lean-jar-and-separate-dependencies-jars.zip)
+ [3.1.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.1.0/athena-jdbc-3.1.0-lean-jar-and-separate-dependencies-jars.zip)
+ [3.0.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.0.0/athena-jdbc-3.0.0-lean-jar-and-separate-dependencies-jars.zip)