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

O [Conector do Aurora DSQL para Rust](https://github.com/awslabs/aurora-dsql-connectors/tree/main/rust/sqlx) é um conector Rust baseado em [SQLx](https://github.com/launchbadge/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
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-about"></a>

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?
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-authentication"></a>

Na autenticação do Aurora DSQL, a **autenticação** envolve:
+ **Autenticação do IAM**: todas as conexões usam autenticação baseada no IAM com tokens de tempo limitado.
+ **Geração de token**: o conector gera tokens de autenticação usando credenciais da AWS, e esses tokens têm vida útil configurável

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

### Recursos
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-features"></a>
+ **Autenticação automática do IAM:** lida com a geração e atualização de tokens do Aurora DSQL
+ **Baseado em SQLx:** encapsula o driver assíncrono popular de PostgreSQL para Rust
+ **Integração perfeita:** funciona com fluxos de trabalho existentes do SQLx
+ **Agrupamento de conexões**: suporte opcional a grupo com atualização em segundo plano de tokens do IAM por meio do recurso `pool`
+ **Detecção automática de região:** extrai a região da AWS do nome de host do cluster do Aurora DSQL
+ **Suporte de credenciais da AWS**: é compatível com perfis da AWS e com a cadeia de credenciais padrão
+ **Nova tentativa de OCC:** permite optar por uma nova tentativa de controle de simultaneidade otimista com recuo exponencial e variação aleatória

## Aplicativo de exemplo
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-example-application"></a>

Para ver um exemplo completo, consulte a [aplicação de exemplo](https://github.com/awslabs/aurora-dsql-connectors/tree/main/rust/sqlx/example) no GitHub.

## Guia de início 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>
+ Ruby 1.80 ou posterior
+ [Conceitos básicos do Aurora DSQL](getting-started.md)
+ Credenciais da AWS configuradas (por meio da CLI da AWS, de variáveis de ambiente ou perfis do IAM)

## Instalação
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-installation"></a>

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
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-feature-flags"></a>


| Recurso | Padrão | Descrição | 
| --- | --- | --- | 
| pool | Não | Auxiliar de grupo de SQLx com atualização de token em segundo plano | 
| occ | Não | Auxiliares de nova tentativa de OCC (retry\_on\_occ, is\_occ\_error) | 

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

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

### Conexão única
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-single-connection"></a>

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
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-advanced"></a>

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

**Atenção**  
`retry_on_occ` executa novamente toda a closure em caso de conflito OCC, portanto a closure deve conter apenas operações de banco de dados e ser segura para nova tentativa.

## Opções de configuração
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-configuration"></a>


| Campo | Tipo | Padrão | Descrição | 
| --- | --- | --- | --- | 
| host | String | (obrigatório) | Endpoint do cluster ou ID do cluster | 
| region | Option<Region> | (detectado automaticamente) | Região da AWS; obrigatória se o host for um ID de cluster | 
| user | String | "admin" | Usuário do banco de dados | 
| database | String | "postgres" | Nome do banco de dados | 
| port | u16 | 5432 | Porta do banco de dados | 
| profile | Option<String> | None | Nome do perfil da AWS para credenciais | 
| tokenDurationSecs | u64 | 900 (15 min) | Duração da validade do token em segundos | 
| ormPrefix | Option<String> | None | Prefixo de ORM para application\_name (por exemplo, "diesel" produz "diesel:aurora-dsql-rust-sqlx/{version}") | 

## Autenticação
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-auth"></a>

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](authentication-authorization.md).

### Geração de tokens
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-token-generation"></a>
+ **Grupos de conexão:** uma tarefa em segundo plano atualiza o token em 80% da duração do token. Chame `pool.close().await` para interromper a tarefa de atualização e liberar recursos do grupo.
+ **Conexões únicas:** o conector gera um novo token do IAM no momento da conexão.
+ A **geração de tokens** é uma operação local de pré-assinatura SigV4 com custo insignificante.

### Admin versus usuários regulares
<a name="SECTION_program-with-dsql-connector-for-rust-sqlx-admin-vs-regular"></a>
+ Usuários chamados “admin” utilizam automaticamente tokens de autenticação de admin.
+ Todos os outros usuários utilizam tokens de autenticação regulares.
+ O conector gera tokens dinamicamente para cada conexão