Eloquent API

Suprnova's Eloquent layer gives Laravel developers the API they know, implemented as a thin shim over SeaORM. Copy code from the Laravel docs, swap PHP syntax for Rust, add .await?, and it runs.

The whole layer is a struct attribute (#[suprnova::model]), a trait (Model), and a chainable query builder (Builder<M>) - that's it. Behind the scenes the macro generates a SeaORM Entity, Model, ActiveModel, and Column enum, plus every Eloquent trait impl. The SeaORM types stay reachable for the rare case the Eloquent surface doesn't cover (see the SeaORM escape hatches).

Table of contents

• Quick start
• The #[suprnova::model] attribute
• Model module layout
• Finding rows
• Creating and updating
• Deleting and soft deletes
• Query builder - dual API
• Row locking
• Transactions
• Scopes
• Relationships
• Eager loading
• Preventing lazy loading
• Pagination
• Chunking and lazy iteration
• Collections
• Mass assignment
• Casts
• Accessors and mutators
• Timestamps
• Observers and lifecycle events
• Prunable
• Multi-connection routing
• Replication
• Debugging - dump and dd
• Testing models
• Dropping to SeaORM
• Migrating from database::Model
• DB facade - model-less queries
• Laravel-13 parity - relation-existence + cheap shortcuts

Quick start

One attribute on a struct turns it into a fully-featured Eloquent model:

use chrono::{DateTime, Utc};
use suprnova::{model, Model};

#[model(table = "users")]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

Once declared, you can write:

• User::query() - start a fluent query builder.
• User::find(id).await? - fetch by primary key.
• User::find_or_fail(id).await? - same, but errors with ModelNotFound on miss.
• User::all().await? - every row.
• User::create(attrs!{ name: "Alice", email: "alice@example.com" }).await? - insert with mass-assignment filtering.
• User::filter("email", "alice@example.com").first().await? - one row that matches.
• user.update(attrs!{ name: "Alice B" }).await? - partial update.
• user.save().await? - persist in-memory changes.
• user.delete().await? - remove the row.
• user.refresh().await? / user.fresh().await? / user.replicate().await? - the rest of the Laravel lifecycle.

The user-facing struct (here User) IS the type your handlers and controllers carry. The macro emits a per-model inner module (user::) with the SeaORM Entity, Column, ActiveModel, and Model types for the cases where you want to drop down to SeaORM directly. The struct is also registered in an inventory-backed ModelEntry so admin and tooling code can enumerate every model at boot.

The #[suprnova::model] attribute

The single entry point for declaring a model. Every attribute is optional; the defaults are tuned so a struct with id + created_at + updated_at works as a Suprnova model with zero configuration.

Macro attribute reference

Full example

use chrono::{DateTime, Utc};
use serde_json::Value as Json;
use suprnova::{model, AsBool, AsEncrypted, AsJson};

#[model(
    table = "users",
    fillable = ["name", "email", "preferences"],
    casts = {
        active = AsBool,
        preferences = AsJson<Json>,
        api_token = AsEncrypted,
    },
    hidden = ["password", "remember_token", "api_token"],
    appends = ["full_name"],
    soft_deletes,
    timestamps,
)]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
    pub password: String,
    pub remember_token: Option<String>,
    pub api_token: Option<String>,
    pub active: bool,
    pub preferences: Json,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
    pub deleted_at: Option<DateTime<Utc>>,
}

Function-level macros

Function-level macros work alongside the struct attribute:

• #[accessor] on a fn name(&self) -> T makes it an Eloquent accessor. The model's to_array() calls it when name is listed in appends = [...] (and to_json() picks it up via the to_array → string delegation).
• #[mutator] on a fn set_name(&mut self, value: serde_json::Value) makes it an Eloquent mutator. The model's JSON-fill path routes through it when name is listed in mutators = [...].
• #[suprnova::scopes(Model)] on an impl Model { ... } block: every method whose signature is fn name(query: Builder<Self>[, args…]) -> Builder<Self> becomes both a chainable .scope_name(args) on Builder<Self> and a Model::scope_name(args) shortcut. There is no function-level #[scope] form - scopes are declared per impl-block.
• Global scopes are a runtime registration via the GlobalScope trait, registered with ScopeRegistry::register::<M, _>(scope). There is no function-level #[global_scope] macro - see Macros for the full pattern.
• #[prunable] on impl Prunable for T { ... } registers the pruner via inventory so model:prune finds it.

Model module layout

#[suprnova::model] keeps your user-facing struct (e.g. Post) at parent scope and emits a sibling pub mod named after the struct in snake_case (post). That inner module is where the SeaORM types live.

For a model declared at app/src/models/posts.rs:

use chrono::{DateTime, Utc};
use suprnova::model;

#[model(table = "posts", fillable = ["title", "body"], timestamps)]
pub struct Post {
    pub id: i64,
    pub title: String,
    pub body: String,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

// Convention: re-export the SeaORM types the macro emits inside the
// inner module so call sites can use the unprefixed names. Suprnova's
// own dogfood models all carry this line (see `app/src/models/users.rs`,
// `app/src/models/posts.rs`, etc.).
pub use post::{ActiveModel, Column, Entity};

You now have these items reachable from crate::models::posts:

Two things to know about the inner module's Model:

1. It is the SeaORM-shape row, not your Post struct. Cast columns carry their Storage type here (e.g. bool becomes the underlying integer), and the __eager / __pivot runtime slots from your struct are absent.
2. From<post::Model> for Post and From<Post> for post::Model bridge the two shapes. See Dropping to SeaORM for the round-trip pattern.

Model is intentionally not part of the conventional parent re-export - the user-facing Post already occupies the Post name at parent scope, and post::Model is a separate type that callers reach through post::Model (or From conversion) when they need the inner shape.

When to reach into the inner module

The Eloquent surface (Model trait + Builder<M>) covers the vast majority of queries. Reach into post::* when you need SeaORM-only features:

• Raw query construction with SeaORM's EntityTrait::find() chain when Eloquent doesn't expose the helper you want.
• Custom join logic - building JoinType::* joins explicitly via QuerySelect::join() for a relation Eloquent's with(...) doesn't model.
• SeaORM-native subqueries through Entity::find().select_only().
• Plain ActiveModel mutation for the rare case you want to bypass the Eloquent lifecycle (no observers, no auto-timestamps).

// Common case - Column re-exported at parent module level via the
// `pub use post::{...}` convention above.
use crate::models::posts::Column;

let drafts = Post::query()
    .db_where(Column::Status, "draft")
    .get()
    .await?;

// Power-user case - reach into the inner module for the SeaORM Entity
// directly. This is what the parent `pub use` does not surface.
use crate::models::posts::post;
use suprnova::sea_orm::{ColumnTrait, EntityTrait, QueryFilter};

let db = suprnova::DB::connection()?;
let rows: Vec<post::Model> = post::Entity::find()
    .filter(post::Column::Status.eq("published"))
    .all(db.inner())
    .await?;

// Bridge back to the Eloquent shape when the caller wants it.
let posts: Vec<Post> = rows.into_iter().map(Post::from).collect();

If you find yourself reaching into the inner module routinely for the same operation, that's a signal Eloquent is missing a helper - open an issue, or add the helper to the Model / Builder surface.

Finding rows

// Laravel
$user = User::find(1);
$user = User::findOrFail(1);          // throws on missing
$users = User::findMany([1, 2, 3]);

// Suprnova
let user: Option<User> = User::find(1).await?;
let user: User = User::find_or_fail(1).await?;
let users: Vec<User> = User::find_many([1, 2, 3]).await?;

find_or_fail returns FrameworkError::ModelNotFound (HTTP 404 when bubbled to a controller).

first_or_create / update_or_create / first_or_new / first_or

// Laravel
$user = User::firstOrCreate(
    ['email' => 'alice@example.com'],
    ['name' => 'Alice'],
);
$user = User::updateOrCreate(
    ['email' => 'alice@example.com'],
    ['name' => 'Alice Updated'],
);
$user = User::firstOrNew(['email' => 'alice@example.com']);  // unsaved

// Suprnova
let user = User::first_or_create(
    attrs! { email: "alice@example.com" },          // lookup keys
    attrs! { name: "Alice" },                       // extras on create
).await?;

let user = User::update_or_create(
    attrs! { email: "alice@example.com" },
    attrs! { name: "Alice Updated" },
).await?;

let user = User::first_or_new(
    attrs! { email: "alice@example.com" },
).await?;   // returns an unsaved User; caller inserts it explicitly
let user = user.persist().await?;   // `use suprnova::Persistable;`

Lookup keys go in the first map; extra fields applied on the create-path go in the second map. Returning an unsaved model via first_or_new lets the caller mutate it further before inserting it with persist().await?, which fires creating and created and returns the saved model with the key the database assigned. When first_or_new finds a row, the model it returns is loaded, and save updates it.

Why Suprnova diverges

Laravel's save inserts a model that does not exist yet and writes the new key into it. Suprnova's save borrows the model, so it cannot hand the new key back. A model built in the process whose key still holds its reset value - a new model from first_or_new or find_or_new, or a replica - has no row to update, so save refuses it with an error that names persist. persist consumes the model and returns the inserted one, key included.

Creating and updating

Create

// Laravel
$user = User::create([
    'name' => 'Alice',
    'email' => 'alice@example.com',
]);

// Suprnova
let user = User::create(attrs! {
    name: "Alice",
    email: "alice@example.com",
}).await?;

attrs! is a macro that produces an Attrs value (a typed JSON map). Pure JSON also works - User::create(serde_json::json!({"name": "Alice", "email": "..."})). The Fillable filter runs inside create; non-fillable fields are silently dropped, matching Laravel's behaviour.

Declared defaults

Declare defaults(field = value, ...) to give new instances initial values:

use suprnova::{Model, attrs, model};

#[model(
    table = "posts",
    fillable = ["title", "status", "votes"],
    defaults(status = "draft", votes = 0),
)]
pub struct Post {
    pub id: i64,
    pub title: String,
    pub status: String,
    pub votes: i64,
}

