适用于 Rust SQLx 的 Aurora DSQL 连接器

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

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

关于连接器

适用于 Rust 的 Aurora DSQL 连接器在 SQLx 之上添加一个身份验证层来处理 IAM 令牌生成，使您无需更改现有 SQLx 工作流程即可连接到 Aurora DSQL。

什么是 Aurora DSQL 身份验证？

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

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

功能

示例应用程序

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

快速入门指南

要求

安装

添加到 Cargo.toml：

[dependencies]
aurora-dsql-sqlx-connector = "0.1.2"

对于大多数应用程序，请同时启用 pool 和 occ 功能：

[dependencies]
aurora-dsql-sqlx-connector = { version = "0.1.2", features = ["pool", "occ"] }

功能标志

用法

池连接

use sqlx::Row;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let pool = aurora_dsql_sqlx_connector::pool::connect(
        "postgres://admin@your-cluster.dsql.us-east-1.on.aws/postgres"
    ).await?;

    // Read
    let row = sqlx::query("SELECT 'Hello, DSQL!' as greeting")
        .fetch_one(&pool)
        .await?;
    let greeting: &str = row.get("greeting");
    println!("{}", greeting);

    // Write — you must wrap writes in a transaction
    let mut tx = pool.begin().await?;
    sqlx::query("INSERT INTO users (id, name) VALUES (gen_random_uuid(), $1)")
        .bind("Alice")
        .execute(&mut *tx)
        .await?;
    tx.commit().await?;

    pool.close().await;
    Ok(())
}

单一 连接

对于简单的脚本或当您不需要连接池时：

use sqlx::Row;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut conn = aurora_dsql_sqlx_connector::connection::connect(
        "postgres://admin@your-cluster.dsql.us-east-1.on.aws/postgres"
    ).await?;

    let row = sqlx::query("SELECT 1 as value")
        .fetch_one(&mut conn)
        .await?;
    let value: i32 = row.get("value");
    println!("Result: {}", value);

    Ok(())
}

每次调用 connection::connect() 都会生成一个新的 IAM 令牌。如果操作的时间长于令牌持续时间，请创建一个新连接。

高级用法

主机配置

该连接器支持完整的集群端点（自动检测区域）和集群 ID（需要区域）：

// Full endpoint (region auto-detected)
let opts = DsqlConnectOptions::from_connection_string(
    "postgres://admin@your-cluster.dsql.us-east-1.on.aws/postgres"
)?;

// Cluster ID (region required)
let opts = DsqlConnectOptions::from_connection_string(
    "postgres://admin@your-cluster-id/postgres?region=us-east-1"
)?;

AWS 配置文件

为凭证指定 AWS 配置文件：

let pool = aurora_dsql_sqlx_connector::pool::connect(
    "postgres://admin@your-cluster.dsql.us-east-1.on.aws/postgres?profile=production"
).await?;

连接字符串格式

该连接器支持 PostgreSQL 连接字符串格式：

postgres://[user@]host[:port]/[database][?param=value&...]
postgresql://[user@]host[:port]/[database][?param=value&...]

支持的查询参数：region、profile、tokenDurationSecs、ormPrefix。

池配置

对于自定义池设置，请将 PgPoolOptions 传递到 connect_with()：

use aurora_dsql_sqlx_connector::DsqlConnectOptions;
use sqlx::postgres::PgPoolOptions;

let config = DsqlConnectOptions::from_connection_string(
    "postgres://admin@your-cluster.dsql.us-east-1.on.aws/postgres"
)?;

let pool = aurora_dsql_sqlx_connector::pool::connect_with(
    &config,
    PgPoolOptions::new().max_connections(20),
).await?;

编程配置

使用 DsqlConnectOptionsBuilder 进行编程配置：

use aurora_dsql_sqlx_connector::{DsqlConnectOptionsBuilder, Region};
use sqlx::postgres::PgConnectOptions;

let pg = PgConnectOptions::new()
    .host("your-cluster.dsql.us-east-1.on.aws")
    .username("admin")
    .database("postgres");

let opts = DsqlConnectOptionsBuilder::default()
    .pg_connect_options(pg)
    .region(Some(Region::new("us-east-1")))
    .build()?;

let mut conn = aurora_dsql_sqlx_connector::connection::connect_with(&opts).await?;

OCC 重试

Aurora DSQL 使用乐观并发控制（OCC）。当两个事务修改相同的数据时，提交的第一个事务获胜，第二个事务收到 OCC 错误。

OCC 重试为选择加入的。启用 occ 功能，并使用 retry_on_occ 启用带指数回退和抖动的自动重试功能：

use aurora_dsql_sqlx_connector::{retry_on_occ, OCCRetryConfig};

let config = OCCRetryConfig::default(); // max_attempts: 3, exponential backoff

retry_on_occ(&config, || async {
    let mut tx = pool.begin().await?;

    sqlx::query("UPDATE accounts SET balance = balance - 100 WHERE id = $1")
        .bind(account_id)
        .execute(&mut *tx)
        .await?;

    tx.commit().await?;
    Ok(())
}).await?;

配置选项

身份验证

该连接器通过使用 AWS 凭证生成令牌来自动处理 Aurora DSQL 身份验证。如果您未提供 AWS 区域，则连接器会从主机名中解析该区域。

有关 Aurora DSQL 中的身份验证的更多信息，请参阅 Aurora DSQL 的身份验证和授权。

令牌生成

管理员用户与普通用户