Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Connettore Aurora DSQL per Rust SQLx
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx"></a>

L'[Aurora DSQL Connector for Rust è un connettore Rust](https://github.com/awslabs/aurora-dsql-connectors/tree/main/rust/sqlx) basato su [SQLx](https://github.com/launchbadge/sqlx)che integra l'autenticazione IAM per connettere le applicazioni Rust ai cluster DSQL di Amazon Aurora.

Il connettore gestisce la generazione di token, la configurazione SSL e la gestione delle connessioni in modo che tu possa concentrarti sulla logica dell'applicazione.

## Informazioni sul connettore
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-about"></a>

L'Aurora DSQL Connector for Rust aggiunge un livello di autenticazione SQLx che gestisce la generazione di token IAM, consentendoti di connetterti ad Aurora DSQL senza modificare i flussi di lavoro esistenti. SQLx 

### Cos'è l'autenticazione Aurora SQL?
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-authentication"></a>

In Aurora DSQL, l’**autenticazione** prevede:
+ **Autenticazione IAM:** tutte le connessioni utilizzano l’autenticazione basata su IAM con token a tempo limitato
+ **Generazione di token**: il connettore genera token di autenticazione utilizzando AWS credenziali e questi token hanno una durata configurabile

L'Aurora DSQL Connector for Rust comprende questi requisiti e genera automaticamente token di autenticazione IAM quando stabilisce connessioni.

### Funzionalità
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-features"></a>
+ **Autenticazione IAM automatica**: gestisce la generazione e l'aggiornamento dei token Aurora DSQL
+ **Costruito su SQLx**: racchiude il popolare driver PostgreSQL asincrono per Rust
+ **Integrazione perfetta: funziona con i flussi di lavoro esistenti** SQLx 
+ **Connessione condivisa**: supporto del pool di opt-in con aggiornamento dei token in background tramite la funzionalità `pool`
+ **Rilevamento automatico della regione**: estrae la AWS regione dal nome host del cluster Aurora DSQL
+ AWS supporto per **le credenziali: supporta** AWS i profili e la catena di credenziali predefinita
+ **Riprova OCC: attiva un nuovo tentativo** ottimistico di controllo della concorrenza con backoff e jitter esponenziali

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

Per un esempio completo, vedi l'[applicazione di esempio](https://github.com/awslabs/aurora-dsql-connectors/tree/main/rust/sqlx/example) su GitHub.

## Guida rapida di avvio
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-quick-start"></a>

### Requisiti
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-requirements"></a>
+ Rust 1.80 o versione successiva
+ [Nozioni di base su Aurora DSQL](getting-started.md)
+ AWS credenziali configurate (tramite AWS CLI, variabili di ambiente o ruoli IAM)

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

Aggiungi al tuo: `Cargo.toml`

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

Per la maggior parte delle applicazioni, abilita sia `pool` le `occ` funzionalità che:

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

### Bandiere di funzionalità
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-feature-flags"></a>


| Funzionalità | Predefinita | Description | 
| --- | --- | --- | 
| pool | No | SQLx pool helper con aggiornamento dei token in background | 
| occ | No | aiutanti di riprova OCC (,) retry\$1on\$1occ is\$1occ\$1error | 

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

### Connessione alla piscina
<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(())
}
```

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

Per script semplici o quando non è necessario il pool di connessioni:

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

Ogni chiamata `connection::connect()` genera un nuovo token IAM. Per operazioni più lunghe della durata del token, crea una nuova connessione.

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

**Configurazione dell'host**

Il connettore supporta sia gli endpoint completi del cluster (regione rilevata automaticamente) che il cluster IDs (regione richiesta):

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

Specificare un AWS profilo per le credenziali:

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

**Formato della stringa di connessione**

Il connettore supporta i formati di stringhe di connessione PostgreSQL:

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

Parametri di interrogazione supportati:`region`,,,`profile`. `tokenDurationSecs` `ormPrefix`

**Configurazione del pool**

Per impostazioni personalizzate del pool, passa `PgPoolOptions` a`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?;
```

**Configurazione programmatica**

Uso `DsqlConnectOptionsBuilder` per la configurazione programmatica:

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

**Riprova OCC**

Aurora DSQL utilizza il controllo ottimistico della concorrenza (OCC). Quando due transazioni modificano gli stessi dati, la prima che esegue il commit vince e la seconda riceve un errore OCC.

Il nuovo tentativo OCC è facoltativo. Abilita la `occ` funzione e usala `retry_on_occ` per abilitare il nuovo tentativo automatico con backoff e jitter esponenziali:

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

**avvertimento**  
`retry_on_occ`riesegue l'intera chiusura in caso di conflitto OCC, quindi la chiusura deve contenere solo le operazioni del database ed essere sicura da riprovare.

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


| Campo | Tipo | Predefinita | Description | 
| --- | --- | --- | --- | 
| host | String | (richiesto) | Endpoint o ID del cluster | 
| region | Option<Region> | (rilevato automaticamente) | AWS regione; richiesto se l'host è un ID del cluster | 
| user | String | "admin" | Utente del database | 
| database | String | "postgres" | Nome del database | 
| port | u16 | 5432 | Database port (Porta del database) | 
| profile | Option<String> | None | AWS nome del profilo per le credenziali | 
| tokenDurationSecs | u64 | 900(15 min) | Durata della validità del token in secondi | 
| ormPrefix | Option<String> | None | Prefisso ORM per application\$1name (ad esempio, produce) "diesel" "diesel:aurora-dsql-rust-sqlx/\$1version\$1" | 

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

Il connettore gestisce automaticamente l'autenticazione Aurora DSQL generando token utilizzando credenziali. AWS Se non fornisci la AWS regione, il connettore la analizza a partire dal nome host.

Per ulteriori informazioni sull'autenticazione in Aurora DSQL, vedere. [Autenticazione e autorizzazione per Aurora DSQL](authentication-authorization.md)

### Generazione di token
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-token-generation"></a>
+ **Pool di connessioni**: un'attività in background aggiorna il token all'80% della durata del token. Chiama `pool.close().await` per interrompere l'attività di aggiornamento e rilasciare le risorse del pool.
+ **Connessioni singole**: il connettore genera un nuovo token al momento della connessione.
+ La **generazione di token** è un'operazione di prefirma SigV4 locale con costi trascurabili.

### Amministratore vs. utenti regolari
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-admin-vs-regular"></a>
+ Gli utenti denominati «admin» utilizzano automaticamente i token di autenticazione dell'amministratore
+ Tutti gli altri utenti utilizzano token di autenticazione regolari
+ Il connettore genera i token in modo dinamico per ogni connessione