SQLx para Rust: guia completo com exemplos

O que é SQLx e para que serve?

\n\n

SQLx é uma biblioteca Rust assíncrona e pura para trabalhar com bancos de dados, que implementa a abordagem "SQL sem ORM". Ao contrário de soluções ORM como Diesel ou SeaORM, o SQLx não esconde consultas SQL por trás de abstrações, mas permite escrever código SQL puro, garantindo total segurança de tipos em tempo de compilação.

\n\n

Principais vantagens do SQLx:

\n

\n
• Segurança de tipos em tempo de compilação — o SQLx verifica suas consultas SQL em relação ao esquema do banco de dados diretamente durante a compilação do projeto.
\n
• Assincronicidade nativa — a biblioteca suporta totalmente async/await, sendo ideal para aplicações web de alta carga.
\n
• Suporte a múltiplos SGBDs — PostgreSQL, MySQL, SQLite e MSSQL.
\n
• Sem mágica — você escreve SQL comum, e a biblioteca apenas ajuda a passar parâmetros e obter resultados com segurança.
\n
• Migrações — sistema integrado de gerenciamento de migrações de esquema de banco de dados.
\n

\n\n

O SQLx é ideal para projetos onde o controle total sobre as consultas, desempenho e segurança de tipos são importantes, mas sem a necessidade de aprender DSLs (linguagens específicas de domínio) complexas de ORM.

\n\n

Instalação

\n\n

O SQLx é instalado através do gerenciador de pacotes Cargo. Adicione a dependência no arquivo Cargo.toml:

\n\n

[dependencies]\nsqlx = { version = "0.7", features = ["runtime-tokio-rustls", "postgres"] }\ntokio = { version = "1", features = ["full"] }\nanyhow = "1.0"

\n\n

Dependendo do banco de dados utilizado, escolha a flag de recurso correspondente:

\n

\n
• postgres — para PostgreSQL
\n
• mysql — para MySQL
\n
• sqlite — para SQLite
\n
• mssql — para Microsoft SQL Server
\n

\n\n

Para o runtime, você pode escolher runtime-tokio-rustls (recomendado) ou runtime-async-std-rustls.

\n\n

Início rápido

\n\n

Vamos criar uma aplicação simples que se conecta ao PostgreSQL e executa uma consulta:

\n\n

use sqlx::postgres::PgPoolOptions;\nuse anyhow::Result;\n\n#[tokio::main]\nasync fn main() -> Result<()> {\n    // Cria um pool de conexões\n    let pool = PgPoolOptions::new()\n        .max_connections(5)\n        .connect("postgres://user:password@localhost/mydb")\n        .await?;\n\n    // Executa uma consulta simples\n    let row: (i64,) = sqlx::query_as("SELECT $1::bigint")\n        .bind(42_i64)\n        .fetch_one(&pool)\n        .await?;\n\n    println!("Resultado: {}", row.0);\n\n    Ok(())\n}

\n\n

Este código cria um pool de 5 conexões com o banco de dados, executa uma consulta com parâmetro e exibe o resultado.

\n\n

Principais métodos e funções do SQLx

\n\n

1. sqlx::query

\n

O que faz: Cria uma nova consulta SQL com possibilidade de vinculação de parâmetros. É o bloco de construção básico para todas as operações.

\n

Parâmetros:

\n

\n
• sql: &str — string da consulta SQL com placeholders ($1, $2 para PostgreSQL; ? para MySQL/SQLite)
\n

\n

Exemplo:

\n

use sqlx::query;\n\nlet query = sqlx::query("SELECT * FROM users WHERE id = $1 AND active = $2")\n    .bind(1)\n    .bind(true);

\n\n

2. .bind()

\n

O que faz: Vincula um valor ao parâmetro da consulta. A ordem das chamadas corresponde à ordem dos placeholders no SQL.

\n

Parâmetros:

\n

\n
• value: impl Encode + Type<DB> — qualquer valor que possa ser codificado para o banco de dados (i32, String, bool, Option, etc.)
\n

\n

Exemplo:

\n

let user_id: i32 = 42;\nlet user_name: &str = "Alice";\n\nsqlx::query("INSERT INTO users (id, name) VALUES ($1, $2)")\n    .bind(user_id)\n    .bind(user_name)\n    .execute(&p