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

El [conector de Aurora DSQL para Rust](https://github.com/awslabs/aurora-dsql-connectors/tree/main/rust/sqlx) es un conector de Rust basado en [SQLx](https://github.com/launchbadge/sqlx) que integra la autenticación de IAM para conectar aplicaciones Rust a clústeres de Amazon Aurora DSQL.

El conector se encarga de la generación de tokens, la configuración SSL y la gestión de conexiones para que usted pueda centrarse en la lógica de su aplicación.

## Acerca del conector
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-about"></a>

El conector de Aurora DSQL para Rust agrega una capa de autenticación sobre SQLx que gestiona la generación de tókenes de IAM, lo que permite conectarse a Aurora DSQL sin cambiar los flujos de trabajo de SQLx existentes.

### ¿Qué es la autenticación de Aurora DSQL?
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-authentication"></a>

En Aurora DSQL, la **autenticación** implica:
+ **Autenticación de IAM**: todas las conexiones utilizan la autenticación basada en IAM con tokens de tiempo limitado
+ **Generación de tokens**: el conector genera tokens de autenticación utilizando credenciales de AWS, y estos tokens tienen una duración configurable.

El conector de Aurora DSQL para Rust comprende estos requisitos y genera automáticamente los tókenes de autenticación de IAM al establecer las conexiones.

### Características
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-features"></a>
+ **Autenticación automática de IAM**: gestiona la generación y la actualización de token de Aurora DSQL.
+ **Basado en SQLx**: incluye el popular controlador de PostgreSQL asíncrono para Rust.
+ **Integración perfecta**: funciona con los flujos de trabajo de SQLx existentes.
+ **Agrupación de conexiones**: soporte opcional de grupos con actualización de los tókenes en segundo plano a través de la característica `pool`.
+ **Detección automática de regiones**: extrae la región de AWS del nombre de host del clúster de DSQL.
+ **Compatibilidad con credenciales de AWS**: admite perfiles de AWS y la cadena de credenciales predeterminada.
+ **Reintento de OCC**: reintento opcional del control de simultaneidad optimista con retroceso exponencial y fluctuación.

## Aplicación de ejemplo
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-example-application"></a>

Para ver un ejemplo completo, consulte la [aplicación de ejemplo](https://github.com/awslabs/aurora-dsql-connectors/tree/main/rust/sqlx/example) en GitHub.

## Guía de inicio rápido
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-quick-start"></a>

### Requisitos
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-requirements"></a>
+ Rust 1.80 o posterior
+ [Introducción a Aurora DSQL](getting-started.md)
+ Credenciales de AWS configuradas (mediante AWS CLI, variables de entorno o roles de IAM).

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

Agregue a su `Cargo.toml`:

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

Para la mayoría de las aplicaciones, habilite las características `pool` y `occ`:

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

### Marcas de características
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-feature-flags"></a>


| Característica | Predeterminado | Descripción | 
| --- | --- | --- | 
| pool | No | Asistente de grupo SQLx con actualización de token en segundo plano | 
| occ | No | Ayudantes de reintento de OCC (retry\_on\_occ, is\_occ\_error) | 

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

### Conexión de grupo
<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(())
}
```

### Conexión única de
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-single-connection"></a>

Para scripts sencillos o cuando no se necesita el uso de un grupo de conexiones:

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

Cada llamada a `connection::connect()` genera un nuevo token de IAM. Para operaciones que duren más allá de la duración del token, cree una conexión nueva.

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

**Configuración de host**

El conector admite tanto puntos de conexión de clúster completos (detección automática de la región) como ID de clúster (se requiere especificar la región):

```
// 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 Perfiles de**

Especificación de un perfil de AWS para credenciales:

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

**Formato de la cadena de conexión**

El conector admite los formatos de cadena de conexión PostgreSQL:

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

Parámetros de consulta compatibles: `region`, `profile`, `tokenDurationSecs`, `ormPrefix`.

**Configuración de grupo**

Para una configuración de grupo personalizada, pase `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?;
```

**Configuración mediante programación**

Use `DsqlConnectOptionsBuilder` para configuración mediante programación:

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

**Reintento de OCC**

Aurora DSQL utiliza control de simultaneidad optimista (OCC). Cuando dos transacciones modifican los mismos datos, la primera en confirmarse tiene prioridad y la segunda recibe un error de OCC.

El reintento de OCC es opcional. Habilite la característica `occ` y use `retry_on_occ` para habilitar el reintento automático con retroceso exponencial y fluctuación:

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

**aviso**  
`retry_on_occ` vuelve a ejecutar todo el cierre en el conflicto de OCC, por lo que el cierre debe contener solo operaciones de base de datos y ser seguro para repetir el intento.

## Opciones de configuración
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-configuration"></a>


| Campo | Tipo | Predeterminado | Descripción | 
| --- | --- | --- | --- | 
| host | String | (obligatorio) | Punto de conexión de clúster o ID de clúster | 
| region | Option<Region> | (detectado automáticamente) | Región de AWS; obligatorio si el host es un ID de clúster | 
| user | String | "admin" | Usuario de base de datos | 
| database | String | "postgres" | Nombre de base de datos | 
| port | u16 | 5432 | Database port (Puerto de base de datos) | 
| profile | Option<String> | None | Nombre de perfil de AWS para las credenciales | 
| tokenDurationSecs | u64 | 900 (15 min) | Duración de la validez del token en segundos | 
| ormPrefix | Option<String> | None | Prefijo ORM para application\_name (por ejemplo, "diesel" produce "diesel:aurora-dsql-rust-sqlx/{version}") | 

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

El conector gestiona automáticamente la autenticación de Aurora DSQL generando tokens usando las credenciales de AWS. Si no proporciona la región de AWS, el conector la analiza a partir del nombre de host.

Para obtener más información sobre la autenticación en Aurora DSQL, consulte [Autenticación y autorización para Aurora DSQL](authentication-authorization.md).

### Generación de tókenes
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-token-generation"></a>
+ **Grupos de conexiones**: una tarea en segundo plano actualiza el token al 80 % de su duración. Llame a `pool.close().await` para detener la tarea de actualización y liberar los recursos del grupo.
+ **Conexiones únicas**: el conector genera un token nuevo en el momento de la conexión.
+ La **generación de tókenes** es una operación local de prefirma de SigV4 con un costo insignificante.

### Administrador frente a usuarios habituales
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-admin-vs-regular"></a>
+ Los usuarios denominados “admin” utilizan automáticamente los tókenes de autenticación de administrador
+ Todos los demás usuarios utilizan tókenes de autenticación habituales
+ El conector genera tokens de forma dinámica para cada conexión