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
• 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, applied through Model::global_scope::<GS>(). 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 saves explicitly

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 save().await?.

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.

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?;

save() walks every non-PK field, sets them on the ActiveModel via Set(...), calls SeaORM's update(), and returns the canonical row. update(attrs) is the same flow but applies a partial attribute map first (running the Fillable filter and any declared mutators).

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
$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?;
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. replicate builds an in-memory clone with the PK reset (Default::default() for the key type). Caller saves explicitly.

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 T::save - the normal Saving / Created chain still fires inside save.

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

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.

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.

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 avg     = Order::avg::<f64>("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?;

Aggregates are generic over the return type because SeaORM needs to know what to coerce the DB scalar to. Type defaults: count -> i64; sum/avg carry an explicit type parameter. 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. An incompatible requested Rust type or missing result column is a database error; it is never converted into a plausible zero or None.

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 sql:    String             = User::filter("...").to_sql();

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>).

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?;

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.

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.

What's not in v1

• NOWAIT / SKIP LOCKED - useful for job-queue claim workflows but they add API surface. Deferred until 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 via a tokio::task_local! called CURRENT_TX.

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 (via CURRENT_TX lookup at every leaf SQL call). 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 CURRENT_TX 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 CURRENT_TX. 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.
2. Ambient CURRENT_TX - installed by DB::transaction / DB::transaction_with_attempts for the closure's task scope.
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 CURRENT_TX. 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.

Limitations (v1)

• Relation eager loads - Builder::with(["posts"]) and Collection::load(["posts"]) route the eager IN (...) sub-queries through DB::connection(), not through the active transaction. Pending writes inside a DB::transaction closure are not visible to relations loaded via .with(...). For now, scope tx work to direct Model::* / Builder::* / DB::table(...) calls; defer relation loads until after the outer write lands (or before DB::begin_transaction on the manual path). This is a known seam - the routing helper (ExecutorChoice) is already in place at every SQL leaf; the blocker is EagerLoadDispatch::eager_load taking &DatabaseConnection (concrete), which the macro emits for every relation kind. A follow-up sweep will adapt the trait to the dispatch helper.
• DDL on Postgres - DB::statement(...) inside a transaction runs the DDL against the tx connection, which Postgres allows; MySQL implicitly commits and is therefore unsupported inside a Suprnova transaction (this matches Laravel's DB::transaction caveat).

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?;

Non-scope methods declared in the same impl block (anything whose first parameter isn't query: Builder<Self>) pass through unchanged.

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).

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?;

Important: the opt-out helpers must be the entry point. Chaining .without_global_scope::<S>() onto a builder already returned by Model::query() doesn't undo scopes that have already run - Model::query() applies scopes eagerly at construction time, so the mask is set too late. Use the per-model static helpers (above) for correct semantics.

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() skip soft-delete filtering and also bypass the registry (they build a fresh unscoped builder). Pair with .without_global_scope::<S>() if you need scope-aware reads over trashed rows.

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 shipped today:

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:

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().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, leave the intersection alone. Wrapped in a transaction.

.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, i64) for legacy rows whose <name>_type value doesn't match any registered target.

#[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` 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"