let draft = Post::new();
assert_eq!(draft.status, "draft");
let draft = Post::create(attrs! { title: "First" }).await?;
let live = Post::create(attrs! { title: "Second", status: "live" }).await?;

You read declared defaults before saving a new instance. A partial create uses every declared default that your filtered attributes omit, before creation events and the insert. Your supplied attributes win. The same rules apply to create_with_tx and unsaved instances from first_or_new.

You supply values convertible into the declared field types, so "draft" works for a String. You name each column at most once. An unknown column or a value of the wrong type fails the build. Your defaults are trusted model values; your caller's attributes still pass through the fillable filter. A model without the declaration keeps its existing construction and insert behavior.

Save / update

// Laravel
$user->name = 'Alice B';
$user->save();

$user->update(['name' => 'Alice B']);

// Suprnova
user.name = "Alice B".into();
user.save().await?;

user.update(attrs! { name: "Alice B" }).await?;

You call save() after changing a loaded model. It compares your values with the original values kept in memory, without re-reading the row. A clean save issues no UPDATE and fires neither Updating nor Updated; Saving and Saved still fire. A Saving listener can make the model dirty by changing its attributes. A dirty save writes changed columns and updates its timestamp.

You use update(attrs) to apply a partial attribute map, with the Fillable filter and declared mutators, before writing.

Changes after a save

After a save, a model reports which attributes that save changed. While the save's updated and saved observers run, the original values are still the ones loaded before the save; once the save returns, they are the saved ones:

// Laravel
$user->is_admin = true;
$user->save();

$user->wasChanged('is_admin');        // true
$user->wasChanged(['name', 'email']); // false
$user->getChanges();                  // ['is_admin' => 1]
$user->getOriginal('is_admin');       // true

// Suprnova
use suprnova::Model;

user.is_admin = true;
user.save().await?;

user.was_changed("is_admin");             // true
user.was_changed_any(&["name", "email"]); // false
user.was_changed_any(&[]);                // true: the save changed something
user.get_changes();                       // Attrs { "is_admin": 1 }
user.get_original("is_admin")?;           // Some(true): the saved value
user.get_raw_original("is_admin");        // Some(1), as stored
user.get_previous("is_admin");            // Some(0): before the change

An observer reads the value from before the save, which is how an audit trail records both sides of a change:

use async_trait::async_trait;
use suprnova::eloquent::observers::Observer;
use suprnova::{FrameworkError, Model};

pub struct AdminAudit;

#[suprnova::observer(User)]
#[async_trait]
impl Observer<User> for AdminAudit {
    async fn updated(&self, _previous: &User, user: &User) -> Result<(), FrameworkError> {
        if user.was_changed("is_admin") {
            let before = user.get_raw_original("is_admin"); // Some(0)
            tracing::info!(user_id = user.id, ?before, after = user.is_admin, "admin flag changed");
        }
        Ok(())
    }
}

The rules follow Laravel's save:

• A column counts as changed when the value the database stores after the save differs from the value the model held before it. Writing the same value back is not a change. A column that a Saving listener or the timestamps rewrote is one, so a model with timestamps also reports updated_at. An encrypted column stores a new ciphertext on every save, so it is compared by its decrypted value instead: it counts as changed only when that value changed.
• get_previous(attribute) returns the stored value before the last change for that attribute. You get None for an unchanged or unknown attribute. A clean or failed save keeps this record.
• get_changes and get_raw_original return stored values, before casts, as Laravel does. get_original reads the value through the model's casts and returns an error only when the stored value no longer decodes.
• The record describes the last save that changed something. A later save that changes something replaces it. A save that changes nothing, or a save that fails, leaves it in place.
• save, update, save_with_tx, and update_with_tx record a save. A model you create reports no changes, and a model you load reports none until you save it. The original is the row as the model last read or saved it, whatever you change in memory. To answer this, every model a query loads keeps a copy of its stored row beside its fields, so a large result takes more memory than the fields alone. A clone keeps the record; replicate builds a new model without one.
• A model you build in memory and save without reading it first has no loaded values to compare with: every column counts as changed, and get_original returns None until that save returns. Such a model needs a key a row already holds: while its key holds the reset value, as a replica's and a new first_or_new model's do, save refuses it and persist inserts it.

Why Suprnova diverges

A save that changes nothing runs no UPDATE and fires neither updating nor updated, as in Laravel, while saving and saved still fire; the previous save's change record stays in place. refresh replaces the model with a fresh read, so it also clears the record, where Laravel's refresh keeps getChanges.

Increment / decrement

// Laravel
$user->increment('login_count');
$user->increment('login_count', 5);
$user->decrement('credits', 10);
User::where('plan', 'free')->increment('quota_reset_count');

// Suprnova
user.increment("login_count", 1).await?;
user.increment("login_count", 5).await?;
user.decrement("credits", 10).await?;
User::filter("plan", "free").increment("quota_reset_count", 1).await?;

increment / decrement emit UPDATE table SET col = col + N WHERE ... SQL - atomic against concurrent updates, no read-modify-write race. Available both on a fetched model instance (uses the row's PK in the WHERE clause) and as a Builder terminal (uses the chain's WHERE clauses).

Fresh / refresh / replicate

// Laravel
$user->refresh();                          // reload from DB
$user->refreshForUpdate();                 // reload under a row lock
$copy = $user->fresh();                    // fetch + return copy
$replica = $user->replicate();             // unsaved clone with fresh PK
$replica = $user->replicate(['email']);    // skip a field

// Suprnova
user.refresh().await?;
user.refresh_for_update().await?;
let copy: User = user.fresh().await?;
let replica: User = user.replicate().await?;
let replica: User = user.replicate_except(["email"]).await?;

