sqlx

sqlx 0.8 oferece SQL assíncrono e nativo do driver com verificação opcional de consulta em tempo de compilação contra um banco de dados ativo.

Receita

Cartão de referência rápida - pronto para copiar e colar.

use sqlx::FromRow;
 
#[derive(FromRow)]
struct User { id: i64, email: String }
 
let users = sqlx::query_as::<_, User>("SELECT id, email FROM users WHERE active = $1")
    .bind(true)
    .fetch_all(&pool)
    .await?;

Quando usar isso: Você deseja controle de SQL bruto, integração assíncrona com Tokio e suporte a PostgreSQL/MySQL/SQLite sem um ORM pesado.

Exemplo de Trabalho

use sqlx::{postgres::PgPoolOptions, FromRow};
 
#[derive(Debug, FromRow)]
struct Item { id: i64, name: String }
 
#[tokio::main]
async fn main() -> Result<(), sqlx::Error> {
    let pool = PgPoolOptions::new()
        .max_connections(5)
        .connect(&std::env::var("DATABASE_URL").expect("DATABASE_URL"))
        .await?;
 
    sqlx::query("CREATE TABLE IF NOT EXISTS items (id BIGSERIAL PRIMARY KEY, name TEXT NOT NULL)")
        .execute(&pool)
        .await?;
 
    let inserted = sqlx::query_as::<_, Item>(
        "INSERT INTO items (name) VALUES ($1) RETURNING id, name"
    )
    .bind("widget")
    .fetch_one(&pool)
    .await?;
 
    let all = sqlx::query_as::<_, Item>("SELECT id, name FROM items ORDER BY id")
        .fetch_all(&pool)
        .await?;
 
    println!("{:?} {:?}", inserted, all);
    Ok(())
}

O que isso demonstra:

PgPoolOptions para configuração de pool.
Mapeamento de FromRow de linhas para structs.
INSERT ... RETURNING com resultado tipado.
fetch_all para consultas de várias linhas.

Mergulho Profundo

Como Funciona

sqlx fala o protocolo nativo (por exemplo, fio do PostgreSQL) sem bloquear o runtime.
A macro query! verifica o SQL em tempo de compilação quando DATABASE_URL é definido para cargo sqlx prepare.
O modo offline armazena metadados de consulta em .sqlx/ para CI sem banco de dados.

Estilos de Consulta

API	Verificação	Uso
`query`	Runtime	SQL Dinâmico
`query_as`	Mapeamento de Runtime	Linhas de Struct
`query!`	Tempo de Compilação	SQL Conhecido
`query_as!`	Tempo de Compilação	Linhas Tipadas

Notas de Rust

// Verificações offline em tempo de compilação
// cargo sqlx prepare --workspace
let row = sqlx::query!("SELECT id FROM users WHERE id = $1", id).fetch_one(&pool).await?;

Armadilhas

SQL em strings de formato - Risco de injeção. Correção: Use query apenas com parâmetros de vinculação.
Banco de dados necessário em tempo de compilação - query! precisa de um banco de dados na compilação, a menos que preparado. Correção: Execute cargo sqlx prepare em CI.
Consultas N+1 em loops - Uma consulta por item prejudica a latência. Correção: Agrupe WHERE id = ANY($1) ou junções.
Pool por solicitação - Criar pools repetidamente esgota o banco de dados. Correção: Um pool em AppState.
Desvio de migração - SQL escrito manualmente fora de sincronia com o esquema. Correção: Migrações como fonte da verdade.

Alternativas

Alternativa	Use Quando	Não Use Quando
Diesel	Construtor de consultas type-safe, síncrono	Pilha Tokio assíncrona pura preferida
SeaORM	ORM assíncrono com relações	Controle máximo de SQL necessário
tokio-postgres sozinho	Dependências mínimas	Você quer pooling e macros

FAQs

Quais bancos de dados?

PostgreSQL, MySQL, SQLite, MSSQL via flags de recursos.

Transações?

pool.begin().await? então commit ou rollback automático ao descartar.

Colunas JSON?

sqlx::types::Json<T> para jsonb do PostgreSQL.

Arrays?

Vec<T> vincula a arrays PostgreSQL com tipos compatíveis.

Testes?

#[sqlx::test] inicia um banco de dados ou usa testcontainers.

MSRV?

Corresponde à toolchain Rust do workspace - sqlx acompanha as versões estáveis recentes.

Registrando consultas?

Ative o recurso de rastreamento sqlx; filtre SQL nos logs de produção para PII.

Segredos da string de conexão?

Apenas variáveis de ambiente; nunca envie URLs com senhas.

Timeouts de pool?

acquire_timeout em PgPoolOptions evita solicitações travadas.

Réplicas de leitura?

Pools separados para URLs de leitura vs. gravação; roteie na camada de repositório.

Relacionado

Noções Básicas de Banco de Dados - Introdução a pool e consultas
Migrações - Gerenciamento de esquema
Pooling de Conexão - Dimensionamento de pool
Transações e Isolamento - Uso de ACID
Padrões de Consulta e N+1 - Acesso eficiente

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4 e Polars 0.46+.

sqlx

