Conector do Aurora DSQL para Rust SQLx

O Conector do Aurora DSQL para Rust é um conector Rust baseado em SQLx que integra a autenticação do IAM para conectar aplicações Rust a clusters do Amazon Aurora DSQL.

O conector gerencia a geração de tokens, a configuração SSL e o gerenciamento de conexões para que você se concentre na lógica da aplicação.

Sobre o conector

O Conector do Aurora DSQL para Rust adiciona uma camada de autenticação sobre o SQLx que gerencia a geração de tokens do IAM, permitindo conectar ao Aurora DSQL sem alterar fluxos de trabalho existentes do SQLx.

O que é a autenticação do Aurora DSQL?

Na autenticação do Aurora DSQL, a autenticação envolve:

O Conector do Aurora DSQL para Rust compreende esses requisitos e gera automaticamente tokens de autenticação do IAM ao estabelecer conexões.

Recursos

Aplicativo de exemplo

Para ver um exemplo completo, consulte a aplicação de exemplo no GitHub.

Guia de início rápido

Requisitos

Instalação

Adicione ao seu Cargo.toml:

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

Para a maioria das aplicações, ative os recursos pool e occ:

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

Sinalizadores de atributo

Usage

Conexão do 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(())
}

Conexão única

Para scripts simples ou quando não houver necessidade de agrupamento de conexões:

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 chamada para connection::connect() gera um novo token do IAM. Para operações mais longas que a duração do token, crie outra conexão.

Uso avançado

Configuração do host

O conector é compatível com endpoints de cluster completos (região detectada automaticamente) e IDs de cluster (região obrigatória):

// 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 Perfis do

Especifique um perfil da AWS para credenciais:

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

Formato de string da conexão

O conector é compatível com os formatos de string de conexão do PostgreSQL:

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

Parâmetros de consulta compatíveis: region, profile, tokenDurationSecs, ormPrefix.

Configuração do grupo

Para configurações personalizadas de grupo, passe PgPoolOptions para 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?;

Configuração programática

Use DsqlConnectOptionsBuilder para configuração programática:

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

Nova tentativa de OCC

O Aurora DSQL usa o controle de simultaneidade otimista (OCC). Quando duas transações modificam os mesmos dados, a primeira a confirmar vence e a segunda recebe um erro de OCC.

A nova tentativa do OCC é opcional. Ative o recurso occ e retry_on_occ use para habilitar nova tentativa automática com recuo exponencial e variação aleatória:

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

Opções de configuração

Autenticação

O conector gerencia automaticamente a autenticação do Aurora DSQL gerando tokens com o uso de credenciais da AWS. Se você não fornecer a região da AWS, o conector a analisará a partir do nome do host.

Para obter mais informações sobre autenticação no Aurora DSQL, consulte Autenticação e autorização para o Aurora DSQL.

Geração de tokens

Admin versus usuários regulares