# 开始使用 ODBC 2.x 驱动程序
<a name="odbc-v2-driver-getting-started"></a>

使用本节中的信息开始使用 Amazon Athena ODBC 2.x 驱动程序。Windows、Linux 和 macOS 操作系统均支持该驱动程序。

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

若想使用 Windows 客户端计算机访问 Amazon Athena，则需要 Amazon Athena ODBC 驱动程序。

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

在可以直接访问 Amazon Athena 数据库的客户端计算机上安装 Amazon Athena ODBC 驱动程序，而无需使用 Web 浏览器。

所用的 Windows 系统必须满足以下要求：
+ 你具有管理员权限
+ 以下操作系统之一：
  + Windows 11、10 或 8.1
  + Windows Server 2019、2016 或 2012
  + 支持的处理器架构：x86\$164（64 位）
+ 至少 100 MB 可用磁盘空间
+ 已安装适用于 64 位 Windows 的 [Microsoft Visual C\$1\$1 Redistributable for Visual Studio](https://visualstudio.microsoft.com/downloads/#microsoft-visual-c-redistributable-for-visual-studio-2022)。

## 安装 Amazon Athena ODBC 驱动程序
<a name="odbc-v2-driver-installing"></a>

**下载并安装适用于 Windows 的 Amazon Athena ODBC 驱动程序**

1. [下载](odbc-v2-driver.md#odbc-v2-driver-download) `AmazonAthenaODBC-2.x.x.x.msi` 安装文件。

1. 启动安装文件，然后选择**下一步**。

1. 要接受许可协议条款，选中复选框，然后选择**下一步**。

1. 要更改安装位置，选择**浏览**，浏览到所需的文件夹，然后选择**确定**。

1. 要接受安装位置，选择**下一步**。

1. 选择**安装**。

1. 在安装完成时，选择**完成**。

## 设置驱动程序配置选项的方法
<a name="odbc-v2-driver-ways-to-set-options"></a>

要在 Windows 中控制 Amazon Athena ODBC 驱动程序的行为，可通过以下方式设置驱动程序配置选项：
+ 配置数据来源名称（DSN）时，在 **ODBC 数据来源管理器**程序中。
+ 通过在以下位置添加或更改 Windows 注册表项：

  ```
  HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\YOUR_DSN_NAME
  ```
+ 在以编程方式连接时，通过在连接字符串中设置驱动程序选项。

## 在 Windows 上配置数据来源名称
<a name="odbc-v2-driver-configuring-dsn-on-windows"></a>

在下载并安装 ODBC 驱动程序后，必须将数据来源名称（DSN）条目添加到客户端计算机或 Amazon EC2 实例。SQL 客户端工具将使用此数据来源连接和查询 Amazon Athena。

**创建系统 DSN 条目**

1. 在 Windows 的**开始**菜单中，右键单击 **ODBC 数据来源（64 位）**，然后选择**更多**、**以管理员身份运行**。

1. 在 **ODBC 数据来源管理器**中，选择**驱动程序**选项卡。

1. 在**名称**列中，确认是否存在 **Amazon Athena ODBC（x64）**。

1. 请执行以下操作之一：
   + 要为计算机上的所有用户配置驱动程序，选择**系统 DSN** 选项卡。由于使用不同账户加载数据的应用程序可能检测不到来自其他账户的用户 DSN，因而建议使用系统 DSN 配置选项。
**注意**  
要使用**系统 DSN** 选项，需要管理权限。
   + 要仅为您的用户账户配置驱动程序，选择**用户 DSN** 选项卡。

1. 选择**添加**。随即打开**新建数据来源**对话框。

1. 选择 **Amazon Athena ODBC（x64）**，然后选择**完成**。

1. 在 **Amazon Athena ODBC 配置**对话框中，输入以下信息。有关这些选项的详细信息，请参阅 [主要 ODBC 2.x 连接参数](odbc-v2-driver-main-connection-parameters.md)。
   + 在**数据来源名称**中，输入要用于识别数据来源的名称。
   + 对于**描述**，输入描述以帮助您识别数据来源。
   + 在**区域**中，输入要在其中使用 Athena 的 AWS 区域 名称（例如，** us-west-1**）。
   + 在**目录**中，输入 Amazon Athena 目录的名称。默认为 **AwsDataCatalog**，供 AWS Glue 使用。
   + 在**数据库**中，输入 Amazon Athena 数据库的名称。默认为**默认**。
   + 对于**工作组**，输入 Amazon Athena 工作组的名称。默认为**主要**。
   + 对于 **S3 输出位置**，输入 Amazon S3 中存储查询结果的位置（例如 **s3://amzn-s3-demo-bucket/**）。
   + （可选）对于**加密选项**，选择一个加密选项。默认值为 `NOT_SET`。
   + （可选）对于 **KMS 密钥**，根据需要选择加密 KMS 密钥。

1. 要指定用于 IAM 身份验证的配置选项，选择**身份验证选项**。

1. 输入以下信息：
   + 对于**身份验证类型**，选择 **IAM 凭证**。这是默认值。有关可用身份验证类型的更多信息，请参阅 [身份验证选项](odbc-v2-driver-authentication-options.md)。
   + 对于**用户名**，输入用户名。
   + 对于**密码**，输入密码。
   + 对于**会话令牌**，如果要使用临时 AWS 凭证，则输入会话令牌。有关临时凭证的更多信息，请参阅《*IAM 用户指南*》中的[将临时凭证用于 AWS 资源](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html)。

1. 选择**确定**。

1. 在 **Amazon Athena ODBC 配置**对话框的底部，选择**测试**。如果客户端计算机成功连接到 Amazon Athena，则**连接测试**框会报告**连接成功**。否则，该框将报告**连接失败**并显示相应的错误信息。

1. 要关闭测试连接，选择**确定**。现在，您创建的数据来源在数据来源名称列表中显示。

## 在 Windows 上使用无 DSN 连接
<a name="odbc-v2-driver-dsn-less-connection"></a>

您可以使用无 DSN 连接来连接到没有数据来源名称（DSN）的数据库。以下示例显示了连接到 Amazon Athena 的 Amazon Athena ODBC（x64）ODBC 驱动程序的连接字符串。

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

若想使用 Linux 客户端计算机访问 Amazon Athena，则需要安装 Amazon Athena ODBC 驱动程序。

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

安装该驱动程序的每台 Linux 客户端计算机都必须满足以下要求。
+ 拥有根访问权限。
+ 使用以下 Linux 发行版之一：
  + Red Hat Enterprise Linux（RHEL）7 或 8
  + CentOS 7 或 8。
+ 有 100MB 可用磁盘空间。
+ 使用版本 2.3.1 或更高版本的 [unixODBC](https://www.unixodbc.org/)。
+ 使用版本 2.26 或更高版本的 [GNU C 库](https://www.gnu.org/software/libc/)（glibc）。

## 在 Linux 上安装 ODBC 数据连接器
<a name="odbc-v2-driver-getting-started-linux-installing-the-odbc-data-connector-on-linux"></a>

参照以下过程在 Linux 操作系统上安装 Amazon Athena ODBC 驱动程序。

**在 Linux 上安装 Amazon Athena ODBC 驱动程序**

1. 输入下列命令之一：

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

   或者

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

1. 安装完成后，输入以下命令之一，验证驱动程序是否安装成功：
   + 

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

     输出：

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

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

     输出：

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

## 在 Linux 上配置数据来源名称
<a name="odbc-v2-driver-getting-started-linux-configuring-a-data-source-name-on-linux"></a>

安装好驱动程序后，可以在以下位置找到示例 `.odbc.ini` 和 `.odbcinst.ini` 文件：
+ `/opt/athena/odbc/ini/`.

使用此位置中的 `.ini` 文件作为配置 Amazon Athena ODBC 驱动程序和数据来源名称（DSN）的示例。

**注意**  
默认情况下，ODBC 驱动程序管理器使用位于主目录中的隐藏配置文件 `.odbc.ini` 和 `.odbcinst.ini`。

要使用 unixODBC 指定 `.odbc.ini` 和 `.odbcinst.ini` 文件的路径，请执行以下步骤。

**使用 unixODBC 指定 ODBC `.ini` 文件的位置**

1. 将 `ODBCINI` 设置为 `odbc.ini` 文件的完整路径和文件名，如下例所示。

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

1. 将 `ODBCSYSINI` 设置为 `odbcinst.ini` 文件所在目录的完整路径，如下例所示。

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

1. 输入以下命令，验证是否使用 unixODBC 驱动程序管理器，并验证 `odbc*.ini` 文件是否正确：

   ```
   username % odbcinst -j
   ```

   示例输出

   ```
   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. 如果想要使用数据来源名称（DSN）连接到数据存储，请配置 `odbc.ini` 文件来定义数据源名称（DSN）。设置 `odbc.ini` 文件中的属性，以便创建指定数据存储连接信息的 DSN，如下例所示。

   ```
   [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. 配置 `odbcinst.ini` 文件，如下例所示。

   ```
   [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. 安装并配置 Amazon Athena ODBC 驱动程序后，使用 unixODBC `isql` 命令行工具来验证连接，如下例所示。

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

## 验证 ODBC 驱动程序签名
<a name="verify-odbc-linux-signature"></a>

**重要**  
我们建议在您的计算机上安装 Athena ODBC 驱动程序 RPM 签名之前对其进行验证。

请按照以下步骤验证 Athena ODBC 驱动程序 RPM 包的签名：

1. **准备模板**

   使用适当的公有密钥、RPM 签名以及指向 Amazon S3 存储桶中托管的 RPM 脚本的相应访问链接来准备命令。您必须将以下内容下载到设备上。
   +  [Athena ODBC 驱动程序](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Linux/AmazonAthenaODBC-2.1.0.0.rpm) 
   +  [公有密钥](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Linux/public_key.pem) 
   +  [Athena ODBC RPM 签名](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Linux/signature.bin) 

1. 将 Athena ODBC 驱动程序、公有密钥和 Athena ODBC RPM 签名下载到设备上。

1. 运行以下命令来验证 ODBC 驱动程序签名：

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

   如果通过验证，您将看到类似 `Verified OK` 的消息。这意味着现在可以继续安装 Athena ODBC 驱动程序。

   如果失败并显示消息 `Verification Failure`，则意味着 RPM 上的签名已被篡改。确保步骤 1 中提到的所有三个文件都存在、路径指定正确并且文件自下载以来未被修改，然后重试验证过程。

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

若想使用 macOS 客户端计算机访问 Amazon Athena，则需要安装 Amazon Athena ODBC 驱动程序。

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

安装该驱动程序的每台 macOS 计算机都必须满足以下要求。
+ 使用 macOS 版本 14 或更高版本。
+ 有 100MB 可用磁盘空间。
+ 使用版本 3.52.16 或更高版本的 [iODBC](https://www.iodbc.org/dataspace/doc/iodbc/wiki/iodbcWiki/WelcomeVisitors)。

## 在 macOS 上安装 ODBC 数据连接器
<a name="odbc-v2-driver-getting-started-macos-installing-the-odbc-data-connector-on-macos"></a>

参照以下过程下载并安装适用于 macOS 操作系统的 Amazon Athena ODBC 驱动程序。

**下载并安装适用于 macOS 的 Amazon Athena ODBC 驱动程序**

1. 下载 `.pkg` 包文件。

1. 双击 `.pkg` 文件。

1. 按照向导中的步骤安装驱动程序。

1. 在**许可协议**页面上，按**继续**，然后选择**同意**。

1. 选择**安装**。

1. 在安装完成时，选择**完成**。

1. 输入以下命令，验证是否已安装驱动程序：

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

   输出因系统而异，具体内容如下。

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

   或者

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

## 在 macOS 上配置数据来源名称
<a name="odbc-v2-driver-getting-started-macos-configuring-a-data-source-name-on-macos"></a>

安装好驱动程序后，可以在以下位置找到示例 `.odbc.ini` 和 `.odbcinst.ini` 文件：
+ 英特尔处理器计算机：`/opt/athena/odbc/x86_64/ini/`
+ ARM 处理器计算机：`/opt/athena/odbc/arm64/ini/`

使用此位置中的 `.ini` 文件作为配置 Amazon Athena ODBC 驱动程序和数据来源名称（DSN）的示例。

**注意**  
默认情况下，ODBC 驱动程序管理器使用位于主目录中的隐藏配置文件 `.odbc.ini` 和 `.odbcinst.ini`。

要使用 iODBC 驱动程序管理器指定 `.odbc.ini` 和 `.odbcinst.ini` 文件的路径，请执行以下步骤。

**使用 iODBC 驱动程序管理器指定 ODBC `.ini` 文件位置**

1. 将 `ODBCINI` 设置到 `odbc.ini` 文件的完整路径和文件名。
   + 对于配备了英特尔处理器的 macOS 计算机，请使用以下语法。

     ```
     export ODBCINI=/opt/athena/odbc/x86_64/ini/odbc.ini
     ```
   + 对于配备了 ARM 处理器的 macOS 计算机，请使用以下语法。

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

1. 将 `ODBCSYSINI` 设置到 `odbcinst.ini` 文件的完整路径和文件名。
   + 对于配备了英特尔处理器的 macOS 计算机，请使用以下语法。

     ```
     export ODBCSYSINI=/opt/athena/odbc/x86_64/ini/odbcinst.ini
     ```
   + 对于配备了 ARM 处理器的 macOS 计算机，请使用以下语法。

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

1. 如果想要使用数据来源名称（DSN）连接到数据存储，请配置 `odbc.ini` 文件来定义数据源名称（DSN）。设置 `odbc.ini` 文件中的属性，以便创建指定数据存储连接信息的 DSN，如下例所示。

   ```
   [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. 配置 `odbcinst.ini` 文件，如下例所示。

   ```
   [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. 安装并配置 Amazon Athena ODBC 驱动程序后，使用 `iodbctest` 命令行工具来验证连接，如下例所示。

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