sqlx 0.8 oferece SQL assíncrono e nativo do driver com verificação opcional de consulta em tempo de compilação contra um banco de dados ativo.

Receita

Cartão de referência rápida - pronto para copiar e colar.

use sqlx::FromRow;
 
#[derive(FromRow)]
struct User { id: i64, email: String }
 
let users = sqlx::query_as::<_, User>("SELECT id, email FROM users WHERE active = $1")
    .bind(true)
    .fetch_all(&pool)
    .await?;

Quando usar isso: Você deseja controle de SQL bruto, integração assíncrona com Tokio e suporte a PostgreSQL/MySQL/SQLite sem um ORM pesado.

Exemplo de Trabalho

use sqlx::{postgres::PgPoolOptions, FromRow};
 
#[derive(Debug, FromRow)]
struct Item { id: i64, name: String }
 
#[tokio::main]
async fn main() -> Result<(), sqlx::Error> {
    let pool = PgPoolOptions::new()
        .max_connections(5)
        .connect(&std::env::var("DATABASE_URL").expect("DATABASE_URL"))
        .await?;
 
    sqlx::query("CREATE TABLE IF NOT EXISTS items (id BIGSERIAL PRIMARY KEY, name TEXT NOT NULL)")
        .execute(&pool)
        .await?;
 
    let inserted = sqlx::query_as::<_, Item>(
        "INSERT INTO items (name) VALUES ($1) RETURNING id, name"
    )
    .bind("widget")
    .fetch_one(&pool)
    .await?;
 
    let all = sqlx::query_as::<_, Item>("SELECT id, name FROM items ORDER BY id")
        .fetch_all(&pool)
        .await?;
 
    println!("{:?} {:?}", inserted, all);
    Ok(())
}

O que isso demonstra:

PgPoolOptions para configuração de pool.
Mapeamento de FromRow de linhas para structs.
INSERT ... RETURNING com resultado tipado.
fetch_all para consultas de várias linhas.

Mergulho Profundo

Como Funciona

sqlx fala o protocolo nativo (por exemplo, fio do PostgreSQL) sem bloquear o runtime.
A macro query! verifica o SQL em tempo de compilação quando DATABASE_URL é definido para cargo sqlx prepare.
O modo offline armazena metadados de consulta em .sqlx/ para CI sem banco de dados.

Estilos de Consulta

API	Verificação	Uso
`query`	Runtime	SQL Dinâmico
`query_as`	Mapeamento de Runtime	Linhas de Struct
`query!`	Tempo de Compilação	SQL Conhecido
`query_as!`	Tempo de Compilação	Linhas Tipadas

Notas de Rust

// Verificações offline em tempo de compilação
// cargo sqlx prepare --workspace
let row = sqlx::query!("SELECT id FROM users WHERE id = $1", id).fetch_one(&pool).await?;

Armadilhas

SQL em strings de formato - Risco de injeção. Correção: Use query apenas com parâmetros de vinculação.
Banco de dados necessário em tempo de compilação - query! precisa de um banco de dados na compilação, a menos que preparado. Correção: Execute cargo sqlx prepare em CI.
Consultas N+1 em loops - Uma consulta por item prejudica a latência. Correção: Agrupe WHERE id = ANY($1) ou junções.
Pool por solicitação - Criar pools repetidamente esgota o banco de dados. Correção: Um pool em AppState.
Desvio de migração - SQL escrito manualmente fora de sincronia com o esquema. Correção: Migrações como fonte da verdade.

Alternativas

Alternativa	Use Quando	Não Use Quando
Diesel	Construtor de consultas type-safe, síncrono	Pilha Tokio assíncrona pura preferida
SeaORM	ORM assíncrono com relações	Controle máximo de SQL necessário
tokio-postgres sozinho	Dependências mínimas	Você quer pooling e macros

FAQs

Quais bancos de dados?

PostgreSQL, MySQL, SQLite, MSSQL via flags de recursos.

Transações?

pool.begin().await? então commit ou rollback automático ao descartar.

Colunas JSON?

sqlx::types::Json<T> para jsonb do PostgreSQL.

Arrays?

Vec<T> vincula a arrays PostgreSQL com tipos compatíveis.

Testes?

#[sqlx::test] inicia um banco de dados ou usa testcontainers.

MSRV?

Corresponde à toolchain Rust do workspace - sqlx acompanha as versões estáveis recentes.

Registrando consultas?

Ative o recurso de rastreamento sqlx; filtre SQL nos logs de produção para PII.

Segredos da string de conexão?

Apenas variáveis de ambiente; nunca envie URLs com senhas.

Timeouts de pool?

acquire_timeout em PgPoolOptions evita solicitações travadas.

Réplicas de leitura?

Pools separados para URLs de leitura vs. gravação; roteie na camada de repositório.

Relacionado

Noções Básicas de Banco de Dados - Introdução a pool e consultas
Migrações - Gerenciamento de esquema
Pooling de Conexão - Dimensionamento de pool
Transações e Isolamento - Uso de ACID
Padrões de Consulta e N+1 - Acesso eficiente

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4 e Polars 0.46+.

sqlx

Buscar na documentação

sqlx