refresh mutates in place; fresh returns a separately-fetched copy. refresh_for_update is refresh under a SELECT ... FOR UPDATE row lock - use it inside a transaction when you need the row's current values and the exclusive lock in one statement. Unlike refresh, refresh_for_update bypasses every registered global scope AND the #[model(soft_deletes)] filter: it reloads a trashed row too, with deleted_at coming back set. The reload is a lookup by primary key under a lock - scoping it the way an ordinary read is scoped would hand admin tooling and cross-tenant callers a false not-found for a row they already hold a reference to. replicate builds an in-memory clone with the PK and the timestamps reset (Default::default() for each type). Insert it with replica.persist().await? (the Persistable trait), which stamps created_at and updated_at the way create does. replica.save() refuses it: the replica has no row yet, and its reset key would name another row.

refresh and refresh_for_update both return an error when the row no longer exists, rather than leaving the model holding stale values. SQLite has no row-level locking, so refresh_for_update reloads without a lock there - see Row locking.

Replicating event

replicate and replicate_except fire the per-model Replicating { source, replica } event after constructing the in-memory clone and BEFORE returning it. The replica field is an Arc<tokio::sync::Mutex<Self>> so listeners can mutate the replica before the caller sees it - useful for prefixing titles with (copy), clearing flags, resetting derived columns, etc.

use suprnova::events::{EventFacade, Listener};
use async_trait::async_trait;

pub struct PrefixTitle;

#[async_trait]
impl Listener<post::events::Replicating> for PrefixTitle {
    async fn handle(&self, e: &post::events::Replicating)
        -> Result<(), FrameworkError>
    {
        let mut replica = e.replica.lock().await;
        replica.title = format!("(copy) {}", replica.title);
        Ok(())
    }
}

// Wire it up once at boot:
EventFacade::listen::<post::events::Replicating, _>(
    std::sync::Arc::new(PrefixTitle)
).await;

Cross-type replication

let replica: UserDraft = user.replicate_into().await?;  // cross-type clone

A Suprnova divergence - Laravel can't do this because PHP doesn't have types. Useful when promoting a draft model into a final one or vice-versa.

