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

# 適用於 Ruby 的 Aurora DSQL 連接器 pg
<a name="SECTION_program-with-dsql-connector-for-ruby-pg"></a>

[Aurora DSQL Connector for Ruby](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg) 是建置在 [pg](https://github.com/ged/ruby-pg) 上的 Ruby 連接器，整合將 Ruby 應用程式連線至 Amazon Aurora DSQL 叢集的 IAM 身分驗證。

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

## 關於連接器
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-about"></a>

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

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

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

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

**主機組態**

連接器同時支援完整叢集端點 （自動偵測區域） 和叢集 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
```

**警告**  
`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>


| 欄位 | Type | 預設 | Description | 
| --- | --- | --- | --- | 
| 託管 | String | （必要） | 叢集端點或叢集 ID | 
| region | String | （自動偵測） | AWS region；如果主機是叢集 ID，則為必要 | 
| user | String | 「管理員」 | 資料庫使用者 | 
| 資料庫 | String | 「postgres」 | 資料庫名稱 | 
| port | Integer | 5432 | Database port (資料庫連線埠) | 
| profile | String | nil | AWS 登入資料的設定檔名稱 | 
| token\$1duration | Integer | 900 (15 分鐘） | 字符有效性持續時間，以秒為單位 （允許上限：1 週，預設值：15 分鐘） | 
| credentials\$1provider | Aws：：Credentials | nil | 自訂登入資料供應商 | 
| max\$1lifetime | Integer | 3300 (55 分鐘） | 最長連線生命週期，以秒為單位 | 
| application\$1name | String | nil | application\$1name 的 ORM 字首 | 
| 記錄器 | Logger | nil | OCC 重試警告的記錄器 | 
| occ\$1max\$1retries | Integer | nil （已停用） | 上的最大 OCC 重試次數pool.with；設定時啟用重試次數 | 

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

## 身分驗證
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-auth"></a>

連接器會自動處理 Aurora DSQL 身分驗證，方法是使用 AWS 登入資料產生字符。如果您未提供區域，連接器會從主機名稱剖析該 AWS 區域。

如需 Aurora DSQL 中身分驗證的詳細資訊，請參閱 [Aurora DSQL 的身分驗證和授權](authentication-authorization.md)。

### 管理員與一般使用者
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-admin-vs-regular"></a>
+ 名為「admin」的使用者會自動使用管理員身分驗證字符
+ 所有其他使用者都使用一般身分驗證字符
+ 連接器會為每個連線動態產生權杖