Conector de Aurora DSQL para Rust SQLx

El conector de Aurora DSQL para Rust es un conector de Rust basado en 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

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?

En Aurora DSQL, la autenticación implica:

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

Aplicación de ejemplo

Para ver un ejemplo completo, consulte la aplicación de ejemplo en GitHub.

Guía de inicio rápido

Requisitos

Instalación

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

Uso

Conexión de grupo

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

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

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

Opciones de configuración

Autenticación

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.

Generación de tókenes

Administrador frente a usuarios habituales