replicate_into<T> does NOT fire Replicating (the event carries Arc<Mutex<Self>>, so a listener on the source type couldn't mutate the cross-type replica anyway). Callers wanting per-T setup should run it on the returned T before calling persist - the normal Creating / Saving / Created / Saved chain still fires inside persist.

Deleting and soft deletes

Soft deletes flag

Add soft_deletes to the macro attribute and a deleted_at: Option<DateTime<Utc>> column to the struct:

#[model(table = "users", soft_deletes, timestamps)]
pub struct User {
    pub id: i64,
    pub email: String,
    pub deleted_at: Option<DateTime<Utc>>,
    // ...
}

Lifecycle

user.delete().await?;             // UPDATE: sets deleted_at (and updated_at) = NOW()
user.trashed();                   // -> true
let trashed = User::with_trashed().find(user.id).await?.unwrap();
trashed.restore().await?;         // UPDATE: sets deleted_at = NULL

let only_dead = User::only_trashed().get().await?;
let all_including_dead = User::with_trashed().get().await?;

user.force_delete().await?;       // actual DELETE

delete() sets updated_at along with deleted_at when the model manages timestamps, as Laravel's soft delete does. The mass form follows the row form. delete_all() on a builder soft-deletes every row the query matches with one UPDATE, and it sets updated_at too. force_delete_all() removes the rows for good. Neither fires per-row events. See Mass mutation.

User::query().filter("active", false).delete_all().await?;        // soft delete
User::only_trashed().force_delete_all().await?;                   // actual DELETE

Default scope

When soft_deletes is set, the macro overrides Model::query() so default reads filter out trashed rows automatically. with_trashed() and only_trashed() opt back in. Concretely: User::find(id) skips trashed rows; User::with_trashed().find(id) finds them.

Query builder - dual API

Builder<M> is the chainable query type returned by User::query(), User::filter(...), User::db_where(...), and every other static method that doesn't terminate the chain.

Naming note: dual API

where is a Rust keyword, so the bare-equality where method can't share Laravel's name. Rather than pick a winner, every where-shape method ships under both a Rust-idiomatic name (filter, filter_in, filter_null, …) and a Laravel-shape name (db_where, where_in, where_null, …). They're aliases over one canonical implementation - pick whichever your muscle memory matches.

// Rust dev:
User::query().filter("active", true).filter_in("role", ["admin"]).get().await?;

// Laravel dev:
User::db_where("active", true).where_in("role", ["admin"]).get().await?;

// Same query. Same result. Different muscle memory.

Where shortcuts

// Laravel
$users = User::where('email', $email)->get();
$users = User::where('age', '>=', 18)->get();
$users = User::where('email', 'like', '%@example.com')->get();

// Suprnova - pick either family; both compile, both documented.

// Rust-shape (filter family):
let users = User::query().filter("email", &email).get().await?;
let users = User::query().filter_op("age", ">=", 18).get().await?;
let users = User::query().filter_like("email", "%@example.com").get().await?;

// Laravel-shape (db_where / where_* family):
let users = User::db_where("email", &email).get().await?;
let users = User::query().db_where_op("age", ">=", 18).get().await?;
let users = User::query().where_like("email", "%@example.com").get().await?;

Where variants

Every row has two equivalent Suprnova forms - Rust-shape (filter*) and Laravel-shape (db_where / where_*). Both call the same canonical implementation; both are tagged with #[doc(alias = "...")] so rustdoc search finds either.

Every or_* method adds a flat OR condition, so r#where(a).or_where(b).r#where(c) means a OR b AND c. You use r#where(column, value) or db_where(column, value) for equality, and filter_op or or_where_op for an explicit operator. A null equality value compiles to IS NULL. Global scopes keep your complete condition list in a group when it contains an OR.

The grouped helpers keep their comparisons in parentheses: this query never returns a user whose active is false, and the model's soft-delete filter still applies:

// WHERE deleted_at IS NULL AND active = ? AND (is_admin = ? OR is_staff = ?)
let staff = User::query()
    .filter("active", true)
    .where_any(["is_admin", "is_staff"], "=", true)
    .get()
    .await?;

An empty column list adds no condition. where_in and its siblings take another DB::table builder as a subquery, and so do where_exists and where_not_exists, whose subquery can refer to the model's table through where_column:

use suprnova::DB;

let booked = Room::query()
    .where_in("id", DB::table("slots").select(["room_id"]).filter("day", "mon"))
    .get()
    .await?;

let authors = User::query()
    .where_exists(
        DB::table("posts")
            .select_raw("1")
            .where_column("posts.author_id", "users.id"),
    )
    .get()
    .await?;

A subquery's values are bound parameters in their place in the statement. For a declared relation, has and where_has build the EXISTS subquery for you. The full subquery and OR rules are in Query Builder.

The binary family compares raw bytes instead of matching under the column's collation. MySQL and MariaDB emit col = binary ?; Postgres and SQLite have no equivalent operator, so a terminal on those backends returns an error when the statement renders rather than falling back to a collation-dependent =. See Byte-exact comparison.

Bound raw predicates use portable ? markers on SQLite, MySQL, and PostgreSQL:

let rows = User::query()
    .filter("active", true)
    .filter_raw(
        "score >= ? AND role = ?",
        vec![serde_json::json!(80), serde_json::json!("admin")],
    )
    .get()
    .await?;

On PostgreSQL, Suprnova rebases those markers after earlier query bindings, so the example renders $1 for active and $2/$3 for the raw predicate. Use ?? for a literal question-mark operator in a bound raw fragment, such as "payload ?? 'enabled' AND status = ?". Existing $N fragments remain accepted, but portable markers avoid coupling call sites to query position. Mixed marker styles and marker/binding count mismatches are rejected before database I/O. As with every raw expression, the SQL text must be trusted; untrusted values belong only in the bindings vector.

Ordering

$users = User::orderBy('name', 'asc')->get();
$users = User::orderByDesc('created_at')->get();
$users = User::latest()->get();        // shortcut: orderBy(created_at, desc)
$users = User::oldest()->get();        // shortcut: orderBy(created_at, asc)
$users = User::inRandomOrder()->get();

let users = User::query().order_by("name", Direction::Asc).get().await?;
let users = User::query().order_by_desc("created_at").get().await?;
let users = User::latest().get().await?;
let users = User::oldest().get().await?;
let users = User::query().in_random_order().get().await?;

Direction::Asc / Direction::Desc is the Suprnova enum re-exported from SeaORM.

reorder() drops every ordering set so far, and reorder_by(col, dir) drops them and orders by col instead. Orderings a global scope adds when the query runs stay, as in Laravel:

$users = User::latest()->reorder('name')->get();

let users = User::latest().reorder_by("name", Direction::Asc).get().await?;

Ordering by an explicit sequence

in_order_of sorts rows into the order you list. Anything whose value is not in the list sorts after everything that is.

$users = User::inOrderOf('role', ['admin', 'member', 'guest'])->get();

let users = User::query()
    .in_order_of("role", ["admin", "member", "guest"])
    .get()
    .await?;

Suprnova renders this as a bound CASE expression, so the values are parameters and are safe to take from request data:

ORDER BY CASE WHEN role = ? THEN 0 WHEN role = ? THEN 1 WHEN role = ? THEN 2 ELSE 3 END

The column name is an SQL identifier, not a parameter. Hardcode it or pick it from an allowlist, the same as every other column argument. An empty value list adds no ordering at all, so you can build the sequence conditionally without special-casing the empty case.

For a column that uses the AsEnum<E> cast, pass each variant through as_ref(). That is the exact string the cast stores:

let users = User::query()
    .in_order_of("role", [Role::Admin.as_ref(), Role::Member.as_ref()])
    .get()
    .await?;

in_order_of ships on the typed Builder<M> surface. The model-less DB::table(...) builder orders by column and direction only.

Grouping + having

$rows = User::groupBy('role')->having('count(*)', '>', 5)->get();

let rows = User::query()
    .group_by("role")
    .having_op("count(*)", ">", 5)
    .get()
    .await?;

Limit / offset

$users = User::limit(10)->offset(20)->get();
$users = User::take(10)->skip(20)->get();   // aliases

let users = User::query().limit(10).offset(20).get().await?;
let users = User::query().take(10).skip(20).get().await?;

Select / add_select / select_raw

let users = User::query().select(["id", "name", "email"]).get().await?;
let users = User::query().select("name").add_select("email").get().await?;
let rows  = User::query().select_raw("count(*) as total, role")
    .group_by("role")
    .get_raw()
    .await?;

get_raw() returns the raw column-shape result for select_raw cases where the columns don't match the model schema; get() returns Vec<User> and requires the selected columns to fill the model struct.

Distinct

let emails: Vec<String> = User::query().distinct().pluck("email").await?;

Aggregates

let count   = User::count().await?;
let count   = User::filter("active", true).count().await?;
let sum     = User::sum::<f64>("balance").await?;
let visits  = Page::sum::<u64>("views").await?;
let avg     = Order::avg::<f64>("total").await?;
let exact   = Order::avg::<Decimal>("total").await?;
let min     = Order::min::<DateTime<Utc>>("created_at").await?;
let max     = Order::max::<DateTime<Utc>>("created_at").await?;
let exists  = User::filter("email", &email).exists().await?;
let missing = User::filter("email", &email).doesnt_exist().await?;

count returns an i64. sum, avg, min and max take the type to read as a type parameter; for avg it is f64 or rust_decimal::Decimal (the AvgValue trait). Suprnova aliases generated aggregate expressions internally so the same typed result is decoded on PostgreSQL, MySQL, and SQLite. sum and avg return zero for an empty match set, while min and max return None. The same holds when no row comes back at all - an offset skips the aggregate's one row, as skip(10).count() does, or a grouped query has no group: count, sum and avg return zero and min and max return None, as Laravel's count, sum, min and max do. An incompatible requested Rust type or missing result column is a database error; it is never converted into a plausible zero or None.

The database chooses the type of a sum or an average: PostgreSQL answers numeric for the sum of a bigint column and for any average of integers, MySQL answers DECIMAL, and SQLite answers an integer or a real. sum and avg read whichever arrives. An integer type such as i64 or u64 takes a sum exactly, and a sum with a fraction, or outside the type's range, is an error rather than a truncated value. Decimal takes a sum or an average exactly, so the average of a DECIMAL money column keeps every digit, and a value it can't hold is an error. f64 takes the nearest value. SQLite has no exact decimal type: it stores a DECIMAL column as a real, and Decimal reads that real.

Terminals

let users:  Vec<User>          = User::all().await?;
let first:  Option<User>       = User::first().await?;
let user:   User               = User::first_or_fail().await?;
let value:  Option<String>     = User::filter("...").value("email").await?;
let emails: Vec<String>        = User::pluck::<String>("email").await?;
let keyed:  HashMap<i64, String> = User::pluck_keyed::<i64, String>("id", "name").await?;
let ids:    Vec<i64>           = User::query().model_keys().await?;
let sql:    String             = User::filter("...").to_sql();

value, pluck and pluck_keyed skip a NULL: value returns None and pluck leaves the row out. A value that doesn't read as the type you name is an error that names the column, rather than a missing row. These terminals, the aggregates and DB::scalar read u64 and Option<u64> on every database, as a model's u64 field does: on Postgres and SQLite a negative value fails the read. A read by a u64 above i64::MAX answers what the database holds. On Postgres a signed integer column holds only integers, so no row matches and the query gets its answer without sending the value: find returns None, find_many skips it, and in a filter =, >, >= and IN match no row, while !=, <, <= and NOT IN match every row whose column is not NULL. SQLite compares the value's digits, as it does a literal, because an INTEGER column there can hold a REAL above i64::MAX that raw SQL or an older write left. MySQL compares the unsigned number.

The same holds for a column of a narrower integer field such as i64 or i32, which can't hold such a value on any database, and a mass update that writes one to it is refused on Postgres and SQLite before anything is sent. A column the model doesn't know, such as a joined table's column, compares as the number on every database, as with DB::table. A mass write (update_all, upsert) to a field that is neither an integer nor text, such as a decimal, also takes the value as DB::table does: a numeric column on Postgres or MySQL stores it exactly, and SQLite refuses it for a column of INTEGER or NUMERIC affinity, which would store a rounded REAL.

to_sql returns the parameterised SQL the next terminal would emit - useful for debugging or building views. The bindings are accessible via .to_sql_with_bindings() -> (String, Vec<Value>).

model_keys is the key-only terminal: it projects the qualified primary key (users.id) and never hydrates a model, so a "which rows matched?" question costs one column instead of a full row per match. The qualification is what lets it survive a query that joins another table carrying its own id. Any select(...) already on the builder is discarded - the caller asked for keys.

Joins

join, left_join, right_join, and cross_join work as they do on the DB::table builder, along with the closure forms (join_with, left_join_with, right_join_with, cross_join_with) and the subquery joins (join_sub, left_join_sub, join_sub_with, left_join_sub_with). See Query Builder - Joins for the conditions a join takes.

$posts = Post::join('users', 'users.id', '=', 'posts.author_id')
    ->where('users.active', true)
    ->get();

let posts = Post::query()
    .join("users", "users.id", "=", "posts.author_id")
    .filter("users.active", true)
    .get()
    .await?;

Without a select, a model query with a join selects only the model's own columns ("posts".*), so the joined table's id, name, or created_at never lands in the model. Call select to choose the columns yourself; select(["posts.*"]) is the default spelled out. Qualify a column that both tables carry, such as users.active above. On a model that soft-deletes, the soft-delete filter names the model's table once the query joins another, so a joined table with its own deleted_at doesn't make the column ambiguous. The joined table's own soft-delete filter isn't applied, as in Laravel.

count and paginate count the joined rows. You use update or update_all to update matching base rows, and delete or delete_all to delete them. On a soft-delete model, deletion writes its tombstone; force_delete_all removes the rows. Every join and predicate still constrains these writes. increment_each still refuses joins.

You compare two columns with where_column(a, b) for equality or where_column_op(a, op, b) for another allowed operator.

Unions

let first  = User::filter("active", true);
let second = User::filter("role", "admin");
let users  = first.union(second).get().await?;
let users  = first.union_all(second).get().await?;

As in Laravel, an ordering, a limit, or an offset belongs to the whole union when you add it after union, and to the first query alone when you add it before. paginate, simple_paginate, cursor_paginate, first, and count all come after union, so they page, take, and count the rows of the union; a cursor bounds the rows of every arm:

let page = User::filter("active", true)
    .union(User::filter("role", "admin"))
    .order_by_desc("id")      // orders the union
    .paginate(20)             // pages the union; `total` counts its rows
    .await?;

let latest_active = User::filter("active", true)
    .order_by_desc("created_at")
    .limit(10)                // the ten newest active users only
    .union(User::filter("role", "admin"));

The union is wrapped as a subquery for these clauses, so order it by the bare names of its columns (id, not users.id). A UNION keeps one copy of a row both queries return, and total counts it once; union_all keeps both.

Row locking

Two builder methods request a per-row database lock at SELECT time:

// Exclusive write lock - blocks other transactions trying to lock
// or write the same rows until this transaction commits.
let order = Order::query()
    .filter("id", 42)
    .lock_for_update()
    .first_or_fail()
    .await?;

// Shared read lock - allows other shared readers, blocks writers.
let inventory = Inventory::query()
    .filter("sku", sku)
    .shared_lock()
    .first_or_fail()
    .await?;

Per-backend SQL emitted:

The lock clause is appended at the very end of the compound statement - after every UNION arm, every ORDER BY, every LIMIT / OFFSET. A union(...) of two builders followed by .lock_for_update() emits exactly one FOR UPDATE at the outer scope, not one per arm.

To reload a model you already hold and take the lock in the same statement, use refresh_for_update:

DB::transaction(|tx| async move {
    let mut order = Order::find_or_fail(42).await?;
    order.refresh_for_update().await?;   // SELECT ... WHERE id = ? FOR UPDATE
    order.status = "processed".into();
    order.save_with_tx(&tx).await?;
    Ok(())
}).await?;

Use inside a transaction

The lock only does useful work inside a transaction - without one, the SQL still emits but the lock releases at statement end. Pair with DB::transaction(...):

DB::transaction(|tx| async move {
    let order = Order::query()
        .filter("id", 42)
        .lock_for_update()
        .first_or_fail()
        .with_tx(&tx)
        .await?;
    // Other transactions trying to lock id=42 block here until commit.
    order.status = "processed".into();
    order.save_with_tx(&tx).await?;
    Ok(())
}).await?;

lock_for_update vs shared_lock

Most "read then write" flows want lock_for_update. A shared lock still lets another shared_lock reader race you to a following UPDATE - only FOR UPDATE is mutually exclusive.

shared_lock is right for consistent snapshot reads where you read a row, derive a decision from it, and don't write back - e.g. an inventory check that doesn't itself decrement stock.

SQLite

SQLite has no row-level locking. It uses file-level transaction locking only (BEGIN IMMEDIATE / BEGIN EXCLUSIVE). The lock methods are kept in the SQLite path so cross-backend code compiles, but they emit no SQL.

The first time per process that lock_for_update / shared_lock runs against a SQLite backend, the framework logs a single warn! on the suprnova::eloquent::lock tracing target. This surfaces the no-op without spamming high-volume code paths.

If you need cross-row contention guarantees on SQLite, wrap the critical section in an explicit BEGIN IMMEDIATE transaction - at the file level that blocks every other writer.

Not provided

• NOWAIT / SKIP LOCKED - useful for job-queue claim workflows but they add API surface, so they are added only when a real consumer needs them.

Transactions

Suprnova ships three entry points for database transactions plus nested-rollback via savepoints. Two of them - the closure form and the retry-on-deadlock helper - install an ambient context so model operations inside the closure auto-route through the transaction without callers threading a handle through every call site.

Closure form - DB::transaction

The closure form is the common case. The closure receives a &Transaction it can use to checkpoint with savepoint(name); every Model::* / Builder::* operation inside the closure auto-routes through the transaction: the closure's task carries it as the ambient transaction.

use suprnova::{DB, FrameworkError, Model};

DB::transaction(|_tx| {
    Box::pin(async move {
        let mut alice = User::query().filter("name", "alice").first_or_fail().await?;
        alice.balance -= 30;
        alice.save().await?;

        let mut bob = User::query().filter("name", "bob").first_or_fail().await?;
        bob.balance += 30;
        bob.save().await?;
        Ok::<(), FrameworkError>(())
    })
}).await?;

• Closure returns Ok → commit.
• Closure returns Err → rollback (original error propagates).
• Closure panics → rollback (the in-flight transaction is dropped on unwind; SeaORM's DatabaseTransaction::drop rolls back).

Reads inside the closure see writes from the same transaction (every leaf SQL call looks up the ambient transaction). The first DB::transaction call after process start picks the database backend off DB::connection(); subsequent calls reuse the same connection registry.

The signature uses a higher-ranked trait bound + Pin<Box<dyn Future>> so closures can borrow tx across .await points:

DB::transaction(|tx| {
    Box::pin(async move {
        // ... pre-savepoint work ...
        tx.savepoint("inner").await?;
        // ... inner work ...
        if some_condition {
            tx.rollback_to("inner").await?;
        }
        Ok::<(), FrameworkError>(())
    })
}).await?;

The Box::pin(async move { ... }) shape is the cost of letting the future use &tx after an .await - without it, the lifetime of the borrow can't escape the closure body. Mirrors SeaORM's TransactionTrait::transaction signature.

Savepoints - tx.savepoint(name) / tx.rollback_to(name)

Savepoints checkpoint the transaction so you can drop a block of inner work without aborting the outer commit. Works on all three backends - SQLite's SAVEPOINT is fully functional even though SQLite has no row-level locking.

DB::transaction(|tx| {
    Box::pin(async move {
        let mut account = Account::query().filter("id", id).first_or_fail().await?;
        account.balance = 200;
        account.save().await?;     // committed when the outer tx commits

        tx.savepoint("audit_trail").await?;

        let entry = AuditEntry::create(attrs! { actor_id: actor, ... }).await?;
        if audit_validation_failed(&entry) {
            tx.rollback_to("audit_trail").await?;
            // audit_trail row gone; account update still pending commit
        }

        Ok::<(), FrameworkError>(())
    })
}).await?;

The savepoint name is interpolated verbatim into the SQL - use a static identifier, do not splice user input.

Nested DB::transaction is rejected at runtime

DB::transaction(|_outer| Box::pin(async move {
    let inner = DB::transaction(|_inner| Box::pin(async move {
        Ok::<(), FrameworkError>(())
    })).await;
    // inner is Err(FrameworkError::Database(
    //     "nested DB::transaction is not supported; use tx.savepoint(name) for nested rollback"
    // ))
    Ok::<(), FrameworkError>(())
})).await?;

SeaORM's DatabaseConnection::begin() doesn't compose - calling it on a connection that's already holding a transaction starts a brand-new physical transaction that commits / rolls back independently of the outer scope. That's a silent data-integrity footgun, so DB::transaction checks for an ambient transaction up front and returns a database error instead of producing the wrong semantics. Use tx.savepoint(name) for nested behaviour.

Retry-on-deadlock - DB::transaction_with_attempts

Postgres SERIALIZABLE reads and MySQL row-level locks can raise serialization-failure / deadlock errors that resolve by retrying the transaction. transaction_with_attempts runs the closure from scratch each time, up to attempts:

DB::transaction_with_attempts(3, |_tx| {
    Box::pin(async move {
        // SERIALIZABLE-isolated logic that may race a concurrent
        // tx and surface SQLSTATE 40001 / 40P01 on commit.
        let inventory = Inventory::query()
            .filter("sku", sku)
            .lock_for_update()
            .first_or_fail()
            .await?;
        if inventory.units < requested {
            return Err(FrameworkError::bad_request("out of stock"));
        }
        Inventory::query()
            .filter("sku", sku)
            .update(attrs! { units: inventory.units - requested })
            .await?;
        Ok::<(), FrameworkError>(())
    })
}).await?;

Detection is by Display-string substring against the inner error:

• Postgres SQLSTATE 40001 (serialization_failure)
• Postgres SQLSTATE 40P01 (deadlock_detected)
• Case-insensitive "deadlock" substring (covers MySQL Deadlock found when trying to get lock and any user-surfaced deadlock string)

On the final attempt the error propagates unchanged. The closure runs from scratch on every attempt - capture owned state or Arcs rather than &mut references so the retry path is well-defined.

Caveat: because detection includes a case-insensitive "deadlock" substring (needed for MySQL whose driver doesn't surface a SQLSTATE), any inner error whose Display contains the word will trigger a retry. When raising your own errors from inside a transaction_with_attempts closure, avoid "deadlock" in the message - otherwise an unrelated validation error retries up to attempts times before propagating. The Postgres SQLSTATE matches (40001 / 40P01) are the reliable signal; the heuristic is for MySQL only.

Manual form - DB::begin_transaction + *_with_tx shims

When the transaction lifetime doesn't fit a closure (e.g. spans multiple control-flow branches), open a manual Transaction and opt each operation into it explicitly:

let tx = DB::begin_transaction().await?;

let mut user = User::query()
    .filter("name", "alice")
    .with_tx(&tx)
    .first_or_fail()
    .await?;
user.balance = 500;
user.save_with_tx(&tx).await?;

if some_condition {
    let mut other = User::query()
        .filter("name", "bob")
        .with_tx(&tx)
        .first_or_fail()
        .await?;
    other.update_with_tx(&tx, attrs! { balance: 200i64 }).await?;
}

tx.commit().await?;  // or tx.rollback().await?;

Manual mode does not install an ambient transaction. Scope individual operations through the transaction with Builder::with_tx(&tx) or the Model::*_with_tx(&tx, ...) shims:

Holding a Transaction pins one pool connection for the entire lifetime of the handle. On SQLite the pool has a single connection, so any parallel non-transactional read against the same database blocks until the transaction completes - load any pre-flight rows BEFORE DB::begin_transaction() and route every dependent write through the returned tx.

Transaction::commit / Transaction::rollback consume the handle and require Arc::try_unwrap of the inner SeaORM transaction; if any TxHandle clones (from tx.handle() / Builder::with_tx(&tx)) are still alive at commit / rollback time, both fail with a "TxHandle clones still alive" error. The correct fix is to drop your Builder<M> / outstanding handles before calling commit - the framework refuses to race a half-uncommitted write against a parallel writer holding the same tx.

Precedence

Three-way precedence for routing an operation through a connection:

1. Builder-level override - Builder::with_tx(&tx) or any Model::*_with_tx(&tx, ...) shim. Explicit beats ambient. The eager loads of such a query read through the same transaction, and those of an on(name) query read from that connection, unless the related model declares a connection of its own.
2. The ambient transaction - installed by DB::transaction / DB::transaction_with_attempts for the closure's task scope. A read that names another connection, through on(name) or a model's declared connection, still runs on that connection: the transaction is pinned to one database, so a read cannot join it there, and rerouting it would change which database the code reads from (audit finding ASTRA-06, 2026-09-13). Writes stay on the transaction, since atomicity must not split across connections.
3. Pool fallback - DB::connection() returns the global DbConnection singleton.

Inside DB::transaction(|tx| ...), calling Builder::with_tx(&other_tx) explicitly routes that one query through other_tx - bypassing the ambient transaction. That's almost certainly a bug; the override path exists for the manual form, not for overriding the closure's own tx.

with_tx and global scopes

A builder carrying a tx_override still respects global scopes, named scopes, and the eager-load plan - the override only changes the connection routing, not the SQL.

Relations and DDL inside a transaction

• Relation eager loads - Builder::with(["posts"]) and Collection::load(["posts"]) run their IN (...) sub-queries through the active transaction, so pending writes inside a DB::transaction closure are visible to relations loaded there.
• DDL - DB::statement(...) inside a transaction runs the DDL against the transaction's connection, which Postgres allows; MySQL and MariaDB commit implicitly on DDL, so DDL is unsupported inside a Suprnova transaction on those engines (the same caveat as Laravel's DB::transaction).

Scopes

Suprnova ships two flavours of scope, mirroring Laravel:

• Local scopes - extension methods on the builder, declared per model with #[suprnova::scopes(Model)]. Each free function in the annotated impl block becomes both Model::name() (a static starter) and Builder::name() (a chainable method).
• Global scopes - implementations of GlobalScope<M> registered at boot via ScopeRegistry::register::<M, _>(scope). Every Model::query() call layers them on automatically.

Local scopes

Declare local scopes by giving them the shape fn(query: Builder<Self>, args...) -> Builder<Self>:

#[suprnova::scopes(User)]
impl User {
    pub fn active(query: Builder<Self>) -> Builder<Self> {
        query.filter("active", true)
    }

    pub fn popular(query: Builder<Self>, threshold: i64) -> Builder<Self> {
        query.filter_op("followers_count", ">", threshold)
    }
}

// Use as either a starter or a chainable method:
let active_users  = User::active().get().await?;
let popular_users = User::query().active().popular(500).get().await?;

A method that does not handle a Builder passes through unchanged, so scopes and ordinary methods can share one impl block.

A method that takes or returns a Builder in any other form is a scope written wrong, and the macro refuses it with a compile error that names the accepted shape. This covers a first parameter of &mut Builder<User> or &Builder<Self>, a model name in place of Self (Builder<User>), and a missing Builder<Self> return type. Left alone, such a method would be an ordinary method and no .name() would reach the builder. Put #[not_scope] on a helper that handles a builder and is not a scope:

#[suprnova::scopes(User)]
impl User {
    #[not_scope]
    fn describe(query: &Builder<User>) -> String {
        query.to_sql()
    }
}

Global scopes

Global scopes apply on every Model::query() call. The classic use case is multi-tenancy - every read is scoped to the current tenant without each caller threading the filter through.

use suprnova::eloquent::scopes::{GlobalScope, ScopeRegistry};

pub struct TenantScope;

impl GlobalScope<Article> for TenantScope {
    fn apply(&self, query: Builder<Article>) -> Builder<Article> {
        // Reads the current tenant from a task-local /
        // AtomicI64 / wherever per-request state lives.
        query.filter("tenant_id", current_tenant_id())
    }
}

// At boot - typically inside your provider/bootstrap module:
ScopeRegistry::register::<Article, _>(TenantScope);

// Every read is auto-scoped to the active tenant:
let scoped = Article::query().get().await?;

Multiple scopes per model compose in registration order - first registered runs first, so its filter clauses appear first in the WHERE chain. AND-combined filters don't care about order, but left-to-right matters for any clause whose side-effect order is visible (e.g. ordering, having, raw fragments).

You call apply_scopes() to keep a builder with its registered scopes and soft-delete filter already applied. You inspect the resulting SQL or run the same builder. Repeated calls keep each scope's clauses once. You set without_global_scopes() or with_trashed() before applying scopes when you need those opt-outs.

let query = Article::query().apply_scopes();
let sql = query.to_sql();
let rows = query.get().await?;

Opting out of a global scope

Each model the #[suprnova::model] macro touches gets two static helpers emitted on it:

// Bypass exactly one registered scope by type. Other scopes still apply.
let all_tenants = Article::without_global_scope::<TenantScope>().get().await?;

// Bypass every registered scope. Admin tooling pattern.
let everything = Article::without_global_scopes().get().await?;

The opt-outs also chain on a Builder: Model::query().without_global_scope::<S>() and Model::query().without_global_scopes() return the same rows as the static helpers, wherever you write them in the chain.

The builder applies global scopes when the query runs, not when Model::query() builds it. The statement reads <scopes> AND <your terms>. Your own terms stay together after the scopes: an or_where never widens past a scope. update_all, delete_all, and increment_each resolve scopes the same way, so a mass write reaches only the rows a read returns. A scope that reads per-request state reads it when the query runs.

Where global scopes apply

This mirrors Laravel: Eloquent\Model::find doesn't trigger addGlobalScopes. Callers that want scoped PK lookups use Self::query().filter("id", pk).first().await?.

Soft deletes and global scopes coexist

#[suprnova::model(soft_deletes)] installs the deleted_at IS NULL filter via a separate string-tag mechanism, not through the typed scope registry. Both layers compose:

• Model::query() filters out trashed rows AND runs every registered scope.
• Model::without_global_scopes() drops registered scopes but preserves the soft-delete filter - admin tooling that wants to read every column-set still excludes trashed rows by default.
• Model::with_trashed() and Model::only_trashed() lift only the soft-delete filter. Every registered scope still runs, so a tenant scope keeps trashed reads inside the tenant, as Laravel's withTrashed() does.

Relationships

Suprnova ships every Eloquent relation flavour. They're declared in the relations = { ... } block on #[suprnova::model], and the macro emits - per declared relation - a method on the struct, a loaded-accessor (<name>_loaded()), a count-accessor (<name>_count()), and the dispatcher arm the eager loader calls into. This section covers the per-kind shape and option table; the deep dive on join-key resolution, the morph registry, pivot rows, and the polymorphic enum lowering lives in Eloquent Relationships. The relation kinds:

relations = { ... } syntax

Every relation declaration carries the same outer shape: the relation name, the kind, the related type (and pivot/intermediate types where applicable), and a { ... } block of options.

use suprnova::model;

#[model(
    table = "users",
    relations = {
        // HasMany<R>
        posts: HasMany<crate::models::Post> {
            fk = "author_id",         // override default `user_id`
        },
        // BelongsToMany<R, Pivot>
        roles: BelongsToMany<crate::models::Role, crate::models::RoleUser> {
            with_pivot = ["assigned_at"],
            with_timestamps,
        },
    },
)]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}

