# Get started with the ODBC 2.x driver
<a name="odbc-v2-driver-getting-started"></a>

Use the information in this section to get started with the Amazon Athena ODBC 2.x driver. The driver is supported on the Windows, Linux, and macOS operating systems.

**Topics**
+ [

# Windows
](odbc-v2-driver-getting-started-windows.md)
+ [

# Linux
](odbc-v2-driver-getting-started-linux.md)
+ [

# macOS
](odbc-v2-driver-getting-started-macos.md)

# Windows
<a name="odbc-v2-driver-getting-started-windows"></a>

If you want to use a Windows client computer to access Amazon Athena, the Amazon Athena ODBC driver is required.

## Windows system requirements
<a name="odbc-v2-driver-system-requirements-windows"></a>

Install the Amazon Athena ODBC driver on client computers that will access Amazon Athena databases directly instead of using a web browser.

The Windows system you use must meet the following requirements:
+ You have administrator rights
+ One of the following operating systems:
  + Windows 11, 10, or 8.1
  + Windows Server 2019, 2016, or 2012
  + Supported processor architecture : x86\$164 (64-bit)
+ At least 100 MB of available disk space
+ [Microsoft Visual C\$1\$1 Redistributable for Visual Studio](https://visualstudio.microsoft.com/downloads/#microsoft-visual-c-redistributable-for-visual-studio-2022) for 64-bit Windows is installed.

## Installing the Amazon Athena ODBC driver
<a name="odbc-v2-driver-installing"></a>

**To download and install the Amazon Athena ODBC driver for Windows**

1. [Download](odbc-v2-driver.md#odbc-v2-driver-download) the `AmazonAthenaODBC-2.x.x.x.msi` installation file.

1. Launch the installation file, and then choose **Next**.

1. To accept the terms of the license agreement, select the check box, and then choose **Next**.

1. To change the installation location, choose **Browse**, browse to the desired folder, and then choose **OK**.

1. To accept the installation location, choose **Next**.

1. Choose **Install**.

1. When the installation completes, choose **Finish**.

## Ways to set driver configuration options
<a name="odbc-v2-driver-ways-to-set-options"></a>

To control the behavior of the Amazon Athena ODBC driver in Windows, you can set driver configuration options in the following ways:
+ In the **ODBC Data Source Administrator** program when you configure a data source name (DSN).
+ By adding or changing Windows registry keys in the following location:

  ```
  HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\YOUR_DSN_NAME
  ```
+ By setting driver options in the connection string when you connect programmatically.

## Configuring a data source name on Windows
<a name="odbc-v2-driver-configuring-dsn-on-windows"></a>

After you download and install the ODBC driver, you must add a data source name (DSN) entry to the client computer or Amazon EC2 instance. SQL client tools use this data source to connect to and query Amazon Athena.

**To create a system DSN entry**

1. From the Windows **Start** menu, right-click **ODBC Data Sources (64 bit)**, and then choose **More**, **Run as administrator**.

1. In the **ODBC Data Source Administrator**, choose the **Drivers** tab.

1. In the **Name** column, verify that **Amazon Athena ODBC (x64)** is present.

1. Do one of the following:
   + To configure the driver for all users on the computer, choose the **System DSN** tab. Because applications that use a different account to load data might not be able to detect user DSNs from another account, we recommend the system DSN configuration option.
**Note**  
Using the **System DSN** option requires administrative privileges.
   + To configure the driver for your user account only, choose the **User DSN** tab.

1. Choose **Add**. The **Create New Data Source** dialog box opens.

1. Choose **Amazon Athena ODBC (x64)**, and then choose **Finish**.

1. In the **Amazon Athena ODBC Configuration** dialog box, enter the following information. For detailed information about these options, see [Main ODBC 2.x connection parameters](odbc-v2-driver-main-connection-parameters.md).
   + For **Data Source Name**, enter a name that you want to use to identify the data source.
   + For **Description**, enter a description to help you identify the data source.
   + For **Region**, enter the name of the AWS Region that you will use Athena in (for example, ** us-west-1**).
   + For **Catalog**, enter the name of the Amazon Athena catalog. The default is **AwsDataCatalog**, which is used by AWS Glue.
   + For **Database**, enter the name of the Amazon Athena database. The default is **default**.
   + For **Workgroup**, enter the name of the Amazon Athena workgroup. The default is **primary**.
   + For **S3 Output Location**, enter the location in Amazon S3 where the query results will be stored (for example, **s3://amzn-s3-demo-bucket/**).
   + (Optional) For **Encryption Options**, choose an encryption option. The default is `NOT_SET`.
   + (Optional) For **KMS Key**, choose an encryption KMS key if required.

1. To specify configuration options for IAM authentication, choose **Authentication Options.**

1. Enter the following information:
   + For **Authentication Type**, choose **IAM Credentials**. This is the default. For more information about available authentication types, see [Authentication options](odbc-v2-driver-authentication-options.md).
   + For **Username**, enter a user name.
   + For **Password**, enter a password.
   + For **Session Token**, enter a session token if you want to use temporary AWS credentials. For information about temporary credentials, see [Using temporary credentials with AWS resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html) in the *IAM User Guide*.

1. Choose **OK**.

1. At the bottom of the **Amazon Athena ODBC Configuration** dialog box, choose **Test**. If the client computer connects successfully to Amazon Athena, the **Connection test** box reports **Connection successful**. If not, the box reports **Connection failed** with corresponding error information.

1. Choose **OK** to close the connection test. The data source that you created now appears in the list of data source names.

## Using a DSN-less connection on Windows
<a name="odbc-v2-driver-dsn-less-connection"></a>

You can use a DSN-less connection to connect to a database without a Data Source Name (DSN). The following example shows a connection string for the Amazon Athena ODBC (x64) ODBC driver that connects to Amazon Athena.

```
DRIVER={Amazon Athena ODBC (x64)};Catalog=AwsDataCatalog;AwsRegion=us-west-1;Schema=test_schema;S3OutputLocation=
s3://amzn-s3-demo-bucket/;AuthenticationType=IAM Credentials;UID=YOUR_UID;PWD=YOUR_PWD;
```

# Linux
<a name="odbc-v2-driver-getting-started-linux"></a>

If you want use a Linux client computer to access Amazon Athena, the Amazon Athena ODBC driver is required.

## Linux system requirements
<a name="odbc-v2-driver-getting-started-linux-linux-system-requirements"></a>

Each Linux client computer where you install the driver must meet the following requirements.
+ You have root access.
+ Use one of the following Linux distributions:
  + Red Hat Enterprise Linux (RHEL) 7 or 8
  + CentOS 7 or 8.
+ Have 100 MB of disk space available.
+ Use version 2.3.1 or later of [unixODBC](https://www.unixodbc.org/).
+ Use version 2.26 or later of the [GNU C Library](https://www.gnu.org/software/libc/) (glibc).

## Installing the ODBC data connector on Linux
<a name="odbc-v2-driver-getting-started-linux-installing-the-odbc-data-connector-on-linux"></a>

Use the following procedure to install the Amazon Athena ODBC driver on a Linux operating system.

**To install the Amazon Athena ODBC driver on Linux**

1. Enter one of the following commands:

   ```
   sudo rpm -Uvh AmazonAthenaODBC-2.X.Y.Z.rpm
   ```

   or

   ```
   sudo yum --nogpgcheck localinstall AmazonAthenaODBC-2.X.Y.Z.rpm
   ```

1. After the installation finishes, enter one of the following commands to verify that the driver is installed:
   + 

     ```
     yum list | grep amazon-athena-odbc-driver
     ```

     Output:

     ```
     amazon-athena-odbc-driver.x86_64 2.0.2.1-1.amzn2int installed
     ```
   + 

     ```
     rpm -qa | grep amazon
     ```

     Output:

     ```
     amazon-athena-odbc-driver-2.0.2.1-1.amzn2int.x86_64
     ```

## Configuring a data source name on Linux
<a name="odbc-v2-driver-getting-started-linux-configuring-a-data-source-name-on-linux"></a>

After the driver is installed, you can find example `.odbc.ini` and `.odbcinst.ini` files in the following location:
+ `/opt/athena/odbc/ini/`.

Use the `.ini` files in this location as examples for configuring the Amazon Athena ODBC driver and data source name (DSN).

**Note**  
By default, ODBC driver managers use the hidden configuration files `.odbc.ini` and `.odbcinst.ini`, which are located in the home directory.

To specify the path to the `.odbc.ini` and `.odbcinst.ini` files using unixODBC, perform the following steps.

**To specify ODBC `.ini` file locations using unixODBC**

1. Set `ODBCINI` to the full path and file name of the `odbc.ini` file, as in the following example.

   ```
   export ODBCINI=/opt/athena/odbc/ini/odbc.ini
   ```

1. Set `ODBCSYSINI` to the full path of the directory that contains the `odbcinst.ini` file, as in the following example.

   ```
   export ODBCSYSINI=/opt/athena/odbc/ini
   ```

1. Enter the following command to verify that you are using the unixODBC driver manager and the correct `odbc*.ini` files:

   ```
   username % odbcinst -j
   ```

   Sample output

   ```
   unixODBC 2.3.1
   DRIVERS............: /opt/athena/odbc/ini/odbcinst.ini
   SYSTEM DATA SOURCES: /opt/athena/odbc/ini/odbc.ini
   FILE DATA SOURCES..: /opt/athena/odbc/ini/ODBCDataSources
   USER DATA SOURCES..: /opt/athena/odbc/ini/odbc.ini
   SQLULEN Size.......: 8
   SQLLEN Size........: 8
   SQLSETPOSIROW Size.: 8
   ```

1. If you want to use a data source name (DSN) to connect to your data store, configure the `odbc.ini` file to define data source names (DSNs). Set the properties in the `odbc.ini` file to create a DSN that specifies the connection information for your data store, as in the following example.

   ```
   [ODBC Data Sources]
   athena_odbc_test=Amazon Athena ODBC (x64) 
   
   [ATHENA_WIDE_SETTINGS]  # Special DSN-name to signal driver about logging configuration.
   LogLevel=0              # To enable ODBC driver logs, set this to 1.
   UseAwsLogger=0          # To enable AWS-SDK logs, set this to 1.
   LogPath=/opt/athena/odbc/logs/ # Path to store the log files. Permissions to the location are required. 
   
   [athena_odbc_test]
   Driver=/opt/athena/odbc/lib/libathena-odbc.so
   AwsRegion=us-west-1
   Workgroup=primary
   Catalog=AwsDataCatalog
   Schema=default
   AuthenticationType=IAM Credentials
   UID=
   PWD=
   S3OutputLocation=s3://amzn-s3-demo-bucket/
   ```

1. Configure the `odbcinst.ini` file, as in the following example.

   ```
   [ODBC Drivers]
   Amazon Athena ODBC (x64)=Installed 
   
   [Amazon Athena ODBC (x64)]
   Driver=/opt/athena/odbc/lib/libathena-odbc.so
   Setup=/opt/athena/odbc/lib/libathena-odbc.so
   ```

1. After you install and configure the Amazon Athena ODBC driver, use the unixODBC `isql` command-line tool to verify the connection, as in the following example.

   ```
   username % isql -v "athena_odbc_test" 
   +---------------------------------------+
   | Connected!                            |
   |                                       |
   | sql-statement                         |
   | help [tablename]                      |
   | quit                                  |
   |                                       |
   +---------------------------------------+
   SQL>
   ```

## Verify the ODBC driver signature
<a name="verify-odbc-linux-signature"></a>

**Important**  
We recommend verifying the Athena ODBC driver RPM signature before installing it on your machine.

Follow these steps to verify the signature of the Athena ODBC driver RPM package:

1. **Prepare the templates**

   Prepare the commands with appropriate public key, RPM signature, and the corresponding access link to the RPM scripts hosted in Amazon S3 buckets. You must download the following to your device.
   +  [Athena ODBC driver](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Linux/AmazonAthenaODBC-2.1.0.0.rpm) 
   +  [Public Key](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Linux/public_key.pem) 
   +  [Athena ODBC RPM signature](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Linux/signature.bin) 

1. Download the Athena ODBC driver, public key, and Athena ODBC RPM signature to your device. 

1. Run the following command to verify ODBC driver signature:

   ```
   openssl dgst -sha256 -verify public_key.pem -signature signature.bin AmazonAthenaODBC-2.1.0.0.rpm
   ```

   If verification passes, you will see a message similar to `Verified OK`. This means you can now proceed to install the Athena ODBC driver. 

   If it fails with a message `Verification Failure`, it means that the signature on RPM has been tampered. Ensure that all the three files mentioned in step 1 are present, the paths are correctly specified ,and the files haven't been modified since download and then retry the verification process.

# macOS
<a name="odbc-v2-driver-getting-started-macos"></a>

If you want to use a macOS client computer to access Amazon Athena, the Amazon Athena ODBC driver is required.

## macOS system requirements
<a name="odbc-v2-driver-getting-started-macos-macos-system-requirements"></a>

Each macOS computer where you install the driver must meet the following requirements.
+ Use macOS version 14 or later.
+ Have 100 MB of disk space available.
+ Use version 3.52.16 or later of [iODBC](https://www.iodbc.org/dataspace/doc/iodbc/wiki/iodbcWiki/WelcomeVisitors).

## Installing the ODBC data connector on macOS
<a name="odbc-v2-driver-getting-started-macos-installing-the-odbc-data-connector-on-macos"></a>

Use the following procedure to download and install the Amazon Athena ODBC driver for macOS operating systems.

**To download and install the Amazon Athena ODBC driver for macOS**

1. Download the `.pkg` package file.

1. Double-click the `.pkg` file.

1. Follow the steps in the wizard to install the driver.

1. On the **License Agreement** page, press **Continue**, and then choose **Agree**.

1. Choose **Install**.

1. When the installation completes, choose **Finish**.

1. Enter the following command to verify that the driver is installed:

   ```
   > pkgutil --pkgs | grep athenaodbc
   ```

   Depending on your system, the output can look like one of the following.

   ```
   com.amazon.athenaodbc-x86_64.Config
   com.amazon.athenaodbc-x86_64.Driver
   ```

   or

   ```
   com.amazon.athenaodbc-arm64.Config
   com.amazon.athenaodbc-arm64.Driver
   ```

## Configuring a data source name on macOS
<a name="odbc-v2-driver-getting-started-macos-configuring-a-data-source-name-on-macos"></a>

After the driver is installed, you can find example `.odbc.ini` and `.odbcinst.ini` files in the following locations:
+ Intel processor computers: `/opt/athena/odbc/x86_64/ini/`
+ ARM processor computers: `/opt/athena/odbc/arm64/ini/`

Use the `.ini` files in this location as examples for configuring the Amazon Athena ODBC driver and data source name (DSN).

**Note**  
By default, ODBC driver managers use the hidden configuration files `.odbc.ini` and `.odbcinst.ini`, which are located in the home directory.

To specify the path to the `.odbc.ini` and `.odbcinst.ini` files using the iODBC driver manager, perform the following steps.

**To specify ODBC `.ini` file locations using iODBC driver manager**

1. Set `ODBCINI` to the full path and file name of the `odbc.ini` file.
   + For macOS computers that have Intel processors, use the following syntax.

     ```
     export ODBCINI=/opt/athena/odbc/x86_64/ini/odbc.ini
     ```
   + For macOS computers that have ARM processors, use the following syntax.

     ```
     export ODBCINI=/opt/athena/odbc/arm64/ini/odbc.ini
     ```

1. Set `ODBCSYSINI` to the full path and file name of the `odbcinst.ini` file.
   + For macOS computers that have Intel processors, use the following syntax.

     ```
     export ODBCSYSINI=/opt/athena/odbc/x86_64/ini/odbcinst.ini
     ```
   + For macOS computers that have ARM processors, use the following syntax.

     ```
     export ODBCSYSINI=/opt/athena/odbc/arm64/ini/odbcinst.ini
     ```

1. If you want to use a data source name (DSN) to connect to your data store, configure the `odbc.ini` file to define data source names (DSNs). Set the properties in the `odbc.ini` file to create a DSN that specifies the connection information for your data store, as in the following example.

   ```
   [ODBC Data Sources]
   athena_odbc_test=Amazon Athena ODBC (x64) 
   
   [ATHENA_WIDE_SETTINGS] # Special DSN-name to signal driver about logging configuration.
   LogLevel=0             # set to 1 to enable ODBC driver logs
   UseAwsLogger=0         # set to 1 to enable AWS-SDK logs
   LogPath=/opt/athena/odbc/logs/ # Path to store the log files. Permissions to the location are required. 
   
   [athena_odbc_test]
   Description=Amazon Athena ODBC (x64)
   # For ARM:
   Driver=/opt/athena/odbc/arm64/lib/libathena-odbc-arm64.dylib
   # For Intel:
   # Driver=/opt/athena/odbc/x86_64/lib/libathena-odbc-x86_64.dylib
   AwsRegion=us-west-1
   Workgroup=primary
   Catalog=AwsDataCatalog
   Schema=default
   AuthenticationType=IAM Credentials
   UID=
   PWD=
   S3OutputLocation=s3://amzn-s3-demo-bucket/
   ```

1. Configure the `odbcinst.ini` file, as in the following example.

   ```
   [ODBC Drivers]
   Amazon Athena ODBC (x64)=Installed 
   
   [Amazon Athena ODBC (x64)]
   # For ARM:
   Driver=/opt/athena/odbc/arm64/lib/libathena-odbc-arm64.dylib
   Setup=/opt/athena/odbc/arm64/lib/libathena-odbc-arm64.dylib
   # For Intel:
   # Driver=/opt/athena/odbc/x86_64/lib/libathena-odbc-x86_64.dylib
   # Setup=/opt/athena/odbc/x86_64/lib/libathena-odbc-x86_64.dylib
   ```

1. After you install and configure the Amazon Athena ODBC driver, use the `iodbctest` command-line tool to verify the connection, as in the following example.

   ```
   username@ % iodbctest
   iODBC Demonstration program
   This program shows an interactive SQL processor
   Driver Manager: 03.52.1623.0502 
   
   Enter ODBC connect string (? shows list): ? 
   
   DSN                              | Driver
   ------------------------------------------------------------------------------
   athena_odbc_test                 | Amazon Athena ODBC (x64) 
   
   Enter ODBC connect string (? shows list): DSN=athena_odbc_test;
   Driver: 2.0.2.1 (Amazon Athena ODBC Driver) 
   
   SQL>
   ```