Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Konektor Aurora DSQL untuk Karat SQLx
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx"></a>

Konektor [Aurora DSQL untuk Rust adalah konektor Rust](https://github.com/awslabs/aurora-dsql-connectors/tree/main/rust/sqlx) yang dibangun di atasnya [SQLx](https://github.com/launchbadge/sqlx)yang mengintegrasikan otentikasi IAM untuk menghubungkan aplikasi Rust ke cluster Amazon Aurora DSQL.

Konektor menangani pembuatan token, konfigurasi SSL, dan manajemen koneksi sehingga Anda dapat fokus pada logika aplikasi Anda.

## Tentang konektor
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-about"></a>

Konektor Aurora DSQL untuk Rust menambahkan lapisan otentikasi di atasnya SQLx yang menangani pembuatan token IAM, memungkinkan Anda untuk terhubung ke Aurora DSQL tanpa mengubah alur kerja yang ada. SQLx 

### Apa itu otentikasi Aurora DSQL?
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-authentication"></a>

**Dalam Aurora DSQL, otentikasi melibatkan:**
+ **Otentikasi IAM**: Semua koneksi menggunakan otentikasi berbasis IAM dengan token terbatas waktu
+ **Generasi Token**: Konektor menghasilkan token otentikasi menggunakan AWS kredensil, dan token ini memiliki masa pakai yang dapat dikonfigurasi

Konektor Aurora DSQL untuk Rust memahami persyaratan ini dan secara otomatis menghasilkan token otentikasi IAM saat membuat koneksi.

### Fitur
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-features"></a>
+ **Otentikasi IAM otomatis** - Menangani pembuatan dan penyegaran token Aurora DSQL
+ **Dibangun di atas SQLx** - Membungkus driver PostgreSQL async populer untuk Rust
+ **Integrasi mulus** - Bekerja dengan alur kerja yang ada SQLx 
+ **Penggabungan koneksi** - Dukungan kumpulan opt-in dengan penyegaran token latar belakang melalui fitur `pool`
+ **Deteksi otomatis wilayah** - Ekstrak AWS wilayah dari nama host cluster Aurora DSQL
+ AWS dukungan **kredensil - Mendukung** AWS profil dan rantai kredensi default
+ Coba lagi **OCC - Coba lagi** kontrol konkurensi optimis dengan backoff eksponensial dan jitter

## Contoh aplikasi
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-example-application"></a>

Untuk contoh lengkap, lihat [contoh aplikasi](https://github.com/awslabs/aurora-dsql-connectors/tree/main/rust/sqlx/example) di GitHub.

## Panduan memulai cepat
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-quick-start"></a>

### Persyaratan
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-requirements"></a>
+ Rust 1.80 atau lebih baru
+ [Memulai dengan Aurora DSQL](getting-started.md)
+ AWS kredensil yang dikonfigurasi (melalui AWS CLI, variabel lingkungan, atau peran IAM)

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

Tambahkan ke`Cargo.toml`:

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

Untuk sebagian besar aplikasi, aktifkan keduanya `pool` dan `occ` fitur:

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

### Bendera fitur
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-feature-flags"></a>


| Fitur | Default | Deskripsi | 
| --- | --- | --- | 
| pool | Tidak | SQLx pembantu kolam renang dengan penyegaran token latar belakang | 
| occ | Tidak | Pembantu coba lagi OCC (,) retry\$1on\$1occ is\$1occ\$1error | 

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

### Koneksi kolam renang
<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(())
}
```

### Koneksi tunggal
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-single-connection"></a>

Untuk skrip sederhana atau saat Anda tidak memerlukan penyatuan koneksi:

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

Setiap panggilan untuk `connection::connect()` menghasilkan token IAM baru. Untuk operasi yang lebih lama dari durasi token, buat koneksi baru.

### Penggunaan lanjutan
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-advanced"></a>

**Konfigurasi host**

Konektor mendukung titik akhir cluster penuh (wilayah terdeteksi secara otomatis) dan cluster IDs (wilayah diperlukan):

```
// 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 profil**

Tentukan AWS profil untuk kredensil:

```
let pool = aurora_dsql_sqlx_connector::pool::connect(
    "postgres://admin@your-cluster.dsql.us-east-1.on.aws/postgres?profile=production"
).await?;
```

**Format string koneksi**

Konektor mendukung format string koneksi PostgreSQL:

```
postgres://[user@]host[:port]/[database][?param=value&...]
postgresql://[user@]host[:port]/[database][?param=value&...]
```

Parameter kueri yang didukung: `region``profile`,`tokenDurationSecs`,,`ormPrefix`.

**Konfigurasi kolam renang**

Untuk pengaturan kolam khusus, teruskan `PgPoolOptions` ke`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?;
```

**Konfigurasi terprogram**

Gunakan `DsqlConnectOptionsBuilder` untuk konfigurasi terprogram:

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

**Coba lagi OCC**

Aurora DSQL menggunakan kontrol konkurensi optimis (OCC). Ketika dua transaksi memodifikasi data yang sama, yang pertama melakukan kemenangan dan yang kedua menerima kesalahan OCC.

Coba lagi OCC adalah opt-in. Aktifkan `occ` fitur dan gunakan `retry_on_occ` untuk mengaktifkan percobaan ulang otomatis dengan backoff dan jitter eksponensial:

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

**Awas**  
`retry_on_occ`mengeksekusi kembali seluruh penutupan pada konflik OCC, sehingga penutupan harus hanya berisi operasi database dan aman untuk dicoba lagi.

## Opsi konfigurasi
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-configuration"></a>


| Bidang | Tipe | Default | Deskripsi | 
| --- | --- | --- | --- | 
| host | String | (wajib) | Titik akhir cluster atau ID cluster | 
| region | Option<Region> | (terdeteksi otomatis) | AWS wilayah; diperlukan jika host adalah ID cluster | 
| user | String | "admin" | Pengguna basis data | 
| database | String | "postgres" | Nama database | 
| port | u16 | 5432 | Port basis data | 
| profile | Option<String> | None | AWS nama profil untuk kredensil | 
| tokenDurationSecs | u64 | 900(15 menit) | Durasi validitas token dalam hitungan detik | 
| ormPrefix | Option<String> | None | Awalan ORM untuk application\$1name (misalnya, menghasilkan) "diesel" "diesel:aurora-dsql-rust-sqlx/\$1version\$1" | 

## Autentikasi
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-auth"></a>

Konektor secara otomatis menangani otentikasi Aurora DSQL dengan menghasilkan token menggunakan kredensil. AWS Jika Anda tidak memberikan AWS wilayah, konektor menguraikannya dari nama host.

Untuk informasi lebih lanjut tentang otentikasi di Aurora DSQL, lihat. [Otentikasi dan otorisasi untuk Aurora DSQL](authentication-authorization.md)

### Pembuatan token
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-token-generation"></a>
+ **Kumpulan koneksi**: Tugas latar belakang menyegarkan token pada 80% dari durasi token. Panggil `pool.close().await` untuk menghentikan tugas penyegaran dan melepaskan sumber daya kumpulan.
+ **Koneksi tunggal**: Konektor menghasilkan token baru pada waktu koneksi.
+ **Pembuatan Token** adalah operasi presigning SiGv4 lokal dengan biaya yang dapat diabaikan.

### Admin vs pengguna biasa
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-admin-vs-regular"></a>
+ Pengguna bernama “admin” secara otomatis menggunakan token otentikasi admin
+ Semua pengguna lain menggunakan token otentikasi reguler
+ Konektor menghasilkan token secara dinamis untuk setiap koneksi