Common options:

Why Suprnova diverges: default foreign key names

A default foreign key column always ends in _id. Laravel ends it in the parent model's primary key name instead (getForeignKey() is the snake-cased class name, _, and getKeyName()), so the two agree for the usual id key and differ for any other. BelongsTo differs in the name as well: Laravel takes it from the relation, Suprnova from the target model.

Most schemas name the column <model>_id whatever the parent's key is called, as Laravel's own $table->foreignUuid('user_id') does, so the default matches the column you would write. The join column on the other side already follows the model: lk, related_key and the owner key default to the model's primary key. When you mirror a Laravel schema whose columns follow Laravel's rule, name them with fk = "...", pivot_foreign_key, pivot_related_key, first_key or second_key.

HasOne<R> and BelongsTo<R>

One-to-one in both directions. HasOne lives on the parent side and calls R::query().filter(<fk>, <self.id>).first(). BelongsTo lives on the child side and reads the FK off self, then calls R::query().filter(<owner_key>, <fk_value>).first().

#[model(table = "users", relations = {
    profile: HasOne<crate::models::Profile>,
})]
pub struct User { /* ... */ }

#[model(table = "profiles", relations = {
    user: BelongsTo<crate::models::User>,
})]
pub struct Profile {
    pub id: i64,
    pub user_id: i64,
    pub bio: String,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}

