Rust SQLx용 Aurora DSQL 커넥터

Rust용 Aurora DSQL 커넥터는 Rust 애플리케이션을 Amazon Aurora DSQL 클러스터에 연결하기 위한 IAM 인증을 통합하는 SQLx를 기반으로 구축된 Rust 커넥터입니다.

커넥터는 토큰 생성, SSL 구성 및 연결 관리를 처리하므로 애플리케이션 로직에 집중할 수 있습니다.

커넥터 정보

Rust용 Aurora DSQL 커넥터는 IAM 토큰 생성을 처리하는 SQLx 위에 인증 계층을 추가하여 기존 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?;

구성 옵션

Authentication

커넥터는 AWS 자격 증명을 사용해 토큰을 생성하여 Aurora DSQL 인증을 자동으로 처리합니다. AWS 리전을 제공하지 않으면 커넥터가 호스트 이름에서 리전을 구문 분석합니다.

Aurora DSQL의 인증에 대한 자세한 내용은 Aurora DSQL에 대한 인증 및 권한 부여 섹션을 참조하세요.

토큰 생성

관리자와 일반 사용자