# 使用 Ruby 连接器连接到 Aurora DSQL 集群
<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 连接器，它集成了 IAM 身份验证功能，用于将 Ruby 应用程序连接到 Amazon Aurora DSQL 集群。

此连接器处理令牌生成、SSL 配置和连接池，因此您可以专注于应用程序逻辑。

## 关于连接器
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-about"></a>

Amazon Aurora DSQL 要求使用 IAM 身份验证以及限时令牌，而现有 Ruby PostgreSQL 驱动程序并不原生支持这种方法。适用于 Ruby 的 Aurora DSQL 连接器在 pg gem 之上添加一个身份验证层来处理 IAM 令牌生成，使您无需更改现有 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 工作流程结合使用
+ **连接池**：通过 `connection_pool` gem 提供内置支持，具有 max\$1lifetime 强制执行
+ **区域自动检测**：从 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
```

## 用法
<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）。当两个事务修改相同的数据时，提交的第一个事务获胜，第二个事务收到 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>


| 字段 | 类型 | 默认值 | 说明 | 
| --- | --- | --- | --- | 
| host | 字符串 | （必需） | 集群端点或集群 ID | 
| region | 字符串 | （自动检测） | AWS 区域；如果主机是集群 ID，则为必需 | 
| 用户 | 字符串 | “admin” | 数据库用户 | 
| database | 字符串 | “postgres” | 数据库名称 | 
| 端口 | 整数 | 5432 | 数据库端口 | 
| 配置文件 | 字符串 | nil | 凭证的 AWS 配置文件名称 | 
| token\$1duration | 整数 | 900（15 分钟） | 令牌有效期以秒为单位（支持的最长时间：1 周，默认值：15 分钟） | 
| credentials\$1provider | Aws::Credentials | nil | 自定义凭证提供商 | 
| max\$1lifetime | 整数 | 3300（55 分钟） | 最大连接生命周期，以秒为单位 | 
| application\$1name | 字符串 | nil | application\$1name 的 ORM 前缀 | 
| 日志记录程序 | 记录器 | nil | OCC 重试警告的记录器 | 
| occ\$1max\$1retries | 整数 | nil（已禁用） | pool.with 上的 OCC 最大重试次数；设置后启用重试 | 

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

该连接器通过使用 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”的用户会自动使用管理员身份验证令牌
+ 所有其他用户都使用普通身份验证令牌
+ 该连接器为每个连接动态生成令牌