let user = User::find(1).await?.unwrap();
let profile: Option<Profile> = user.profile().first().await?;

let profile = Profile::find(42).await?.unwrap();
let owner: Option<User> = profile.user().first().await?;

BelongsTo supports with_default = || R { ... }, which fires either when the FK is null OR when the parent row is missing. The default closure runs per call (and per eager-loaded row) - perfect for an empty stand-in when a deleted user still has comments:

#[model(table = "comments", relations = {
    author: BelongsTo<crate::models::User> {
        with_default = || User {
            name: "[deleted]".into(),
            ..Default::default()
        },
    },
})]
pub struct Comment { /* ... */ }

let c = Comment::find(99).await?.unwrap();
// Always Some - the default fires when the user row is missing.
let author = c.author().first().await?.unwrap();

HasMany<R>

One-to-many on the parent side. Returns a fluent builder; chain filter / order / latest / take / get / count and terminate.

#[model(table = "users", relations = {
    posts: HasMany<crate::models::Post> {
        fk = "author_id",
    },
})]
pub struct User { /* ... */ }

let u = User::find(1).await?.unwrap();

// Every post by this user, default ordering:
let posts: Vec<Post> = u.posts().get().await?;

// Filtered + ordered + paged:
let recent = u.posts()
    .filter("published", true)
    .latest()                          // ORDER BY created_at DESC
    .take(10)
    .get()
    .await?;

