# Ruby コネクタを使用した Aurora DSQL クラスターへの接続
<a name="SECTION_program-with-dsql-connector-for-ruby-pg"></a>

[Ruby 用 Aurora DSQL コネクタ](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg)は、Ruby アプリケーションを Amazon Aurora DSQL クラスターに接続するための IAM 認証を統合した [pg](https://github.com/ged/ruby-pg) 上に構築された Ruby コネクタです。

このコネクタは、トークン生成、SSL 設定、接続プーリングを処理し、ユーザーがアプリケーションロジックに集中できるようにします。

## コネクタについて
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-about"></a>

Amazon Aurora DSQL には、既存の Ruby PostgreSQL ドライバーがネイティブにサポートしていない時間制限付きトークンを使用する IAM 認証が必要です。Ruby 用 Aurora DSQL コネクタは、IAM トークン生成を処理する pg gem 上に認証レイヤーを追加し、既存の pg ワークフローを変更せずに Aurora DSQL に接続できるようにします。

### Aurora DSQL 認証とは
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-authentication"></a>

Aurora DSQL では、**認証**に以下が含まれます。
+ **IAM 認証**: すべての接続で、時間制限付きトークンによる IAM ベースの認証が使用されます
+ **トークン生成**: コネクタは AWS 認証情報を使用して認証トークンを生成します。これらのトークンの有効期間は設定可能です。

Ruby 用 Aurora DSQL コネクタは、これらの要件を理解し、接続の確立時に IAM 認証トークンを自動的に生成します。

### 機能
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-features"></a>
+ **自動 IAM 認証** - Aurora DSQL トークンの生成と更新を処理
+ **pg 上に構築** - Ruby 用の一般的な PostgreSQL Gem をラップ
+ **シームレスな統合** - 既存の pg gem ワークフローと連携
+ **接続プーリング** - max\$1lifetime の適用による `connection_pool` gem を介した組み込みサポート
+ **リージョンの自動検出** - Aurora DSQL クラスターホスト名から AWS リージョンを抽出
+ **AWS 認証情報のサポート**: AWS プロファイルとカスタム認証情報プロバイダーをサポート
+ **OCC 再試行** - エクスポネンシャルバックオフを使用したオプトインのオプティミスティック同時実行制御の再試行

## サンプルアプリケーション
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-example-application"></a>

詳細な例については、GitHub の[サンプルアプリケーション](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg/example)を参照してください。

## クイックスタートガイド
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-quick-start"></a>

### 要件
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-requirements"></a>
+ Ruby 3.1 以降
+ [Aurora DSQL クラスターへのアクセス](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ AWS 認証情報の設定 (AWS CLI、環境変数、または IAM ロール経由)。

## インストール
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-installation"></a>

Gemfile に追加:

```
gem "aurora-dsql-ruby-pg"
```

または直接インストール:

```
gem install aurora-dsql-ruby-pg
```

## Usage
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-usage"></a>

### プール接続
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-pool-connection"></a>

```
require "aurora_dsql_pg"

# Create a connection pool with OCC retry enabled
pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws",
  occ_max_retries: 3
)

# Read
pool.with do |conn|
  result = conn.exec("SELECT 'Hello, DSQL!'")
  puts result[0]["?column?"]
end

# Write — you must wrap writes in a transaction
pool.with do |conn|
  conn.transaction do
    conn.exec_params("INSERT INTO users (id, name) VALUES (gen_random_uuid(), $1)", ["Alice"])
  end
end

pool.shutdown
```

### シングル接続
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-single-connection"></a>

シンプルなスクリプトの場合、または接続プーリングが必要ない場合。

```
conn = AuroraDsql::Pg.connect(host: "your-cluster.dsql.us-east-1.on.aws")
conn.exec("SELECT 1")
conn.close
```

### 高度な使用法
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-advanced"></a>

**ホスト設定**

コネクタは、完全なクラスターエンドポイント (リージョンの自動検出) とクラスター ID (リージョンが必要) の両方をサポートしています。

```
# Full endpoint (region auto-detected)
pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws"
)

# Cluster ID (region required)
pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster-id",
  region: "us-east-1"
)
```

**AWS プロファイル**

認証情報の AWS プロファイルを指定します。

```
pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws",
  profile: "production"
)
```

**接続文字列形式**

コネクタは、PostgreSQL 接続文字列形式をサポートしています。

```
postgres://[user@]host[:port]/[database][?param=value&...]
postgresql://[user@]host[:port]/[database][?param=value&...]
```

サポートされているクエリパラメータ: `region`、`profile`、`tokenDurationSecs`。

```
# Full endpoint with profile
pool = AuroraDsql::Pg.create_pool(
  "postgres://admin@cluster.dsql.us-east-1.on.aws/postgres?profile=dev"
)
```

**OCC 再試行**

Aurora DSQL は、オプティミスティック同時実行制御 (OCC) を使用します。2 つのトランザクションが同じデータを変更する場合、最初のトランザクションはコミットに成功し、2 番目のトランザクションは OCC エラーを受け取ります。

OCC 再試行はオプトインです。プールの作成時に `occ_max_retries` を設定し、`pool.with` でエクスポネンシャルバックオフとジッターによる自動再試行を有効にします。

```
pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws",
  occ_max_retries: 3
)

pool.with do |conn|
  conn.transaction do
    conn.exec_params("UPDATE accounts SET balance = balance - $1 WHERE id = $2", [100, from_id])
    conn.exec_params("UPDATE accounts SET balance = balance + $1 WHERE id = $2", [100, to_id])
  end
end
```

**警告**  
`pool.with` は、ブロックをトランザクションに自動的にラップしません。書き込みオペレーションでは、`conn.transaction` を自分自身で呼び出す必要があります。OCC の競合では、コネクタがブロック全体を再実行するため、データベースオペレーションのみが含まれ、安全に再試行できることが必要です。

個々の呼び出しの再試行をスキップするには、`retry_occ: false` を渡します。

```
pool.with(retry_occ: false) do |conn|
  conn.exec("SELECT 1")
end
```

## 設定オプション
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-configuration"></a>


| フィールド | タイプ | デフォルト  | 説明  | 
| --- | --- | --- | --- | 
| ホスト | String | (必須) | クラスターエンドポイントまたはクラスター ID | 
| リージョン | String | (自動検出) | AWS リージョン (host がクラスター ID の場合は必須) | 
| ユーザー | String | 「admin」 | データベースユーザー | 
| データベース | String | 「postgres」 | データベース名 | 
| ポート | 整数 | 5432 | データベースポート | 
| profile | String | nil | 認証情報の AWS プロファイル名 | 
| token\$1duration | 整数 | 900 (15 分) | トークンの有効期間 (秒) (最大許容時間: 1 週間、デフォルト: 15 分) | 
| credentials\$1provider | Aws::Credentials | nil | カスタム認証情報プロバイダー | 
| max\$1lifetime | 整数 | 3300 (55 分) | 最大接続有効期間 (秒単位) | 
| application\$1name | String | nil | application\$1name の ORM プレフィックス | 
| ロガー | ロガー | nil | OCC 再試行警告のロガー | 
| occ\$1max\$1retries | 整数 | nil (無効) | pool.with での最大 OCC 再試行回数。設定すると再試行が有効化 | 

`create_pool` は、`ConnectionPool.new` に直接渡すオプションのハッシュを含む `pool:` キーワードも受け入れます。`pool:` を省略すると、コネクタはデフォルトで `{size: 5, timeout: 5}` になります。指定したキーは、これらの特定のデフォルトのみを上書きします。

```
pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws",
  pool: { size: 10, timeout: 10 }
)
```

## 認証
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-auth"></a>

コネクタは、AWS 認証情報を使用してトークンを生成することで、Aurora DSQL 認証を自動的に処理します。AWS リージョンを指定しない場合、コネクタはホスト名からリージョンを解析します。

Aurora DSQL の認証の詳細については、「[Aurora DSQL の認証および認可](authentication-authorization.md)」を参照してください。

### 管理者ユーザーと通常のユーザー
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-admin-vs-regular"></a>
+ 「admin」という名前のユーザーは、管理者認証トークンを自動的に使用します。
+ 他のすべてのユーザーは通常の認証トークンを使用します。
+ コネクタは、接続ごとにトークンを動的に生成します。