# 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)는 Rust 애플리케이션을 Amazon Aurora DSQL 클러스터에 연결하기 위한 IAM 인증을 통합하는 [SQLx](https://github.com/launchbadge/sqlx)를 기반으로 구축된 Rust 커넥터입니다.

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

## 커넥터 정보
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-about"></a>

Rust용 Aurora DSQL 커넥터는 IAM 토큰 생성을 처리하는 SQLx 위에 인증 계층을 추가하여 기존 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` 기능을 통해 백그라운드 토큰 새로 고침을 사용한 옵트인 풀 지원
+ **리전 자동 감지** - 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 CLI, 환경 변수 또는 IAM 역할을 통해 AWS 자격 증명 구성

## 설치
<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>


| Field | Type | 기본값 | 설명 | 
| --- | --- | --- | --- | 
| 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}" 생성) | 

## Authentication
<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"이라는 사용자는 관리자 인증 토큰을 자동으로 사용
+ 다른 모든 사용자는 일반 인증 토큰을 사용합니다.
+ 커넥터는 각 연결에 대해 동적으로 토큰을 생성합니다.