Diesel

Diesel é um ORM e construtor de consultas type-safe que captura muitos erros de SQL em tempo de compilação através da geração de código de schema.

Receita

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

use diesel::prelude::*;
 
#[derive(Queryable, Selectable)]
#[diesel(table_name = users)]
struct User { id: i64, email: String }
 
let results = users::table
    .filter(users::active.eq(true))
    .select(User::as_select())
    .load(&mut conn)?;

Quando usar isso: Você deseja alinhamento de schema em tempo de compilação, um construtor de consultas rico e migrações integradas ao ORM - frequentemente em arquiteturas síncronas ou spawn_blocking.

Exemplo de Trabalho

use diesel::prelude::*;
use diesel::pg::PgConnection;
 
diesel::table! {
    items (id) {
        id -> Int8,
        name -> Text,
    }
}
 
#[derive(Queryable, Selectable, Insertable)]
#[diesel(table_name = items)]
struct Item { id: i64, name: String }
 
#[derive(Insertable)]
#[diesel(table_name = items)]
struct NewItem<'a> { name: &'a str }
 
fn main() -> QueryResult<()> {
    let mut conn = PgConnection::establish(&std::env::var("DATABASE_URL").unwrap())?;
    let new = NewItem { name: "widget" };
    let inserted: Item = diesel::insert_into(items::table)
        .values(&new)
        .get_result(&mut conn)?;
    let all: Vec<Item> = items::table.load(&mut conn)?;
    println!("{:?} {:?}", inserted, all);
    Ok(())
}

O que isso demonstra:

• A macro table! define o schema em tempo de compilação.
• NewItem separado para inserções sem id.
• insert_into(...).get_result retorna a linha inserida no PostgreSQL.
• Queryable + Selectable para leituras.

Mergulho Profundo

Como Funciona

• diesel print-schema gera schema.rs a partir do banco de dados ativo.
• Métodos do construtor de consultas compilam para SQL parametrizado.
• Conexões são síncronas - use spawn_blocking em manipuladores Axum assíncronos ou diesel-async para assíncrono nativo.

Diesel vs sqlx

Notas de Rust

// Assíncrono com diesel-async (conceitual)
// let users = users::table.load(&mut async_conn).await?;

Armadilhas

• Bloqueio em runtime assíncrono - PgConnection síncrono em um manipulador assíncrono bloqueia o Tokio. Correção: tokio::task::spawn_blocking ou diesel-async.
• Desvio de schema - Esqueceu de executar diesel migration run novamente e regenerar o schema. Correção: Automatizar em CI.
• SQL Complexo - Filtros dinâmicos são estranhos no construtor. Correção: Recorrer a sql_query com parâmetros de vinculação.
• Conexão por requisição - Estabelecer conexões é caro. Correção: Pool r2d2 com Diesel.
• N+1 com Diesel - Padrão de carregamento preguiçoso não é como o Rails - ainda manual. Correção: Carregamentos join ou belonging_to.

Alternativas

FAQs

Relacionado

• sqlx - Alternativa SQL assíncrona
• SeaORM - ORM assíncrono
• Migrations - Fluxo de trabalho de schema
• Padrões de Consulta e N+1 - Consultas eficientes
• Melhores Práticas de Banco de Dados - Higiene de dados

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+.