Diesel: un ORM para Rust

Diesel es una herramienta para el mapeo objeto relacional (ORM, Object-Relational Mapping) para el lenguaje de programación Rust.

Esta herramienta nos ayuda a crear relaciones entre bases de datos y, en este caso, código hecho en Rust.

Además crear operaciones CRUD (Crear, Leer, Actualizar y Eliminar datos) de manera más sencilla. Podemos usar PostgreSQL, MySQL y SQLite.

El sitio oficial dice que debemos tener una versión de Rust superior a la 1.86.0 de preferencia. Verficamos las versiones de Cargo y Rust instalados en nuestro sistema:

$ rustc --version
$ cargo --version

En caso de no tener una versión actualizada, podemos hacerlo lanzando este comando:

$ rustup update stable

Empezando con Diesel

Requisitos:

1. Tener la última versión instalada de Rust (y Cargo). 
2. Tener SQLite instalado.

En caso de no tener SQLite instalado, ver este sitio:

https://sqlite.org/download.html

1. Crearemos un proyecto Rust:

$ cargo new --lib diesel_demo
$ cd diesel_demo

Esto nos creará el proyecto y nos ubicará en el.

2. Ahora editaremos el archivo ``Cargo.toml`` para agregar las dependencias de SQLite y una herramienta llamada .env para administrar nuestros ambientes.

[package]
name = "diesel_demo"
version = "0.1.0"
edition = "2024"

[dependencies]
diesel = { version = "2.2.0", features = ["sqlite", "returning_clauses_for_sqlite_3_35"]}
libsqlite3-sys = { version = "0.27", features = ["bundled"] }
dotenvy = "0.15"
anyhow = "1.0"

3. Instalar la herramienta ``Diesel CLI``

En Linux:

$ curl --proto '=https' --tlsv1.2 -LsSf https://github.com/diesel-rs/diesel/releases/latest/download/diesel_cli-installer.sh | sh

En Windows:

$ Set-ExecutionPolicy RemoteSigned -scope CurrentUser
$ irm https://github.com/diesel-rs/diesel/releases/latest/download/diesel_cli-installer.ps1 | iex

Este comando empezará con la descarga e instalación de la herramienta. En caso de solo querer usar SQLite (y no instalar lo demás) puedes optar por ejecutar este comando:

$ cargo install diesel_cli --no-default-features --features sqlite

4. Crear una BD de SQLite y una tabla:

$ sqlite3 C:\SQLite\test.db

Esto nos abrirá el Shell y crearemos la tabla:

CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL);

Insertamos unos datos:

insert into users (id, name) values (1, 'Mariana Perez');
insert into users (id, name) values (2, 'Thomas Muller');

Listar y salir del shell:

sqlite> .tables
sqlite> .quit

5. Colocamos la variable de la base de datos. Para ello podemos crear un archivo .env donde colocaremos lo siguiente:

DATABASE_URL=C:/SQLite/test.db

Podemos usar Powershell para colocar la variable:

$ setx DATABASE_URL "C:\SQLite\test.db"

O de esta forma:

$ setx DATABASE_URL "C:/SQLite/test.db"

6. Configurar Diesel al proyecto:

$ diesel setup

Y con esto:

• Esto creará nuestra base de datos (si no existía ya). 
• Configurará el directorio de migraciones inicial, que contendrá un archivo de migración generado que establece la configuración de Diesel.

7. El siguiente paso será la migración que nos creará una tabla para almacenar nuestros usuarios:

$ diesel migration generate create_users

Si todo va bien, la salida será algo como esto:

Creating migrations\2025-12-22-012254-0000_create_users\up.sql
Creating migrations\2025-12-22-012254-0000_create_users\down.sql

Editamos los archivos SQL up.sql y down.sql del proyecto:

up.sql

CREATE TABLE IF NOT EXISTS users (
  id INTEGER PRIMARY KEY,
  name TEXT NOT NULL
)

down.sql

DROP TABLE users

Como se puede observar el primero es para crear la tabla y el otro para borrarla.

8. Ejecutamos la migración:

$ diesel migration run

Esto ejecutará el script de creación de la tabla (en este caso la recreación). También podemos probar el borrado de la tabla con este otro comando:

$ diesel migration redo

Nuestro archivo schema.rs lucirá así:

diesel::table! {
    users (id) {
        id -> Nullable<Integer>,
        name -> Text,
    }
}

9. Editamos el archivo src\lib.rs para crear la conexión a la base de datos:

use diesel::prelude::*;
use dotenvy::dotenv;
use std::env;

pub fn establish_connection() -> SqliteConnection {
    dotenv().ok();

    let database_url = env::var("DATABASE_URL").expect("DATABASE_URL must be set");
    SqliteConnection::establish(&database_url)
        .unwrap_or_else(|_| panic!("Error connecting to {}", database_url))
}

Agregaremos esto en el tope del archivo:

pub mod models;
pub mod schema;

Con esto declaramos los módulos de models y schema, lo cual dejaría al archivo de esta manera:

src\lib.rs

pub mod models;
pub mod schema;

use diesel::prelude::*;
use dotenvy::dotenv;
use std::env;

pub fn establish_connection() -> SqliteConnection {
    dotenv().ok();

    let database_url = env::var("DATABASE_URL").expect("DATABASE_URL must be set");
    SqliteConnection::establish(&database_url)
        .unwrap_or_else(|_| panic!("Error connecting to {}", database_url))
}

10. Crear los módulos declarados.

src/models.rs

use diesel::prelude::*;

#[derive(Queryable, Selectable)]
#[diesel(table_name = crate::schema::users)]
#[diesel(check_for_backend(diesel::sqlite::Sqlite))]
pub struct User {
    pub id: i32,
    pub name: String,
}

schema.rs

diesel::table! {
    users (id) {
        id -> Integer,
        name-> Text,
    }
}

Con esto hemos creado el modelo y esquema.

11. Crear un archivo para mostrar los usuarios:

src\bin\show_users.rs

use self::models::*;
use diesel::prelude::*;
use diesel_demo::*;


fn main() {
    use self::schema::users::dsl::*;

    let connection = &mut establish_connection();
    let results = users
        .select(User::as_select())
        .load(connection)
        .expect("Error loading users");

    println!("Displaying {} users", results.len());
    for user in results {
        println!("{}", user.id);
        println!("----------\n");
        println!("{}", user.name);
    }
}

12. Ejecutamos la aplicación de esta manera:

$ cargo run --bin show_users

Si todo va bien, esta será la salida:

Displaying 2 users
1
----------

Mariana Perez
2
----------

Thomas Muller

¡Hemos creado nuestra primera aplicación con Diesel!

Conclusiones:

Diesel permite a los programadores Rust trabajar con bases de datos (PostgreSQL, SQLite y MySQL) crear relaciones objeto realcionales para realizar operaciones CRUD de manera sencilla.

Enlaces:

https://diesel.rs/
https://sqlite.org/
https://github.com/diesel-rs/diesel/
https://www.sqlitetutorial.net/