MorphedByMany's target_morph_type is required because the macro at Tag's declaration site can't introspect the target's morph_type = "..." attribute (it lives in a separate #[suprnova::model] invocation). Setting it explicitly keeps each MorphedByMany arm honest about which family it scans.

Escape hatch: hand-written relation methods

The relations declared in relations = { ... } are the only ones the eager-load dispatcher (and with, with_count, etc.) knows about. If a relation is too unusual for the macro shape - for example a query that aggregates across two pivots, or a typed view of a denormalised cache table - you can omit it from relations = { ... } and write a plain inherent impl:

impl User {
    /// Posts this user authored OR is tagged in. Crosses two relations
    /// and is therefore not expressible as a single `relations = { ... }`
    /// declaration - written by hand.
    pub async fn posts_touched(&self) -> Result<Vec<Post>, FrameworkError> {
        let authored: Vec<Post> = self.posts().get().await?;
        let tagged:   Vec<Post> = /* ...custom query... */;
        // ...merge + dedupe...
        Ok(/* ... */)
    }
}

Such methods lose eager-load support - User::with(["posts_touched"]) will error because the dispatcher has no arm for posts_touched. The in-macro declarations remain the path the framework knows how to eager-load, count, aggregate, and predicate-filter.

v1 restrictions

A handful of things the v1 surface holds off on. Each is documented at its declaration site too - collected here for visibility:

• Morph IDs are i64-only. MorphTo::morph_id is hardcoded to i64, so any model used as a MorphTo target must declare an i64 primary key, and the child table's <name>_id column must also be i64. String / UUID-as-string morph FKs are v2.
• No nested eager loading through MorphTo. The per-family enum erases the child type, so a dotted path like with(["commentable.user"]) can't tail-recurse - the dispatcher returns a typed error. Resolve per-family by matching on the enum and calling with(["user"]) on each variant individually.

Eager loading

Eager loading avoids N+1 queries. Instead of posts.len() queries to fetch every user's posts, Suprnova issues ONE query per top-level relation regardless of how many parent rows are loaded.

The full surface - flat list, nested paths, count, aggregates, and predicate-filtered eager loads - is reached through the #[suprnova::model]-emitted helpers on each model:

// Single relation:
let users = User::with(["posts"]).get().await?;
for u in &users {
    for p in u.posts_loaded() { /* ... */ }
}

// Multiple relations:
let users = User::with(["posts", "profile"]).get().await?;

// Nested paths - three queries (users + posts + comments), no N+1:
let users = User::with(["posts.comments"]).get().await?;
let p1 = users[0].posts_loaded()[0];
let comments = p1.comments_loaded();

// Deeper nesting works as expected:
let users = User::with(["posts.comments.author"]).get().await?;

// Count alongside the parent rows:
let users = User::with_count(["posts"]).get().await?;
for u in &users {
    println!("{} has {} posts", u.name, u.posts_count());
}

// Aggregates - Sum / Avg / Min / Max over a relation column. The
// ergonomic read is the macro-emitted `<rel>_sum_of(col)` accessor.
let users = User::with_sum(("posts", "views")).get().await?;
let sum: f64 = users[0]
    .posts_sum_of("views")
    .expect("with_sum populated the cache");

// Multiple aggregates on the same relation compose - the cache key
// is the wide `<rel>_<kind>_<col>` form, so distinct kinds and
// distinct columns don't collide:
let users = User::with_sum(("posts", "views"))
    .with_avg(("posts", "views"))
    .with_min(("posts", "id"))
    .get()
    .await?;
let u = &users[0];
let sum = u.posts_sum_of("views").unwrap();   // Some(_) - sum of views
let avg = u.posts_avg_of("views").unwrap();   // Some(_) - avg of views
let min = u.posts_min_of("id").unwrap();      // Some(Some(_)) - non-empty group
let max = u.posts_max_of("id");               // None - with_max was not called

// Filter the eager-loaded children. The macro emits a typed
// `with_where_<rel>(closure)` static helper per relation so the closure
// parameter type is inferred - no need to spell out `Builder<Post>`:
let users = User::with_where_posts(|q| q.filter("published", true))
    .get()
    .await?;
// The returned `Builder<User>` chains with any other base-query
// builder method:
let users = User::with_where_posts(|q| q.filter("published", true))
    .filter("active", true)
    .get()
    .await?;
// The generic form is still available - useful when the relation name
// is computed at runtime - but you'll need to name the target type on
// the closure:
let users = User::query()
    .with_where(("posts", |q: Builder<Post>| q.filter("published", true)))
    .get()
    .await?;
// Each u.posts_loaded() contains only published posts.

Cache layout

The per-row __eager cache cells are keyed by:

• <rel> (relation NAME alone) for with and with_count.
• <rel>_<kind>_<col> (e.g. posts_sum_views) for the four aggregate kinds - with_sum / with_avg / with_min / with_max. This wide key lets multiple aggregates on the same relation coexist on the same row without overwriting each other.

The macro emits matching accessors on each model:

• <rel>_loaded() - for collection relations: &[Post] (panics if the relation wasn't eager-loaded). For single-value relations: Option<&Profile>.
• <rel>_count() - u64. Panics if with_count(["..."]) wasn't called.
• <rel>_sum_of(col) / <rel>_avg_of(col) - return Option<f64> (None if the matching with_sum / with_avg was not called).
• <rel>_min_of(col) / <rel>_max_of(col) - return Option<Option<f64>>: outer Option is "was with_min / with_max called?", inner Option is "did SQL return NULL because the group was empty?".

The accessors are the ergonomic surface - read through them rather than reaching into __eager.get_aggregate::<T>(...) directly. They build the same cache key under the hood via eloquent::relations::aggregate_cache_key.

Composing aggregates on the same relation

The wide cache key means you can stack as many with_* calls on the same relation in one query as you want - no collisions:

let users = User::with_sum(("posts", "views"))
    .with_avg(("posts", "views"))
    .with_min(("posts", "id"))
    .with_max(("posts", "id"))
    .get()
    .await?;

let u = &users[0];
let total_views: f64 = u.posts_sum_of("views").unwrap();
let avg_views:   f64 = u.posts_avg_of("views").unwrap();

// Min/Max are double-Option because SQL min/max NULLs on empty:
match u.posts_min_of("id") {
    None              => panic!("with_min not called"),
    Some(None)        => println!("no posts yet"),
    Some(Some(min))   => println!("smallest post id: {min}"),
}

// Accessor returns `None` when the matching `with_*` was skipped:
assert!(u.posts_avg_of("score").is_none()); // never called with col="score"

Aggregates and INTEGER columns

SUM over an INTEGER column lands in the cache as f64. The dispatcher arms try try_get::<Option<f64>> first, then fall back to try_get::<Option<i64>>().map(|n| n as f64) so SQLite's INTEGER- preserving COUNT/SUM types don't silently coerce to 0.0. Read via the macro-emitted accessors regardless of the source column type.

with_where predicate routing

User::with_where_posts(|q| q.filter("published", true)) applies a closure to the inner Builder<Post> BEFORE the filter_in(<fk>, parent_ids) IN-query is issued, so only matching child rows reach the cache. The macro emits one typed with_where_<rel> static helper per declared relation, so the closure's parameter type is inferred from the method signature.

The generic with_where(("posts", |q: Builder<Post>| q.filter("published", true))) is still available - useful when the relation name is computed at runtime, or when you already hold a Builder<User> and want to attach a predicate. It requires naming the target type on the closure because the predicate goes through a Box<dyn Any> and Rust can't infer the type from the relation name alone. (Rust's orphan rules forbid the macro from adding a typed method directly on Builder<User>, so the typed shorthand is offered only on the model - User::with_where_<rel> - not as a builder-chain method.)

For the polymorphic kinds, the predicate runs against the related-table query - not the pivot scan.

with_where is supported on every relation kind EXCEPT MorphTo. MorphTo's per-family enum erases the child type, so no single Builder<R> covers all variants. Nested eager loading through MorphTo is also not supported in v1 - with(["commentable.user"]) where commentable is a MorphTo returns an error from the recurse-eager-load dispatcher.

Collection::load / load_missing

When you've already fetched rows and want to eager-load relations after the fact:

use suprnova::Collection;

let mut users: Collection<User> = User::all().await?.into();
users.load(["posts.comments"]).await?;

load_missing is per-row: each row in the collection is partitioned independently. Rows that already have the named relation cached stay untouched; rows that don't get the relation loaded. Mirrors Laravel's $collection->loadMissing(...) semantics.

For nested paths the partition repeats at every level. Given load_missing(["posts.comments"]):

• Rows without posts cached get the FULL path loaded - posts plus their comments.
• Rows WITH posts already cached recurse into the cached posts and load comments only on the posts that don't already have comments cached.

The same per-row partition repeats at every further segment of a longer dotted path ("posts.comments.author" etc.) - at each step only the rows missing that segment get the bulk-load.

Pagination

Three paginator types compose on top of Builder<M>:

All three implement Serialize with the Laravel-standard JSON shape, so they ship directly to Inertia / JSON consumers without reshaping.

Length-aware

use suprnova::LengthAwarePaginator;

let page: LengthAwarePaginator<User> = User::query()
    .filter("active", true)
    .order_by_desc("created_at")
    .paginate(20)
    .await?;

// page.data: Vec<User>
// page.total: u64 - total row count across all pages
// page.last_page: u64 - 1-based last page index
// page.current_page: u64
// page.per_page: u64
// page.from / page.to: Option<u64> - 1-based window bounds
// page.path: Option<String> - optional base URL for link generation

Page-param parsing reads ?page=N from the active request via Context::query_param. To paginate multiple lists on the same page with their own query keys, use paginate_using:

let posts = Post::query().paginate_using("posts_page", 10).await?;
let comments = Comment::query().paginate_using("comments_page", 25).await?;

JSON shape:

{
  "data": [...],
  "current_page": 1,
  "last_page": 3,
  "per_page": 10,
  "total": 25,
  "from": 1,
  "to": 10,
  "path": "/api/users"
}

path is omitted from JSON when unset.

Simple paginate (no count)

paginate always runs two queries - a COUNT(*) plus the page fetch. On large tables the count alone can dominate request time. simple_paginate skips the count entirely; instead it fetches per_page + 1 rows and reports whether a next page exists via the has_more flag:

use suprnova::Paginator;

let page: Paginator<User> = User::query()
    .order_by_desc("id")
    .simple_paginate(20)
    .await?;

// page.has_more: bool - was there an extra row past per_page?
// page.current_page, page.per_page, page.data, page.path: as above.

JSON shape:

{
  "data": [...],
  "current_page": 1,
  "per_page": 10,
  "has_more": true
}

Cursor paginate (keyset)

Cursor paginate is the choice for infinite scroll, deep pagination, or anywhere a stable row order with cheap O(1)-per-page seeking is worth more than a numeric page UI. Bidirectional - it reads the ?cursor=<opaque> query parameter, walks forward or backward by the cursor's direction, and emits both next_cursor and prev_cursor as the page's neighbours exist (matching Laravel's cursorPaginate()).

use suprnova::CursorPaginator;

let page: CursorPaginator<User> = User::query()
    .cursor_paginate(20)
    .await?;

// page.data: Vec<User>
// page.per_page: u64
// page.next_cursor: Option<String> - opaque cursor for the next page (None on the last)
// page.prev_cursor: Option<String> - opaque cursor for the previous page (None on the first)
// page.path: Option<String>

Cursors are encrypted and authenticated via CursorPaginator::encode_value - they encode the keyset boundary (the model's primary key) plus a direction tag, AES-256-GCM-sealed with the framework's APP_KEY. Tampering produces a 400 ParamParse error; the cursor is opaque to the client and unforgeable without the key.

The next request passes the cursor through ?cursor=<opaque>:

GET /api/users?cursor=eyJ0IjoiQmlnSW50IiwidiI6MTAwLCJkIjoibmV4dCJ9...

Cursor pagination replaces any existing ORDER BY on the builder - a stable PK ASC order is required for gt(boundary) to slice deterministically.

JSON shape:

{
  "data": [...],
  "per_page": 10,
  "next_cursor": "...",
  "prev_cursor": null,
  "path": "/api/users"
}

next_cursor and prev_cursor are always present as JSON keys (emitted as null when absent) so client schemas can rely on the field's presence; path is omitted when unset.

Errors

Cursor authentication failure surfaces as Internal (not ParamParse) so a tampered cursor doesn't leak protocol-level information to the client; the response body still carries a human-readable reason.

Reading query params outside a real request

Tests, console commands, and background workers don't run inside a hyper request - so Context::query_param("page") returns None and paginate falls back to page 1. Tests that need to exercise a specific page can install a per-thread override:

use suprnova::context::Context;

#[tokio::test]
async fn paginate_page_2() {
    Context::test_clear_query();
    Context::test_set_query("page", "2");

    let page = User::query().paginate(10).await.unwrap();
    assert_eq!(page.current_page, 2);

    Context::test_clear_query();
}