使用 Ruby 连接器连接到 Aurora DSQL 集群

Aurora DSQL Connector for Ruby 是一款基于 pg 构建的 Ruby 连接器，它集成了 IAM 身份验证功能，用于将 Ruby 应用程序连接到 Amazon Aurora DSQL 集群。

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

关于连接器

Amazon Aurora DSQL 要求使用 IAM 身份验证以及限时令牌，而现有 Ruby PostgreSQL 驱动程序并不原生支持这种方法。适用于 Ruby 的 Aurora DSQL 连接器在 pg gem 之上添加一个身份验证层来处理 IAM 令牌生成，使您无需更改现有 pg 工作流程即可连接到 Aurora DSQL。

什么是 Aurora DSQL 身份验证？

在 Aurora DSQL 中，身份验证包括：

适用于 Ruby 的 Aurora DSQL 连接器了解这些要求，并在建立连接时自动生成 IAM 身份验证令牌。

功能

示例应用程序

有关完整的示例，请参阅 GitHub 上的示例应用程序。

快速入门指南

要求

安装

添加到您的 Gemfile：

gem "aurora-dsql-ruby-pg"

或者直接安装：

gem install aurora-dsql-ruby-pg

用法

池连接

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）。当两个事务修改相同的数据时，提交的第一个事务获胜，第二个事务收到 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 的身份验证和授权。

管理员用户与普通用户