# 使用 JDBC 连接器连接到 Aurora DSQL 集群
<a name="SECTION_program-with-jdbc-connector"></a>

[Aurora DSQL Connector for JDBC](https://github.com/awslabs/aurora-dsql-connectors/tree/main/java/jdbc) 设计为身份验证插件，该插件对 PostgreSQL JDBC 驱动程序的功能进行扩展，使应用程序能够使用 IAM 凭证向 Aurora DSQL 进行身份验证。该连接器不直接连接到数据库，而是在底层 PostgreSQL JDBC 驱动程序之上，提供无缝的 IAM 身份验证。

适用于 JDBC 的 Aurora DSQL 连接器设计为与 [PostgreSQL JDBC 驱动程序](https://github.com/pgjdbc/pgjdbc)配合使用，提供与 Aurora DSQL 的 IAM 身份验证要求的无缝集成。

适用于 JDBC 的 Aurora DSQL 连接器与 PostgreSQL JDBC 驱动程序结合使用，为 Aurora DSQL 实现了基于 IAM 的身份验证。该连接器引入了与 [AWS Identity and Access Management](https://aws.amazon.com/iam/)（IAM）等 AWS 身份验证服务的深度集成。

## 关于连接器
<a name="SECTION_program-with-jdbc-connector-about"></a>

Aurora DSQL 是一种分布式 SQL 数据库服务，面向兼容 PostgreSQL 的应用程序提供高可用性和可扩展性。Aurora DSQL 要求使用基于 IAM 的身份验证以及限时令牌，而现有 JDBC 驱动程序本身不支持这种方法。

设计适用于 JDBC 的 Aurora DSQL 连接器的主要理念是，在 PostgreSQL JDBC 驱动程序之上添加一个身份验证层来处理 IAM 令牌生成，使得用户无需更改现有 JDBC 工作流即可连接到 Aurora DSQL。

### 什么是 Aurora DSQL 身份验证？
<a name="SECTION_program-with-jdbc-connector-authentication"></a>

在 Aurora DSQL 中，**身份验证**包括：
+ **IAM 身份验证**：所有连接都使用基于 IAM 的身份验证和限时令牌
+ **令牌生成**：使用 AWS 凭证生成身份验证令牌，其生命周期可配置

适用于 JDBC 的 Aurora DSQL 连接器针对这些要求而设计，在建立连接时自动生成 IAM 身份验证令牌。

### 适用于 JDBC 的 Aurora DSQL 连接器的益处
<a name="SECTION_program-with-jdbc-connector-benefits"></a>

尽管 Aurora DSQL 提供了与 PostgreSQL 兼容的接口，但现有 PostgreSQL 驱动程序目前不支持 Aurora DSQL 的 IAM 身份验证要求。通过适用于 JDBC 的 Aurora DSQL 连接器，客户可以继续使用现有的 PostgreSQL 工作流，同时通过以下方式启用 IAM 身份验证：
+ **自动令牌生成**：使用 AWS 凭证自动生成 IAM 令牌
+ **无缝集成**：适用于现有 JDBC 连接模式
+ **AWS 凭证支持**：支持各种 AWS 凭证提供方（默认、基于配置文件等）

### 将适用于 JDBC 的 Aurora DSQL 连接器与连接池结合使用
<a name="SECTION_program-with-jdbc-connector-connection-pooling"></a>

适用于 JDBC 的 Aurora DSQL 连接器可与 HikariCP 等连接池库结合使用。连接器在建立连接期间处理 IAM 令牌生成，使得连接池可以正常操作。

## 主要 功能
<a name="SECTION_program-with-jdbc-connector-features"></a>

自动令牌生成  
IAM 令牌使用 AWS 凭证自动生成。

无缝集成  
使用现有 JDBC 连接模式而无需更改工作流。

AWS 凭证支持  
支持各种 AWS 凭证提供方（默认、基于配置文件等）。

连接池兼容性  
与 HikariCP 等连接池库无缝结合使用。

## 先决条件
<a name="SECTION_program-with-jdbc-connector-prerequisites"></a>

在开始之前，请确保您已完成以下先决条件：
+ [在 Aurora DSQL 中创建集群](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)。
+ 安装 Java 开发工具包（JDK）。请确保您使用的是版本 17 或更高版本。
+ 设置适当的 IAM 权限，以允许应用程序连接到 Aurora DSQL。
+ 已配置 AWS 凭证（通过 AWS CLI、环境变量或 IAM 角色）。

## 使用适用于 JDBC 的 Aurora DSQL 连接器
<a name="SECTION_program-with-jdbc-connector-usage"></a>

要在 Java 应用程序中使用适用于 JDBC 的 Aurora DSQL 连接器，请按照以下步骤操作：

1. 将以下依赖项添加到您的 Maven 项目中。

   ```
   <dependencies>
       <!-- Aurora DSQL Connector for JDBC -->
       <dependency>
           <groupId>software.amazon.dsql</groupId>
           <artifactId>aurora-dsql-jdbc-connector</artifactId>
           <version>1.0.0</version>
       </dependency>
   </dependencies>
   ```

   对于 Gradle 项目，请添加此依赖项：

   ```
   implementation("software.amazon.dsql:aurora-dsql-jdbc-connector:1.0.0")
   ```

1. 使用 AWS DSQL PostgreSQL 连接器格式，创建与 Aurora DSQL 集群的基本连接：

   ```
   import java.sql.Connection;
   import java.sql.DriverManager;
   import java.sql.ResultSet;
   import java.sql.SQLException;
   import java.sql.Statement;
   
   public class DsqlJdbcConnectorExample {
       public static void main(String[] args) {
           // Using AWS DSQL PostgreSQL Connector prefix
           String jdbcUrl = "jdbc:aws-dsql:postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin";
           
           try (Connection connection = DriverManager.getConnection(jdbcUrl)) {
               // Use the connection
               try (Statement statement = connection.createStatement()) {
                   // Create a table
                   statement.execute("CREATE TABLE IF NOT EXISTS test_table (id UUID PRIMARY KEY DEFAULT gen_random_uuid(), name VARCHAR(100))");
                   
                   // Insert data
                   statement.execute("INSERT INTO test_table (name) VALUES ('Test Name')");
                   
                   // Query data
                   try (ResultSet resultSet = statement.executeQuery("SELECT * FROM test_table")) {
                       while (resultSet.next()) {
                           System.out.println("ID: " + resultSet.getInt("id") + ", Name: " + resultSet.getString("name"));
                       }
                   }
               }
               
           } catch (SQLException e) {
               e.printStackTrace();
           }
       }
   }
   ```

### 配置属性
<a name="SECTION_program-with-jdbc-connector-properties"></a>

适用于 JDBC 的 Aurora DSQL 连接器支持以下连接属性：

用户  
确定连接的用户以及使用的令牌生成方法。示例：`admin`

token-duration-secs  
令牌的有效期长度，以秒为单位。有关令牌限制的更多信息，请参阅[在 Amazon Aurora DSQL 中生成身份验证令牌](SECTION_authentication-token.md)。

配置文件  
用于实例化 ProfileCredentialsProvider，来通过提供的配置文件名称生成令牌。

region  
用于 Aurora DSQL 连接的 AWS 区域。这是可选的。提供此项时，将覆盖从 URL 中提取的区域。

database  
要连接的数据库的名称。默认值为 `postgres`。

### 日志记录
<a name="SECTION_program-with-jdbc-connector-logging"></a>

启用日志记录功能，用于对使用 Aurora DSQL JDBC 连接器时可能遇到的任何问题进行故障排除。

该连接器使用 Java 的内置日志记录系统（java.util.logging）。您可以通过创建 `logging.properties` 文件来配置日志记录级别：

```
# Set root logger level to INFO for clean output
.level = INFO

# Show Aurora DSQL Connector for JDBC FINE logs for detailed debugging
software.amazon.dsql.level = FINE

# Console handler configuration
handlers = java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level = FINE
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

# Detailed formatter pattern with timestamp and logger name
java.util.logging.SimpleFormatter.format = %1$tH:%1$tM:%1$tS.%1$tL [%4$s] %3$s - %5$s%n
```

### 示例
<a name="SECTION_program-with-jdbc-connector-examples"></a>

有关更全面的示例和使用案例，请参阅[适用于 JDBC 的 Aurora DSQL 连接器存储库](https://github.com/awslabs/aurora-dsql-connectors/tree/main/java/jdbc/examples)