Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

# Connecteur SQL Aurora pour Rust SQLx
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx"></a>

Le [connecteur Aurora DSQL pour Rust](https://github.com/awslabs/aurora-dsql-connectors/tree/main/rust/sqlx) est un connecteur Rust intégré [SQLx](https://github.com/launchbadge/sqlx)qui intègre l'authentification IAM pour connecter les applications Rust aux clusters Amazon Aurora DSQL.

Le connecteur gère la génération de jetons, la configuration SSL et la gestion des connexions afin que vous puissiez vous concentrer sur la logique de votre application.

## À propos du connecteur
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-about"></a>

Le connecteur Aurora DSQL pour Rust ajoute une couche d'authentification SQLx qui gère la génération de jetons IAM, ce qui vous permet de vous connecter à Aurora DSQL sans modifier vos flux de travail existants. SQLx 

### Qu'est-ce que l'authentification SQL Aurora ?
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-authentication"></a>

Dans Aurora DSQL, **l’authentification** implique :
+ **Authentification IAM** : toutes les connexions utilisent l’authentification basée sur IAM avec des jetons à durée limitée
+ **Génération de jetons** : le connecteur génère des jetons d'authentification à l'aide AWS d'informations d'identification, et ces jetons ont une durée de vie configurable

Le connecteur Aurora DSQL pour Rust comprend ces exigences et génère automatiquement des jetons d'authentification IAM lors de l'établissement de connexions.

### Caractéristiques
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-features"></a>
+ **Authentification IAM automatique** : gère la génération et l'actualisation des jetons Aurora DSQL
+ **Construit sur SQLx** : intègre le célèbre pilote asynchrone PostgreSQL pour Rust
+ **Intégration parfaite** - Fonctionne avec les SQLx flux de travail existants
+ **Regroupement de connexions** : prise en charge des pools optionnels avec actualisation des jetons en arrière-plan via la `pool` fonctionnalité
+ **Détection automatique des régions** : extrait AWS la région du nom d'hôte du cluster Aurora DSQL
+ **AWS support des informations d'identification** : prend en charge les AWS profils et la chaîne d'identification par défaut
+ **Nouvelle tentative OCC - Réessayez de** contrôler la simultanéité de manière optimiste avec recul et instabilité exponentiels

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

Pour un exemple complet, consultez l'[exemple d'application](https://github.com/awslabs/aurora-dsql-connectors/tree/main/rust/sqlx/example) sur GitHub.

## Guide de démarrage rapide
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-quick-start"></a>

### Exigences
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-requirements"></a>
+ Rust 1.80 ou version ultérieure
+ [Mise en route avec Aurora DSQL](getting-started.md)
+ AWS informations d'identification configurées (via la AWS CLI, les variables d'environnement ou les rôles IAM)

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

Ajoutez à votre `Cargo.toml` :

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

Pour la plupart des applications, activez à la fois les `occ` fonctionnalités `pool` et :

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

### Drapeaux caractéristiques
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-feature-flags"></a>


| Fonctionnalité | Par défaut | Description | 
| --- | --- | --- | 
| pool | Non | SQLx assistant de pool avec actualisation du jeton d'arrière-plan | 
| occ | Non | Assistants à la nouvelle tentative OCC (,) retry\$1on\$1occ is\$1occ\$1error | 

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

### Connexion à la piscine
<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(())
}
```

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

Pour les scripts simples ou lorsque vous n'avez pas besoin d'un regroupement de connexions :

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

Chaque appel à `connection::connect()` génère un nouveau jeton IAM. Pour les opérations supérieures à la durée du jeton, créez une nouvelle connexion.

### Utilisation avancée
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-advanced"></a>

**Configuration de l'hôte**

Le connecteur prend en charge à la fois les points de terminaison complets du cluster (région détectée automatiquement) et le cluster IDs (région requise) :

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

Spécifiez un AWS profil pour les informations d'identification :

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

**Format de chaîne de connexion**

Le connecteur prend en charge les formats de chaîne de connexion PostgreSQL :

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

Paramètres de requête pris en charge : `region``profile`,`tokenDurationSecs`,,`ormPrefix`.

**Configuration du pool**

Pour les paramètres de pool personnalisés, passez `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?;
```

**Configuration programmatique**

Utilisation `DsqlConnectOptionsBuilder` pour la configuration programmatique :

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

**Réessayer OCC**

Aurora DSQL utilise un contrôle de simultanéité optimiste (OCC). Lorsque deux transactions modifient les mêmes données, la première à valider gagne et la seconde reçoit une erreur OCC.

Une nouvelle tentative d'OCC est facultative. Activez la `occ` fonctionnalité et utilisez-la `retry_on_occ` pour activer une nouvelle tentative automatique avec un recul et une instabilité exponentiels :

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

**Avertissement**  
`retry_on_occ`réexécute la fermeture complète en cas de conflit OCC. La fermeture ne doit donc contenir que des opérations de base de données et pouvoir être réessayée en toute sécurité.

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


| Champ | Type | Par défaut | Description | 
| --- | --- | --- | --- | 
| host | String | (obligatoire) | Point de terminaison ou ID de cluster | 
| region | Option<Region> | (détecté automatiquement) | AWS région ; obligatoire si l'hôte est un ID de cluster | 
| user | String | "admin" | Utilisateur de la base de donnée | 
| database | String | "postgres" | Nom de la base de données | 
| port | u16 | 5432 | Port de la base de données | 
| profile | Option<String> | None | AWS nom de profil pour les informations d'identification | 
| tokenDurationSecs | u64 | 900(15 minutes) | Durée de validité du jeton en secondes | 
| ormPrefix | Option<String> | None | Préfixe ORM pour application\$1name (par exemple, produit) "diesel" "diesel:aurora-dsql-rust-sqlx/\$1version\$1" | 

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

Le connecteur gère automatiquement l'authentification Aurora DSQL en générant des jetons à l'aide d' AWS informations d'identification. Si vous ne fournissez pas la AWS région, le connecteur l'analyse à partir du nom d'hôte.

Pour plus d'informations sur l'authentification dans Aurora DSQL, consultez[Authentification et autorisation pour Aurora DSQL](authentication-authorization.md).

### Génération de jetons
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-token-generation"></a>
+ **Pools de connexions** : une tâche en arrière-plan actualise le jeton à 80 % de sa durée. Appelez `pool.close().await` pour arrêter la tâche d'actualisation et libérer les ressources du pool.
+ **Connexions uniques** : le connecteur génère un nouveau jeton au moment de la connexion.
+ La **génération de jetons** est une opération de présignature SigV4 locale dont le coût est négligeable.

### Administrateur et utilisateurs réguliers
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-admin-vs-regular"></a>
+ Les utilisateurs nommés « admin » utilisent automatiquement des jetons d'authentification d'administrateur
+ Tous les autres utilisateurs utilisent des jetons d'authentification ordinaires
+ Le connecteur génère des jetons de manière dynamique pour chaque connexion