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

使用 Ruby 連接器連接到 Aurora DSQL 叢集

Aurora DSQL Connector for Ruby 是建置在 pg 上的 Ruby 連接器，整合將 Ruby 應用程式連線至 Amazon Aurora DSQL 叢集的 IAM 身分驗證。

連接器會處理字符產生、SSL 組態和連線集區，讓您可以專注於應用程式邏輯。

關於連接器

Amazon Aurora DSQL 需要使用現有 Ruby PostgreSQL 驅動程式原生不支援的時間限制字符進行 IAM 身分驗證。Aurora DSQL Connector for Ruby 在處理 IAM 字符產生的 pg Gem 上新增了身分驗證層，可讓您連線到 Aurora DSQL，而無需變更現有的 pg 工作流程。

什麼是 Aurora DSQL 身分驗證？

在 Aurora DSQL 中，身分驗證涉及：

Aurora DSQL Connector for Ruby 了解這些要求，並在建立連線時自動產生 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

進階用量

主機組態

連接器同時支援完整叢集端點 （自動偵測區域） 和叢集 IDs（需要區域）：

# 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)。當兩個交易修改相同的資料時，第一個遞交獲勝，第二個收到 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 也接受pool:關鍵字，其中包含您直接傳遞給 的選項雜湊ConnectionPool.new。如果您省略 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 的身分驗證和授權。

管理員與一般使用者