Ruby コネクタを使用した Aurora DSQL クラスターへの接続

Ruby 用 Aurora DSQL コネクタは、Ruby アプリケーションを Amazon Aurora DSQL クラスターに接続するための IAM 認証を統合した pg 上に構築された Ruby コネクタです。

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

コネクタについて

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

Aurora DSQL 認証とは

Aurora DSQL では、認証に以下が含まれます。

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

機能

サンプルアプリケーション

詳細な例については、GitHub のサンプルアプリケーションを参照してください。

クイックスタートガイド

要件

インストール

Gemfile に追加:

gem "aurora-dsql-ruby-pg"

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

gem install aurora-dsql-ruby-pg

Usage

プール接続

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

シングル接続

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

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

高度な使用法

ホスト設定

コネクタは、完全なクラスターエンドポイント (リージョンの自動検出) とクラスター 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

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

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

設定オプション

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 }
)

認証

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

Aurora DSQL の認証の詳細については、「Aurora DSQL の認証および認可」を参照してください。

管理者ユーザーと通常のユーザー