ORM — SeaORM

use sea_orm::{ColumnTrait, EntityTrait, QueryFilter, QueryOrder};

let actifs = users::Entity::find()
    .filter(users::Column::Active.eq(true))
    .order_by_asc(users::Column::Username)
    .all(&db)
    .await?;

User.objects.filter(active=True).order_by("username")

let actifs = users::Entity::objects
    .filter(users::Column::Active.eq(true))
    .order_by_asc(users::Column::Username)
    .all(&db)
    .await?;

pub struct Objects<E: EntityTrait> { /* ... */ }

Objects<users::Entity> et Objects<article::Entity> sont deux types différents, générés à la compilation (monomorphisation, cours generics) : Objects<users::Entity>::all() renvoie des users::Model, jamais des article::Model.

use std::marker::PhantomData;

pub struct Objects<E: EntityTrait> {
    _phantom: PhantomData<E>,
}

Le gestionnaire n'a aucune donnée à garder : il a seulement besoin de savoir de quelle entité il s'agit. Rust refuse un paramètre de type inutilisé ; PhantomData<E> l'utilise sans occuper un seul octet. Objects<E> a donc une taille nulle.

impl<E: EntityTrait> Objects<E> {
    pub const fn new() -> Self {
        Self { _phantom: PhantomData }
    }
}

Une const fn peut être appelée pour initialiser une constante. C'est ce qui permet de déclarer objects comme une const associée (section 5), sans static ni initialisation au démarrage.

pub fn filter<C>(&self, condition: C) -> RuniqueQueryBuilder<E>
where
    C: Into<Condition>,

Column::Active.eq(true) produit une SimpleExpr ; Condition::any().add(..) produit une Condition. Grâce à Into<Condition>, filter accepte les deux (cours borrow-avance, section 5).

pub fn filter<C: Into<Condition>>(mut self, condition: C) -> Self {
    self.query = self.query.filter(condition.into());
    self
}

Chaque méthode prend le constructeur (self), le modifie et le rend. On enchaîne donc .filter(..).order_by_asc(..).limit(..) sans variable intermédiaire, et le compilateur empêche de réutiliser une requête déjà consommée.

users::Entity::objects               Objects<users::Entity>        (constante, taille nulle)
        │ .filter(..) / .all() / .exclude(..)
        ▼
RuniqueQueryBuilder<users::Entity>   { query: Select<users::Entity> }   (enveloppe une requête SeaORM)
        │ .filter(..) .order_by_asc(..) .limit(..)     → renvoient Self
        │ .all(db) .first(db) .one(db) .count(db)      → exécutent (async)
        ▼
SeaORM Select<E>  →  SQL  →  base

// runique/src/macros/bdd/objects.rs (extrait)
pub struct Objects<E: EntityTrait> {
    _phantom: PhantomData<E>,
}

impl<E: EntityTrait> Objects<E> {
    pub const fn new() -> Self {
        Self { _phantom: PhantomData }
    }

    /// Returns a builder over every row of the entity — equivalent to `E::find()`.
    pub fn all(&self) -> RuniqueQueryBuilder<E> {
        RuniqueQueryBuilder::new(E::find())
    }

    /// Starts a query builder with a `WHERE` condition already applied.
    pub fn filter<C>(&self, condition: C) -> RuniqueQueryBuilder<E>
    where
        C: Into<Condition>,
    {
        RuniqueQueryBuilder::new(E::find()).filter(condition.into())
    }

    /// Starts a query builder that excludes rows matching `condition`.
    pub fn exclude<C>(&self, condition: C) -> RuniqueQueryBuilder<E>
    where
        C: Into<Condition>,
    {
        RuniqueQueryBuilder::new(E::find()).exclude(condition.into())
    }

    /// Fetches the row with primary key `id`, or `DbErr::RecordNotFound` if none exists.
    pub async fn get(
        &self,
        db: &ADb,
        id: impl Into<<E::PrimaryKey as sea_orm::PrimaryKeyTrait>::ValueType>,
    ) -> Result<E::Model, DbErr> {
        E::find_by_id(id)
            .one(db)
            .await?
            .ok_or(DbErr::RecordNotFound("Record not found".to_string()))
    }
}

impl<E: EntityTrait> Copy for Objects<E> {}

// runique/src/macros/bdd/impl_objects.rs
#[macro_export]
macro_rules! impl_objects {
    ($entity:ty) => {
        impl $entity {
            #[allow(non_upper_case_globals)]
            pub const objects: $crate::macros::bdd::objects::Objects<Self> =
                $crate::macros::bdd::objects::Objects::new();
        }
    };
}

// runique/src/macros/bdd/query.rs (extrait)
pub struct RuniqueQueryBuilder<E: EntityTrait> {
    query: Select<E>,                // la requête SeaORM sous-jacente
}

impl<E: EntityTrait> RuniqueQueryBuilder<E> {
    pub fn filter<C: Into<Condition>>(mut self, condition: C) -> Self {
        self.query = self.query.filter(condition.into());
        self
    }

    pub fn exclude<C: Into<Condition>>(mut self, condition: C) -> Self {
        self.query = self.query.filter(condition.into().not());   // NOT (condition)
        self
    }

    pub async fn all(self, db: &ADb) -> Result<Vec<E::Model>, DbErr> {
        self.query.all(db).await
    }
}

Un newtype autour de Select<E> (cours structures-enums, section 4) : il ajoute des noms à la Django sans réécrire la logique de SeaORM.

use sea_orm::ColumnTrait;

