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

Le connecteur Aurora DSQL pour Rust est un connecteur Rust intégré SQLxqui 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

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 ?

Dans Aurora DSQL, l’authentification implique :

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

Exemple d'application

Pour un exemple complet, consultez l'exemple d'application sur GitHub.

Guide de démarrage rapide

Exigences

Installation

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

Usage

Connexion à la piscine

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

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

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 : regionprofile,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?;

Options de configuration

Authentification

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, consultezAuthentification et autorisation pour Aurora DSQL.

Génération de jetons

Administrateur et utilisateurs réguliers