// COUNT alone - no row fetching:
let total: i64 = u.posts().count().await?;

Available terminal methods: .first(), .get(), .count(). Available chainable filters: .filter / .db_where, .filter_in / .where_in, .order_by, .latest, .oldest, .limit, .take.

BelongsToMany<R, P> - first-class Pivot

Many-to-many through a #[suprnova::model]-declared pivot. The pivot is a first-class model with its own row identity - not a tuple, not a hidden hash map. Two key benefits over Laravel's anonymous-pivot shape:

1. The pivot row is type-safe. Read with_pivot columns via r.pivot::<P>().<column>, never via r.pivot.get("...").
2. The pivot model is reachable from the rest of the framework (factories, scopes, casts, hooks) the same way every model is.

#[model(table = "role_user", fillable = ["user_id", "role_id", "assigned_at"])]
pub struct RoleUser {
    pub id: i64,
    pub user_id: i64,
    pub role_id: i64,
    pub assigned_at: Option<chrono::DateTime<chrono::Utc>>,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}

#[model(table = "users", relations = {
    roles: BelongsToMany<crate::models::Role, RoleUser> {
        with_pivot = ["assigned_at"],
        with_timestamps,
    },
})]
pub struct User { /* ... */ }

let u = User::find(1).await?.unwrap();
let admin = Role::create(attrs! { name: "admin" }).await?;

// Attach + sync mutators
u.roles().attach(admin.id).await?;
u.roles().attach_with(admin.id, attrs! { assigned_at: chrono::Utc::now() }).await?;
u.roles().sync([role_a.id, role_b.id, role_c.id]).await?;
u.roles().sync_without_detaching([role_d.id]).await?;
u.roles().detach(admin.id).await?;

// Read pivot data through the per-row downcast accessor:
let roles = u.roles().get().await?;
for r in &roles {
    let p: &RoleUser = r.pivot::<RoleUser>();
    println!("user {} got role {} at {:?}", p.user_id, p.role_id, p.assigned_at);
}

