# 适用于 Rust SQLx 的 Aurora DSQL 连接器
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx"></a>

[适用于 Rust 的 Aurora DSQL 连接器](https://github.com/awslabs/aurora-dsql-connectors/tree/main/rust/sqlx)是一款基于 [SQLx](https://github.com/launchbadge/sqlx) 构建的 Rust 连接器，它集成了 IAM 身份验证功能，用于将 Rust 应用程序连接到 Amazon Aurora DSQL 集群。

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

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

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

### 什么是 Aurora DSQL 身份验证？
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-authentication"></a>

在 Aurora DSQL 中，**身份验证**包括：
+ **IAM 身份验证**：所有连接都使用基于 IAM 的身份验证和限时令牌
+ **令牌生成**：连接器使用 AWS 凭证生成身份验证令牌，并且这些令牌具有可配置的生命周期

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

### 功能
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-features"></a>
+ **自动 IAM 身份验证**：处理 Aurora DSQL 令牌生成与刷新
+ **基于 SQLx 构建**：封装了适用于 Rust 的常用异步 PostgreSQL 驱动程序
+ **无缝集成**：可与现有的 SQLx 工作流程结合使用
+ **连接入池**：支持选择加入池，并通过 `pool` 功能在后台刷新令牌
+ **区域自动检测**：从 Aurora DSQL 集群主机名中提取 AWS 区域
+ **AWS 凭证支持**：支持 AWS 配置文件和默认凭证链
+ **OCC 重试**：选择加入乐观并发控制重试，具有指数回退和抖动功能

## 示例应用程序
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-example-application"></a>

有关完整的示例，请参阅 GitHub 上的[示例应用程序](https://github.com/awslabs/aurora-dsql-connectors/tree/main/rust/sqlx/example)。

## 快速入门指南
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-quick-start"></a>

### 要求
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-requirements"></a>
+ Rust 1.80 或更高版本
+ [Aurora DSQL 入门](getting-started.md)
+ 已配置 AWS 凭证（通过 AWS CLI、环境变量或 IAM 角色）

## 安装
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-installation"></a>

添加到 `Cargo.toml`：

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

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

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

### 功能标志
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-feature-flags"></a>


| 功能 | 默认值 | 说明 | 
| --- | --- | --- | 
| pool | 否 | 具有后台令牌刷新功能的 SQLx 池帮助程序 | 
| occ | 否 | OCC 重试帮助程序（retry\_on\_occ、is\_occ\_error） | 

## 用法
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-usage"></a>

### 池连接
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-pool-connection"></a>

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

### 单一 连接
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-single-connection"></a>

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

```
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 令牌。如果操作的时间长于令牌持续时间，请创建一个新连接。

### 高级用法
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-advanced"></a>

**主机配置**

该连接器支持完整的集群端点（自动检测区域）和集群 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?;
```

**警告**  
发生 OCC 冲突时，`retry_on_occ` 重新执行完整关闭，因此关闭应仅包含数据库操作并且可以安全地重试。

## 配置选项
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-configuration"></a>


| 字段 | 类型 | 默认值 | 说明 | 
| --- | --- | --- | --- | 
| host | String | （必需） | 集群端点或集群 ID | 
| region | Option<Region> | （自动检测） | AWS 区域；如果主机是集群 ID，则为必需 | 
| user | String | "admin" | 数据库用户 | 
| database | String | "postgres" | 数据库名称 | 
| port | u16 | 5432 | 数据库端口 | 
| profile | Option<String> | None | 凭证的 AWS 配置文件名称 | 
| tokenDurationSecs | u64 | 900（15 分钟） | 令牌有效期，以秒为单位 | 
| ormPrefix | Option<String> | None | application\_name 的 ORM 前缀（例如，"diesel" 生成 "diesel:aurora-dsql-rust-sqlx/{version}"） | 

## 身份验证
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-auth"></a>

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

有关 Aurora DSQL 中的身份验证的更多信息，请参阅 [Aurora DSQL 的身份验证和授权](authentication-authorization.md)。

### 令牌生成
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-token-generation"></a>
+ **连接池**：后台任务会在令牌持续时间的 80% 时刷新令牌。调用 `pool.close().await` 可停止刷新任务并释放池资源。
+ **单个连接**：连接器在连接时生成一个新令牌。
+ **令牌生成**是本地 SigV4 预签名操作，成本可以忽略不计。

### 管理员用户与普通用户
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-admin-vs-regular"></a>
+ 名为“admin”的用户会自动使用管理员身份验证令牌
+ 所有其他用户都使用普通身份验证令牌
+ 该连接器为每个连接动态生成令牌