ORM — SeaORM

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

let active = 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 active = 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> and Objects<article::Entity> are two different types, generated at compile time (monomorphisation, course generics): Objects<users::Entity>::all() returns users::Model, never article::Model.

use std::marker::PhantomData;

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

The manager has no data to keep: it only needs to know which entity it is about. Rust refuses an unused type parameter; PhantomData<E> uses it without taking up a single byte. So Objects<E> has a size of zero.

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

A const fn can be called to initialise a constant. This is what allows objects to be declared as an associated const (section 5), without a static or start-up initialisation.

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

Column::Active.eq(true) produces a SimpleExpr; Condition::any().add(..) produces a Condition. Thanks to Into<Condition>, filter accepts both (course borrow-avance, section 5).

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

Each method takes the builder (self), modifies it and gives it back. So you chain .filter(..).order_by_asc(..).limit(..) without an intermediate variable, and the compiler prevents reusing a query that has already been consumed.

users::Entity::objects               Objects<users::Entity>        (constant, zero size)
        │ .filter(..) / .all() / .exclude(..)
        ▼
RuniqueQueryBuilder<users::Entity>   { query: Select<users::Entity> }   (wraps a SeaORM query)
        │ .filter(..) .order_by_asc(..) .limit(..)     → return Self
        │ .all(db) .first(db) .one(db) .count(db)      → execute (async)
        ▼
SeaORM Select<E>  →  SQL  →  database

// runique/src/macros/bdd/objects.rs (excerpt)
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 (excerpt)
pub struct RuniqueQueryBuilder<E: EntityTrait> {
    query: Select<E>,                // the underlying SeaORM query
}

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
    }
}

A newtype around Select<E> (course structures-enums, section 4): it adds Django-style names without rewriting SeaORM's logic.

use sea_orm::ColumnTrait;

// Several conditions: AND
let active_adults = 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?;

// OR: a Condition
use sea_orm::Condition;
let two = 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 per_page = 20u64;
let articles = article::Entity::objects
    .all()
    .order_by_desc(article::Column::Id)
    .limit(per_page)
    .offset((page - 1) * per_page)
    .all(&db)
    .await?;

// With the author, in one query
let with_author = 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::Published.eq(true))
    .into_select();                 // Select<article::Entity>

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

The builder hides nothing: everything SeaORM can do stays accessible.

// By primary key
let u = users::Entity::objects.get(&db, 5).await?;              // Err(RecordNotFound) if missing
let u = users::Entity::objects.get_optional(&db, 5).await?;     // None if missing

// By a condition
let u = users::Entity::objects
    .filter(users::Column::Email.eq("[email protected]"))
    .first(&db).await?;                                          // the first one, even if there are several

let u = users::Entity::objects
    .filter(users::Column::Email.eq("[email protected]"))
    .one(&db).await?;                                            // Err if two rows match

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

one reads two rows at most to check that there is only one. Use it when uniqueness is a security assumption (finding an account by its email, a token by its value): if the database contains a duplicate, an error is better than an account picked at random. first fits when several results are normal and the order decides.

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 not found")
        .await
    {
        Ok(a) => a,
        Err(response) => return Ok(response),       // 404 page (or 500 if the query failed)
    };
    // ...
}

Two forms exist: Objects::get_or_404(db, id, &request, message) by primary key, and RuniqueQueryBuilder::get_or_404(db, &request, message) after filters.

use runique::search;

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

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

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

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

// 3. filter_many for equalities
let c = article::Entity::objects
    .filter_many([(article::Column::Published, true)])
    .filter(article::Column::Title.contains("rust"))
    .desc(article::Column::CreatedAt)
    .limit(10)
    .all(&db)
    .await?;

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

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

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

impl<E: EntityTrait> QueryExt<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)
    }
}

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