# Athena JDBC 3.x driver
JDBC 3.x

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

+ Java 8 (or higher) runtime environment
+ At least 20 MB of available disk space

## Considerations and limitations


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


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


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


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


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


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
Get started

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


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

### In a custom application


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


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

## Running the driver


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

### In a custom application


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


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


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


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


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


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


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


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


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


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


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
JDBC 3.x connection parameters

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
Basic

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

## Region


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


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


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


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


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
Advanced

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


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


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


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


### Result fetcher


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


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


### Expected bucket owner


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


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


### Enable result reuse


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


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


### Minimum query execution polling interval


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


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


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


### Athena endpoint override


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


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


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


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


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


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


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


### Proxy host


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


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


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


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


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


This section describes parameters related to logging.

### Log level


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


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


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


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


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


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
Authentication

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
IAM

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

## User


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


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


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
Default

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


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
AWS configuration profile

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


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


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
Instance profile

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


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
Custom

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


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 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
JWT

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


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


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


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


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


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
JWT trusted identity propagation

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


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


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


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


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


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


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


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


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
Browser trusted identity propagation

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


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


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


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


****  

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

## WorkgroupArn


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


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


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


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


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


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


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


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


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


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
Azure AD

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


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


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


The password for the Azure AD user.


****  

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

## Azure AD tenant ID


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


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


The client secret of your Azure AD application.


****  

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

## Preferred role


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


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


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
Okta

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


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


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


The password for the Okta user.


****  

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

## Okta host name


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


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


The name of your Okta application.


****  

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

## Okta MFA type


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


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


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


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


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


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
Ping

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


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


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


The password for the Ping Federate user.


****  

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

## PingHostName


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


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


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


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


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


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
AD FS

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


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


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


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


The address for your AD FS server.


****  

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

## ADFS port number


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


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


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


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


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


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
Browser Azure AD

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


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


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


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


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


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


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


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
Browser SAML

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

## Credentials provider


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


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


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


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


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


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


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
DataZone IdC

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

## Credentials provider


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


Identifier of the DataZone domain to use.


****  

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

## DataZone environment identifier


Identifier of the DataZone environment to use.


****  

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

## DataZone domain region


The AWS Region where your DataZone domain is provisioned.


****  

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

## Region


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


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


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


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


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


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
DataZone IAM

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

## DataZone domain identifier


Identifier of the DataZone domain to use.


****  

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

## DataZone environment identifier


Identifier of the DataZone environment to use.


****  

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

## DataZone domain region


The AWS Region where your DataZone domain is provisioned.


****  

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

## DataZone endpoint override


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


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


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


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

## Network timeout


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


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
JDBC 3.x release notes

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

## 3.7.0


Released 2025-11-21

### Improvements

+ **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

+ **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


Released 2025-09-10

### Improvements

+ **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


Released 2025-07-17

### Improvements

+ **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

+ **DDL query metadata** – Fixed `NoSuchKeyFound` issue with DDL query metadata handling.

## 3.5.0


Released 2025-03-18

### Improvements

+ **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


Released 2025-02-18

### Improvements

+ **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

+ **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


Released 2024-10-30

### Improvements

+ **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

+ **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


Released 2024-07-29

### Improvements

+ **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

+ **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


Released 2024-07-03

### Improvements

+ **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

+ **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


Released 2024-04-26

### Improvements

+ **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

+ **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


Released 2024-02-15

### Improvements

+ 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

+ 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


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
Previous versions

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


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


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)