本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 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 身分驗證。

Aurora DSQL Connector for JDBC 旨在與 [PostgreSQL JDBC 驅動程式](https://github.com/pgjdbc/pgjdbc)搭配使用，並提供與 Aurora DSQL IAM 身分驗證需求的無縫整合。

搭配 PostgreSQL JDBC 驅動程式，適用於 JDBC 的 Aurora DSQL 連接器可啟用 Aurora DSQL 的 IAM 型身分驗證。它引入了與 AWS 身分驗證服務的深度整合，例如 [AWS Identity and Access Management](https://aws.amazon.com/iam/)(IAM)。

## 關於連接器
<a name="SECTION_program-with-jdbc-connector-about"></a>

Aurora DSQL 是一種分散式 SQL 資料庫服務，可為 PostgreSQL 相容應用程式提供高度可用性和可擴展性。Aurora DSQL 需要 IAM 型身分驗證，其具備現有 JDBC 驅動器未原生支援的時間限制權杖。

Aurora DSQL Connector for JDBC 背後的主要概念是在處理產生 IAM 字符的 PostgreSQL JDBC 驅動程式上新增身分驗證層，讓使用者在不變更現有 JDBC 工作流程的情況下連線到 Aurora DSQL。

### 什麼是 Aurora DSQL 身分驗證？
<a name="SECTION_program-with-jdbc-connector-authentication"></a>

在 Aurora DSQL 中，**身分驗證**涉及：
+ **IAM 身分驗證**：所有連線都使用具有時間限制權杖的 IAM 型身分驗證
+ **權杖產生**：使用 AWS 登入資料產生身分驗證權杖，並具有可設定的生命週期

Aurora DSQL Connector for JDBC 旨在了解這些要求，並在建立連線時自動產生 IAM 身分驗證字符。

### Aurora DSQL Connector for JDBC 的優點
<a name="SECTION_program-with-jdbc-connector-benefits"></a>

雖然 Aurora DSQL 提供 PostgreSQL 相容介面，但現有 PostgreSQL 驅動程式尚不支援 Aurora DSQL 的 IAM 身分驗證要求。Aurora DSQL Connector for JDBC 可讓客戶繼續使用其現有的 PostgreSQL 工作流程，同時透過下列方式啟用 IAM 身分驗證：
+ **自動產生字符**：使用 AWS 登入資料自動產生 IAM 字符
+ **無縫整合**：適用於現有的 JDBC 連線模式
+ **AWS 登入資料支援**：支援各種 AWS 登入資料提供者 （預設、設定檔型等）

### 使用適用於 JDBC 的 Aurora DSQL 連接器搭配連線集區
<a name="SECTION_program-with-jdbc-connector-connection-pooling"></a>

Aurora DSQL Connector for JDBC 適用於連線集區程式庫，例如 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 Connector，請遵循下列步驟：

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. 使用 DSQL PostgreSQL 連接器格式建立 Aurora AWS 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>

Aurora DSQL Connector for JDBC 支援下列連線屬性：

user  
決定連線的使用者，以及使用權杖的產生方式。範例：`admin`

token-duration-secs  
權杖有效性的持續時間，以秒為單位。如需更多有關權杖限制的詳細資訊，請參閱[在 Amazon Aurora DSQL 中產生身分驗證權杖](SECTION_authentication-token.md)。

profile  
用於將 ProfileCredentialsProvider 執行個體化，以使用所提供的設定檔名稱產生權杖。

region  
AWS Aurora DSQL 連線的區域。這是選用的。在提供時，會覆寫從 URL 擷取的區域。

資料庫  
要連線的資料庫名稱。預設值為 `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>

如需更完整的範例和使用案例，請參閱 [Aurora DSQL Connector for JDBC 儲存庫](https://github.com/awslabs/aurora-dsql-connectors/tree/main/java/jdbc/examples)