本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Aurora DSQL Connector for Rust SQLx
[Aurora DSQL Connector for Rust](https://github.com/awslabs/aurora-dsql-connectors/tree/main/rust/sqlx) 是建置在 [SQLx](https://github.com/launchbadge/sqlx) 上的 Rust 連接器，整合 IAM 身分驗證以將 Rust 應用程式連線至 Amazon Aurora DSQL 叢集。
連接器會處理字符產生、SSL 組態和連線管理，讓您可以專注於應用程式邏輯。
## 關於連接器
Aurora DSQL Connector for Rust 在處理產生 IAM 字符的 SQLx 上新增了身分驗證層，可讓您連線到 Aurora DSQL，而無需變更現有的 SQLx 工作流程。
### 什麼是 Aurora DSQL 身分驗證？
在 Aurora DSQL 中，**身分驗證**涉及：
+ **IAM 身分驗證**：所有連線都使用具有時間限制權杖的 IAM 型身分驗證
+ **權杖產生**：連接器使用 AWS 登入資料產生身分驗證權杖，這些權杖具有可設定的生命週期
Aurora DSQL Connector for Rust 了解這些要求，並在建立連線時自動產生 IAM 身分驗證字符。
### 功能
+ **自動 IAM 身分驗證** - 處理 Aurora DSQL 字符產生和重新整理
+ **建置在 SQLx** 上 - 包裝 Rust 的熱門非同步 PostgreSQL 驅動程式
+ **無縫整合** - 適用於現有的 SQLx 工作流程
+ **連線集區** - 透過 `pool`功能使用背景字符重新整理來選擇加入集區支援
+ **區域自動偵測** - 從 Aurora DSQL 叢集主機名稱擷取 AWS 區域
+ **AWS 憑證支援** - 支援 AWS 設定檔和預設憑證鏈
+ **OCC 重試** - 選擇加入具有指數退避和抖動的樂觀並行控制重試
## 範例應用程式
如需完整範例，請參閱 GitHub 上的[範例應用程式](https://github.com/awslabs/aurora-dsql-connectors/tree/main/rust/sqlx/example)。
## 快速入門指南
### 要求
+ Rust 1.80 或更新版本
+ [Aurora DSQL 入門指南](getting-started.md)
+ AWS 設定的登入資料 （透過 AWS CLI、環境變數或 IAM 角色）
## 安裝
將 新增至您的 `Cargo.toml`：
```
[dependencies]
aurora-dsql-sqlx-connector = "0.1.2"
```
對於大多數應用程式，同時啟用 `pool`和 `occ`功能：
```
[dependencies]
aurora-dsql-sqlx-connector = { version = "0.1.2", features = ["pool", "occ"] }
```
### 功能旗標
| 功能 | 預設 | Description |
| --- | --- | --- |
| pool | 否 | 具有背景字符重新整理的 SQLx 集區協助程式 |
| occ | 否 | OCC 重試協助程式 (retry\$1on\$1occ、is\$1occ\$1error) |
## Usage
### 集區連線
```
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 字符。對於超過字符持續時間的操作，請建立新的連線。
### 進階用量
**主機組態**
連接器同時支援完整叢集端點 （自動偵測區域） 和叢集 IDs（需要區域）：
```
// 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?;
```
**警告**
`retry_on_occ` 在 OCC 衝突上重新執行整個關閉，因此關閉應僅包含資料庫操作，並且可以安全地重試。
## 組態選項
| 欄位 | Type | 預設 | Description |
| --- | --- | --- | --- |
| host | String | （必要） | 叢集端點或叢集 ID |
| region | Option | （自動偵測） | AWS region；如果主機是叢集 ID，則為必要 |
| user | String | "admin" | 資料庫使用者 |
| database | String | "postgres" | 資料庫名稱 |
| port | u16 | 5432 | Database port (資料庫連線埠) |
| profile | Option | None | AWS 登入資料的設定檔名稱 |
| tokenDurationSecs | u64 | 900 (15 分鐘） | 字符有效性持續時間，以秒為單位 |
| ormPrefix | Option | None | application\$1name 的 ORM 字首 （例如， "diesel"會產生 "diesel:aurora-dsql-rust-sqlx/\$1version\$1") |
## 身分驗證
連接器會自動處理 Aurora DSQL 身分驗證，方法是使用 AWS 登入資料產生字符。如果您未提供區域，連接器會從主機名稱剖析該 AWS 區域。
如需 Aurora DSQL 中身分驗證的詳細資訊，請參閱 [Aurora DSQL 的身分驗證和授權](authentication-authorization.md)。
### 產生字符
+ **連線集區**：背景任務會在字符持續時間的 80% 重新整理字符。呼叫 `pool.close().await` 以停止重新整理任務並釋放集區資源。
+ **單一連線**：連接器會在連線時產生新的權杖。
+ 權**杖產生**是成本微乎其微的本機 SigV4 預先簽章操作。
### 管理員與一般使用者
+ 名為「admin」的使用者會自動使用管理員身分驗證字符
+ 所有其他使用者都使用一般身分驗證字符
+ 連接器會為每個連線動態產生字符