本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

Aurora DSQL Connector for Rust SQLx

Aurora DSQL Connector for Rust 是建置在 SQLx 上的 Rust 連接器，整合 IAM 身分驗證以將 Rust 應用程式連線至 Amazon Aurora DSQL 叢集。

連接器會處理字符產生、SSL 組態和連線管理，讓您可以專注於應用程式邏輯。

關於連接器

Aurora DSQL Connector for Rust 在處理產生 IAM 字符的 SQLx 上新增了身分驗證層，可讓您連線到 Aurora DSQL，而無需變更現有的 SQLx 工作流程。

什麼是 Aurora DSQL 身分驗證？

在 Aurora DSQL 中，身分驗證涉及：

Aurora DSQL Connector for Rust 了解這些要求，並在建立連線時自動產生 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"] }

功能旗標

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?;

組態選項

身分驗證

連接器會自動處理 Aurora DSQL 身分驗證，方法是使用 AWS 登入資料產生字符。如果您未提供區域，連接器會從主機名稱剖析該 AWS 區域。

如需 Aurora DSQL 中身分驗證的詳細資訊，請參閱 Aurora DSQL 的身分驗證和授權。

產生字符

管理員與一般使用者