Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

# Aurora DSQL-Konnektor für Rust SQLx
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx"></a>

Der [Aurora DSQL Connector für Rust](https://github.com/awslabs/aurora-dsql-connectors/tree/main/rust/sqlx) ist ein Rust-Connector [SQLx](https://github.com/launchbadge/sqlx), der auf der IAM-Authentifizierung für die Verbindung von Rust-Anwendungen mit Amazon Aurora DSQL-Clustern basiert.

Der Connector kümmert sich um die Token-Generierung, die SSL-Konfiguration und das Verbindungsmanagement, sodass Sie sich auf Ihre Anwendungslogik konzentrieren können.

## Über den Konnektor
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-about"></a>

Der Aurora DSQL Connector for Rust fügt darüber hinaus eine Authentifizierungsebene hinzu SQLx , die die Generierung von IAM-Tokens übernimmt, sodass Sie eine Verbindung zu Aurora DSQL herstellen können, ohne Ihre bestehenden Workflows zu ändern. SQLx 

### Was ist Aurora DSQL-Authentifizierung?
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-authentication"></a>

In Aurora DSQL umfasst die **Authentifizierung**:
+ **IAM-Authentifizierung**: alle Verbindungen verwenden eine IAM-basierte Authentifizierung mit zeitlich begrenzten Token
+ **Token-Generierung**: Der Connector generiert Authentifizierungstoken mithilfe von AWS Anmeldeinformationen, und diese Token haben eine konfigurierbare Lebensdauer

Der Aurora DSQL Connector for Rust versteht diese Anforderungen und generiert beim Verbindungsaufbau automatisch IAM-Authentifizierungstoken.

### Features
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-features"></a>
+ **Automatische IAM-Authentifizierung** — Übernimmt die Generierung und Aktualisierung von Aurora DSQL-Tokens
+ **Built on SQLx** — Umschließt den beliebten asynchronen PostgreSQL-Treiber für Rust
+ **Nahtlose Integration — Funktioniert** mit bestehenden Workflows SQLx 
+ **Verbindungspooling — Opt-in-Pool-Unterstützung** mit Token-Aktualisierung im Hintergrund über die Funktion `pool`
+ **Automatische Erkennung von Regionen** — Extrahiert die AWS Region aus dem Hostnamen des Aurora DSQL-Clusters
+ AWS Unterstützung von **Anmeldeinformationen — Unterstützt** AWS Profile und die standardmäßige Anmeldeinformationskette
+ **OCC-Wiederholung — Opt-in-Wiederholungsversuch** mit optimistischer Parallelitätssteuerung mit exponentiellem Backoff und Jitter

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

[Ein vollständiges Beispiel finden Sie in der Beispielanwendung unter.](https://github.com/awslabs/aurora-dsql-connectors/tree/main/rust/sqlx/example) GitHub

## Schnellstart-Anleitung
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-quick-start"></a>

### Voraussetzungen
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-requirements"></a>
+ Rust 1.80 oder höher
+ [Erste Schritte mit Aurora DSQL](getting-started.md)
+ AWS konfigurierte Anmeldeinformationen (über AWS CLI, Umgebungsvariablen oder IAM-Rollen)

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

Fügen Sie zu Ihrem `Cargo.toml` hinzu:

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

Aktivieren Sie für die meisten Anwendungen `pool` sowohl die als auch die `occ` Funktionen:

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

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


| Feature | Standard | Description | 
| --- | --- | --- | 
| pool | Nein | SQLx Pool-Helper mit Token-Aktualisierung im Hintergrund | 
| occ | Nein | OCC-Helfer für Wiederholungsversuche (retry\$1on\$1occ,) is\$1occ\$1error | 

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

### Verbindung zum Pool
<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(())
}
```

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

Für einfache Skripte oder wenn Sie kein Verbindungspooling benötigen:

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

Bei jedem Aufruf von `connection::connect()` wird ein neues IAM-Token generiert. Für Operationen, die länger als die Tokendauer dauern, erstellen Sie eine neue Verbindung.

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

**Host-Konfiguration**

Der Connector unterstützt sowohl vollständige Cluster-Endpunkte (Region automatisch erkannt) als auch Cluster IDs (Region erforderlich):

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

Geben Sie ein AWS Profil für Anmeldeinformationen an:

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

**Format der Verbindungszeichenfolge**

Der Konnektor unterstützt PostgreSQL-Verbindungszeichenfolgenformate:

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

Unterstützte Abfrageparameter:`region`,,`profile`,`tokenDurationSecs`. `ormPrefix`

**Pool-Konfiguration**

Für benutzerdefinierte Pooleinstellungen gehen Sie weiter `PgPoolOptions` an`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?;
```

**Programmatische Konfiguration**

`DsqlConnectOptionsBuilder`Für die programmatische Konfiguration verwenden:

```
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-Wiederholung**

Aurora DSQL verwendet Optimistic Concurrency Control (OCC). Wenn zwei Transaktionen dieselben Daten ändern, gewinnt die erste Transaktion, die einen Commit durchführt, und die zweite erhält einen OCC-Fehler.

Die OCC-Wiederholung ist optional. Aktivieren Sie die `occ` Funktion und verwenden Sie sie`retry_on_occ`, um automatische Wiederholungsversuche mit exponentiellem Backoff und Jitter zu aktivieren:

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

**Warnung**  
`retry_on_occ`führt den gesamten Abschluss bei einem OCC-Konflikt erneut aus, sodass der Abschluss nur Datenbankoperationen beinhalten sollte und ein erneuter Versuch sicher sein sollte.

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


| Feld | Typ | Standard | Description | 
| --- | --- | --- | --- | 
| host | String | (erforderlich) | Cluster-Endpunkt oder Cluster-ID | 
| region | Option<Region> | (automatisch erkannt) | AWS Region; erforderlich, wenn es sich bei dem Host um eine Cluster-ID handelt | 
| user | String | "admin" | Datenbankbenutzer | 
| database | String | "postgres" | Datenbankname | 
| port | u16 | 5432 | Datenbankport | 
| profile | Option<String> | None | AWS Profilname für Anmeldeinformationen | 
| tokenDurationSecs | u64 | 900(15 Minuten) | Gültigkeitsdauer des Tokens in Sekunden | 
| ormPrefix | Option<String> | None | ORM-Präfix für application\$1name (zum Beispiel "diesel" produziert) "diesel:aurora-dsql-rust-sqlx/\$1version\$1" | 

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

Der Connector verarbeitet automatisch die Aurora-DSQL-Authentifizierung, indem er mithilfe von AWS Anmeldeinformationen Token generiert. Wenn Sie die AWS Region nicht angeben, analysiert der Connector sie anhand des Hostnamens.

Weitere Informationen zur Authentifizierung in Aurora DSQL finden Sie unter[Authentifizierung und Autorisierung für Aurora DSQL](authentication-authorization.md).

### Token-Generierung
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-token-generation"></a>
+ **Verbindungspools**: Eine Hintergrundaufgabe aktualisiert das Token bei 80% der Tokendauer. Rufen Sie `pool.close().await` auf, um die Aktualisierungsaufgabe zu beenden und Poolressourcen freizugeben.
+ **Einzelverbindungen**: Der Konnektor generiert zum Zeitpunkt der Verbindung ein neues Token.
+ Die **Token-Generierung** ist ein lokaler SigV4-Vorsignierungsvorgang mit vernachlässigbaren Kosten.

### Admin im Vergleich zu normalen Benutzern
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-admin-vs-regular"></a>
+ Benutzer mit dem Namen „admin“ verwenden automatisch Admin-Authentifizierungstoken
+ Alle anderen Benutzer verwenden reguläre Authentifizierungstoken
+ Der Connector generiert dynamisch Token für jede Verbindung