// Plusieurs conditions : ET
let adultes_actifs = users::Entity::objects
    .filter(users::Column::Active.eq(true))
    .filter(users::Column::Age.gte(18))
    .order_by_desc(users::Column::CreatedAt)
    .limit(20)
    .all(&db)
    .await?;

// OU : une Condition
use sea_orm::Condition;
let deux = users::Entity::objects
    .filter(
        Condition::any()
            .add(users::Column::Email.eq("[email protected]"))
            .add(users::Column::Email.eq("[email protected]")),
    )
    .all(&db)
    .await?;

// Pagination
let page = 3u64;
let par_page = 20u64;
let articles = article::Entity::objects
    .all()
    .order_by_desc(article::Column::Id)
    .limit(par_page)
    .offset((page - 1) * par_page)
    .all(&db)
    .await?;

// Avec l'auteur, en une requête
let avec_auteur = article::Entity::objects
    .all()
    .also_related(users::Entity)
    .all(&db)
    .await?;                        // Vec<(article::Model, Option<users::Model>)>

use sea_orm::{QuerySelect, EntityTrait};

let select = article::Entity::objects
    .filter(article::Column::Publie.eq(true))
    .into_select();                 // Select<article::Entity>

let titres: Vec<String> = select
    .select_only()
    .column(article::Column::Titre)
    .into_tuple()
    .all(&db)
    .await?;

Le constructeur ne cache rien : tout ce que SeaORM sait faire reste accessible.

// Par la clé primaire
let u = users::Entity::objects.get(&db, 5).await?;              // Err(RecordNotFound) si absent
let u = users::Entity::objects.get_optional(&db, 5).await?;     // None si absent

// Par une condition
let u = users::Entity::objects
    .filter(users::Column::Email.eq("[email protected]"))
    .first(&db).await?;                                          // le premier, même s'il y en a plusieurs

let u = users::Entity::objects
    .filter(users::Column::Email.eq("[email protected]"))
    .one(&db).await?;                                            // Err si deux lignes correspondent

// runique/src/macros/bdd/query.rs (extrait)
pub async fn one(self, db: &ADb) -> Result<Option<E::Model>, DbErr> {
    let mut results = self.query.paginate(db, 2).fetch_page(0).await?;   // au plus 2 lignes
    match results.len() {
        0 => Ok(None),
        1 => Ok(Some(results.remove(0))),
        _ => Err(DbErr::Custom("search!.one(): multiple rows returned".to_string())),
    }
}

one lit deux lignes au plus pour vérifier qu'il n'y en a qu'une. À utiliser quand l'unicité est une hypothèse de sécurité (retrouver un compte par son e-mail, un jeton par sa valeur) : si la base contient un doublon, mieux vaut une erreur qu'un compte pris au hasard. first convient quand plusieurs résultats sont normaux et que l'ordre décide.

use runique::prelude::*;

pub async fn detail(request: Request) -> AppResult<Response> {
    let id = request.get_path_as::<Pk>("id").unwrap_or_default();

    let article = match article::Entity::objects
        .get_or_404(request.db(), id, &request, "Article introuvable")
        .await
    {
        Ok(a) => a,
        Err(reponse) => return Ok(reponse),       // page 404 (ou 500 si la requête a échoué)
    };
    // ...
}

Deux formes existent : Objects::get_or_404(db, id, &request, message) par la clé primaire, et RuniqueQueryBuilder::get_or_404(db, &request, message) après des filtres.

use runique::search;

let actifs = search!(users::Entity => Active eq true).all(&db).await?;
let adultes = search!(users::Entity => Age gte 18).all(&db).await?;
let sauf = search!(users::Entity => ! Level eq 99).all(&db).await?;
let rust = search!(posts::Entity => Title icontains "rust").all(&db).await?;
let choisis = search!(users::Entity => Id in [1, 2, 3]).all(&db).await?;
let tous = search!(users::Entity).order_by_asc(users::Column::Username).all(&db).await?;

use sea_orm::{ColumnTrait, EntityTrait, QueryFilter, QueryOrder, QuerySelect};

// 1. SeaORM direct
let a = article::Entity::find()
    .filter(article::Column::Publie.eq(true))
    .filter(article::Column::Titre.contains("rust"))
    .order_by_desc(article::Column::CreatedAt)
    .limit(10)
    .all(&db)
    .await?;

// 2. objects (gestionnaire Runique)
let b = article::Entity::objects
    .filter(article::Column::Publie.eq(true))
    .filter(article::Column::Titre.contains("rust"))
    .order_by_desc(article::Column::CreatedAt)
    .limit(10)
    .all(&db)
    .await?;

// 3. filter_many pour les égalités
let c = article::Entity::objects
    .filter_many([(article::Column::Publie, true)])
    .filter(article::Column::Titre.contains("rust"))
    .desc(article::Column::CreatedAt)
    .limit(10)
    .all(&db)
    .await?;

// 4. search!
let d = search!(article::Entity => Publie eq true, Titre icontains "rust")
    .order_by_desc(article::Column::CreatedAt)
    .limit(10)
    .all(&db)
    .await?;

use runique::prelude::*;
use sea_orm::{DbErr, EntityTrait};

pub trait RequeteExt<E: EntityTrait> {
    async fn exists(self, db: &ADb) -> Result<bool, DbErr>;
}

impl<E: EntityTrait> RequeteExt<E> for RuniqueQueryBuilder<E>
where
    E::Model: Sync,
{
    async fn exists(self, db: &ADb) -> Result<bool, DbErr> {
        Ok(self.limit(1).count(db).await? > 0)
    }
}

// Utilisation
let deja_inscrit = users::Entity::objects
    .filter(users::Column::Email.eq(email))
    .exists(&db)
    .await?;