• .attach(id) - INSERT a single pivot row. Errors on duplicate unless your pivot allows it (the framework doesn't dedupe at the Rust layer; use .sync for idempotency).
• .attach_with(id, attrs! { ... }) - INSERT with extra pivot columns. Stamps timestamps when with_timestamps is on.
• .detach(id) - DELETE the pivot row(s) linking parent → id.
• .sync([ids...]) - diff-and-apply: attach what's new, detach what's missing, update supplied pivot columns on existing rows. You receive SyncChanges with attached, detached and updated id lists.
• .sync_without_detaching([ids...]) - attach what's new and keep every existing row. You can supply (id, attrs! { ... }) records to update existing pivot columns. Unchanged rows keep their timestamps, and the returned SyncChanges.detached is empty.

You pass ids alone or (id, Attrs) records to either sync method. Only rows whose supplied columns change appear under updated. Pivot filters constrain the current set, updates and detachments; rows outside that set remain unchanged. All changes run in one transaction. You call .touch_parent() to update the parent's timestamp when sync changes the relation; the touch commits or rolls back with the pivot writes.

Each id and extra column binds by the type its column has: the pivot model's field, or else the key the column holds. On Postgres and SQLite, a u64 above i64::MAX written to the pivot fails with an error that names the column, and nothing is sent. detach of such an id deletes nothing on Postgres, and on SQLite it compares the id's digits, as it does a literal. On MySQL an unsigned pivot column holds the whole u64 range, and sync and .get() read its ids back.

.get() returns Vec<R> with the pivot stamped on each row's internal __pivot field. The .pivot::<P>() accessor downcasts the Arc<dyn Any> to the pivot type you declared. Calling it with the wrong type panics - match the type to the declared pivot.

HasOneThrough<B, R> and HasManyThrough<B, R>

Reach a final target R through an intermediate B. Useful when the relation traverses two tables but you don't need to expose the intermediate (A → B → R).

#[model(table = "countries", relations = {
    posts: HasManyThrough<crate::models::User, crate::models::Post>,
})]
pub struct Country {
    pub id: i64,
    pub name: String,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}

let c = Country::find(1).await?.unwrap();
let posts: Vec<Post> = c.posts().get().await?;

The dispatcher infers JOIN keys from struct names. Overrides:

The parent's primary-key column is read from the model's primary_key declaration (defaulting to "id") - there is no local_key override on HasManyThrough / HasOneThrough; change the parent's PK via the #[suprnova::model] attribute if you need a non-id parent key.

#[model(table = "countries", relations = {
    posts: HasManyThrough<crate::models::User, crate::models::Post> {
        first_key = "country_id",
        second_key = "author_id",
    },
})]
pub struct Country { /* ... */ }

MorphTo with targets = [...] and per-family enum

Polymorphic relations point a child row at one of several parent families. The child carries a (<name>_id, <name>_type) pair; the *_type column holds the morph-type string each parent declares.

MorphTo lives on the child. Its declaration lists every parent family it can point at via targets = [...]. The macro emits a per-family enum named <RelationName>Morph (matching the relation name's PascalCase form, suffixed with Morph) with one variant per target type plus Unknown(String, serde_json::Value) for legacy rows whose <name>_type value doesn't match any registered target. The second field is the value of <name>_id as JSON: a number for an integer key, a string for a String, UUID or ULID key, null for a null column.

#[model(table = "posts", morph_type = "post")]
pub struct Post { /* ... */ }

#[model(table = "videos", morph_type = "video")]
pub struct Video { /* ... */ }

#[model(table = "comments", relations = {
    commentable: MorphTo {
        name = "commentable",
        targets = [
            crate::models::Post,
            crate::models::Video,
        ],
    },
})]
pub struct Comment {
    pub id: i64,
    pub commentable_id: i64,
    pub commentable_type: String,
    pub body: String,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}

let c = Comment::find(1).await?.unwrap();
match c.commentable().get().await? {
    CommentableMorph::Post(post)   => println!("comment on post {}", post.title),
    CommentableMorph::Video(video) => println!("comment on video {}", video.url),
    // Legacy / dangling rows - `<name>_type` doesn't match any target,
    // OR the morph_type matched but the row at `<name>_id` is gone.
    CommentableMorph::Unknown(ty, id) => {
        eprintln!("comment {} points at unknown {ty}#{id}", c.id);
    }
}

The morph_type = "..." attribute on each target struct is what the loader writes into the child's <name>_type column on insert and filters by on read. Without morph_type, the framework derives the type-string from to_snake(struct_name).

MorphTo dispatch - how the per-family enum picks the right variant - consults the runtime morph registry (the inventory populated by every #[suprnova::model(morph_type = "...")] declaration). For each declared target, the fetch helper looks up the target's TypeId, reads the registered morph_type string, and compares it against the stored <name>_type value on the child row. First match wins, in declaration order. Targets without an explicit morph_type attribute fall back to to_snake(target_type_name) - the same default the parent-side MorphMany / MorphOne uses to stamp the type-string at write time, so the two sides stay aligned. This means custom morph_type values (e.g. morph_type = "blog_post" on a struct named Post, or any non-conventional string) dispatch correctly without changes to the declaration site.

MorphOne<R> and MorphMany<R> - parent side

The inverse direction of MorphTo: a parent type declares the polymorphic one-or-many it owns. MorphOne returns Option<R> from .first(); MorphMany returns Vec<R> from .get(). Both filter the child's (<name>_id, <name>_type) pair by self.id and the parent's morph_type.

#[model(table = "posts", morph_type = "post", relations = {
    comments: MorphMany<crate::models::Comment> {
        name = "commentable",
    },
    cover: MorphOne<crate::models::Image> {
        name = "imageable",
    },
})]
pub struct Post { /* ... */ }

#[model(table = "videos", morph_type = "video", relations = {
    comments: MorphMany<crate::models::Comment> {
        name = "commentable",
    },
})]
pub struct Video { /* ... */ }

let post = Post::find(1).await?.unwrap();
let post_comments: Vec<Comment> = post.comments().get().await?;
let post_cover:    Option<Image> = post.cover().first().await?;

let video = Video::find(1).await?.unwrap();
let video_comments: Vec<Comment> = video.comments().get().await?;
// post.comments() returns only `commentable_type = "post"` rows;
// video.comments() returns only `commentable_type = "video"`.

The same chainable surface as HasMany / HasOne: .filter / .db_where, .order_by / .latest / .oldest, .limit / .take, .first / .get / .count.

MorphToMany<R, P> and MorphedByMany<R, P>

Polymorphic many-to-many. The shared pivot P carries the FK pair PLUS a <name>_type discriminator column. One end declares MorphToMany (e.g. Post.tags(), Video.tags()), the other end declares one MorphedByMany per target family (e.g. Tag.posts(), Tag.videos()).

#[model(table = "taggables", fillable = ["tag_id", "taggable_id", "taggable_type"])]
pub struct Taggable {
    pub id: i64,
    pub tag_id: i64,
    pub taggable_id: i64,
    pub taggable_type: String,
}

#[model(table = "posts", morph_type = "post", relations = {
    tags: MorphToMany<crate::models::Tag, Taggable> {
        name = "taggable",
    },
})]
pub struct Post { /* ... */ }

#[model(table = "videos", morph_type = "video", relations = {
    tags: MorphToMany<crate::models::Tag, Taggable> {
        name = "taggable",
    },
})]
pub struct Video { /* ... */ }

// Inverse: Tag declares one MorphedByMany per target family.
#[model(table = "tags", relations = {
    posts: MorphedByMany<crate::models::Post, Taggable> {
        name = "taggable",
        target_morph_type = "post",
    },
    videos: MorphedByMany<crate::models::Video, Taggable> {
        name = "taggable",
        target_morph_type = "video",
    },
})]
pub struct Tag { /* ... */ }

let post  = Post::find(1).await?.unwrap();
let video = Video::find(1).await?.unwrap();
let tag   = Tag::create(attrs! { name: "rust" }).await?;

// `attach` / `attach_with` / `detach` / `sync` / `sync_without_detaching`
// work the same way as BelongsToMany. The `<name>_type` column lands automatically from
// the calling parent's `morph_type`.
post.tags().attach(tag.id).await?;
video.tags().attach(tag.id).await?;          // independent attachment
post.tags().sync([tag_a.id, tag_b.id]).await?;

// Inverse direction - Tag splits by family:
let posts_with_tag:  Vec<Post>  = tag.posts().get().await?;   // typed "post"
let videos_with_tag: Vec<Video> = tag.videos().get().await?;  // typed "video"