# Java JDBC 用 Aurora DSQL コネクタ
<a name="SECTION_program-with-jdbc-connector"></a>

[JDBC 用 Aurora DSQL コネクタ](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 認証要件とシームレスに統合できます。

PostgreSQL JDBC ドライバーと組み合わせて、JDBC 用 Aurora DSQL コネクタは 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 は、PostgreSQL 互換アプリケーションに高可用性とスケーラビリティを提供する分散 SQL データベースサービスです。Aurora DSQL には、既存の JDBC ドライバーがネイティブにサポートしていない時間制限付きトークンを使用した IAM ベースの認証が必要です。

JDBC 用 Aurora DSQL コネクタの主な考え方は、IAM トークン生成を処理する PostgreSQL JDBC ドライバーの上に認証レイヤーを追加することです。これにより、ユーザーは既存の 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 コネクタを使用すると、以下の方法で IAM 認証を有効にしながら、既存の PostgreSQL ワークフローを引き続き使用できます。
+ **自動トークン生成**: IAM トークンは AWS 認証情報を使用して自動的に生成されます
+ **シームレスな統合**: 既存の 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 以上であることを確認します。
+ アプリケーションが Aurora DSQL に接続できるように、適切な IAM アクセス許可を設定します。
+ 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)」を参照してください。

profile  
指定されたプロファイル名を使用したトークン生成用の ProfileCredentialsProvider をインスタンス化するために使用されます。

リージョン  
Aurora DSQL 接続の AWS リージョン。これは省略可能です。指定された場合、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>

より包括的な例とユースケースについては、以下を含む「[JDBC 用 Aurora DSQL コネクタレポジトリ](https://github.com/awslabs/aurora-dsql-connectors/tree/main/java/jdbc/examples)」を参照してください。