Declaring models

Full-text search is not the REST ?search= parameter. They are two different mechanisms:

• REST /api//?search=term is a case-insensitive substring match (UPPER(col) LIKE UPPER('%term%'), case-insensitive contains) across the resource's text columns. tsvector columns are skipped by ?search=. So ?search=best product finds rows whose text literally contains the substring best product, and ?search=tseb finds rows literally containing tseb; forgiving, but it doesn't stem, rank, or use the GIN index.
• TsVector + .matches() / .matches_websearch() is the ORM-level, index-backed, lexeme-based search shown above. There is currently no automatic ?search= → tsvector wiring; to expose full-text search over HTTP today you add a custom resource action or a dedicated query parameter that calls .matches_websearch(...). (Wiring ?search= to prefer a model's tsvector column when one exists is a tracked enhancement.)

Rule of thumb: reach for ?search= for quick "contains this text" filtering on small/medium tables; reach for a TsVector column when you want word-aware, ranked, index-backed search at scale.

The table name

By default the table is snake_case of the struct name: BlogPost becomes blog_post. Override with the struct-level attribute when you need a different name:

#[derive(Debug, Clone, sqlx::FromRow, umbral::orm::Model)]
#[umbral(table = "auth_user")]
pub struct User {
    pub id: i64,
    pub username: String,
}

Beyond table, the struct-level #[umbral(...)] also accepts plugin, display, icon, database, singleton, soft_delete, unique_together = [[...]], indexes = [[...]], and ordering = ["-col", "col"]. The field-level #[umbral(...)] accepts primary_key, unique, index, default = "...", on_delete = "..." / on_update = "...", auto_now / auto_now_add, max_length = N, min = N / max = N, string, noform, noedit, help = "...", example = "...", widget = "...", backend = "...", cidr, db_constraint = false, slug_from = "...", choices, reverse_fk = "...", and no_reverse. (choices pairs #[derive(Choices)] on the enum with #[umbral(choices)] on the field; see Column types - Using a Rust enum.)

Display hints (string, max_length)

Two field-level attributes shape how the admin renders a model when no list_display is configured:

#[derive(Debug, Clone, sqlx::FromRow, umbral::orm::Model)]
pub struct Article {
    pub id: i64,
    #[umbral(string, max_length = 60)]
    pub title: String,
    pub body: String,
    pub published_at: Option<chrono::DateTime<chrono::Utc>>,
}

• #[umbral(string)]: the model's human-readable label field (display field), opt-in. Tagging one field per model switches the admin's default list_display to that single column when no explicit config is registered. Without any field tagged, the changelist shows every column. The PK isn't rendered as a separate column because every row in the admin is clickable into the sheet, so the id is already reachable. The attribute is never required; it's how you ask for the compact single-column form. Equivalent shapes: #[umbral(string)] and #[umbral(string = true)].
• #[umbral(max_length = N)]: soft truncation cap for display. The admin trims the value at N characters when rendering it in list_display, appending … so the cut is visible. Counted in characters, not bytes, so emoji and combining characters survive intact.

Both attributes are display-only; they do not constrain the column at the SQL level. A String field with max_length = 60 is still TEXT (unbounded) at the database; the cap only affects how the admin renders cells. Use #[umbral(table = "...")] plus a manual CHECK constraint via a custom migration if you want the limit enforced at the DB.

Plugin-namespaced tables

When two plugins each ship a model with the same struct name (for example, a blog plugin and a shop plugin both defining Post), the SQL table names collide. Add plugin = "..." to opt into a <plugin>_<table> prefix:

#[derive(Debug, Clone, sqlx::FromRow, umbral::orm::Model)]
#[umbral(plugin = "blog")]
pub struct Post {
    pub id: i64,
    pub title: String,
    pub body: String,
}
// Model::TABLE == "blog_post"

The prefix rule:

When to reach for plugin = "...": multi-plugin apps where two or more plugins ship a model with the same struct name, or any time you want the table name to advertise which plugin owns it. The trade-off is longer table names in the DB.

Built-in plugins keep their bare names. umbral-auth, umbral-sessions, umbral-admin, and umbral-tasks do NOT use this attribute. Their table names (auth_user, session, etc.) are stable DB identifiers; switching them would break every existing database. If you are writing a third-party plugin, you should opt into plugin = "..." for every model the plugin ships to avoid future collisions with other plugins.

Model::NAME (the Rust struct name) is not affected by the plugin attribute; it stays "Post" regardless of which table name is used. The migration engine uses Model::NAME as the stable identity key when detecting table renames (see Managed migrations).

Reading rows

Post::objects() returns a Manager<Post> that builds a QuerySet. No pool argument; the manager reaches the ambient pool published by App::build().

let recent = Post::objects()
    .filter(post::PUBLISHED_AT.is_not_null())
    .order_by(post::PUBLISHED_AT.desc())
    .limit(20)
    .fetch()
    .await?;

Each field gets a typed column constant under the snake_case module, named in SCREAMING_SNAKE_CASE: post::ID, post::TITLE, post::BODY, post::PUBLISHED_AT. The comparison methods are checked at compile time.

Terminals: .fetch(), .first(), .get(), .count(), .exists()

.get() is the shape for "this filter should pin one row exactly." MultipleObjectsReturned is a data-integrity signal, not a control-flow case; it fires when filters that should hit a UNIQUE constraint stop being unique.

use umbral::orm::GetError;
 
match Post::objects().filter(post::ID.eq(42)).get().await {
    Ok(p)                                  => render(p),
    Err(GetError::NotFound)                => not_found(),
    Err(GetError::MultipleObjectsReturned) => unreachable!("id is unique"),
    Err(GetError::Sqlx(e))                 => internal_error(e),
}

Manager::get(predicate) is the one-liner sugar:

let user = User::objects().get(user::EMAIL.eq(addr)).await?;

Writing rows

Four write primitives complement the read side. All return a Result<_, umbral::orm::WriteError> whose variants name the offending field on type mismatch / null-on-required-column / unknown-column errors.

create(instance): INSERT one row

let new_post = Post {
    id: 0, // 0 is the autoincrement sentinel
    title: "Hello".into(),
    body: "World".into(),
    published_at: None,
};
 
let inserted = Post::objects().create(new_post).await?;
assert!(inserted.id > 0); // autoincrement PK populated

The integer 0, the nil UUID, and the empty String are all treated as autoincrement-PK sentinels; the column is omitted from the INSERT so the database assigns one. An explicit non-default PK (id = 999) is bound as-is, so callers with UUID PKs or slug PKs can set them themselves.

The returned struct comes from RETURNING *, so timestamps that default to NOW() server-side land populated.

bulk_create([...]): INSERT many in one statement

let rows = (1..=100)
    .map(|i| Post { id: 0, title: format!("post {i}"), body: "...".into(), published_at: None })
    .collect();
 
let count = Post::objects().bulk_create(rows).await?;
assert_eq!(count, 100);

One INSERT with N value tuples, far faster than calling .create() in a loop. Returns the affected-rows count rather than the populated rows; if you need the inserted IDs, follow up with a .filter(...).fetch().

.delete(): DELETE matching rows

let removed = Post::objects()
    .filter(post::PUBLISHED_AT.lt(cutoff))
    .delete()
    .await?;

Applies the accumulated filter predicates as the WHERE clause and returns the deleted-rows count. Without .filter(...), deletes every row. The type system can't tell "I forgot the filter" from "I really meant to truncate."

.update_values(map): UPDATE matching rows

use serde_json::{json, Map};
 
let mut updates = Map::new();
updates.insert("title".into(), json!("Rebranded"));
updates.insert("body".into(), json!("New copy."));
 
let touched = Post::objects()
    .filter(post::ID.eq(42))
    .update_values(updates)
    .await?;

Takes a serde_json::Map<String, Value> of column → new value. Each value is converted to the right sea-query type per the column's SqlType. PATCH semantics: columns absent from the map keep their current values. The PK column is silently skipped if present in the map (rewriting the PK while filtering on the old one is a footgun).

get_or_create(predicate, defaults): INSERT only when missing

Fetch the first row matching predicate; if none exists, insert defaults and return it. The second tuple element says whether a write happened so the caller can branch on first-time-ever vs already-seeded.

let (ct, created) = ContentType::objects()
    .get_or_create(
        content_type::APP_LABEL.eq("blog") & content_type::MODEL.eq("post"),
        ContentType {
            id: 0,
            app_label: "blog".into(),
            model: "post".into(),
        },
    )
    .await?;
if created {
    tracing::info!("first boot, seeded blog.post content type");
}

Two round-trips on the miss path (filter+first, then create), one on the hit path. Pair with a UNIQUE constraint on the predicate columns for at-most-one semantics under concurrent inserters; the constraint is the backstop a concurrent caller hits if both pass the filter check before either creates.

Common shapes:

• Seeding on first boot. A plugin's on_ready walks a list of canonical rows and get_or_creates each. Idempotent regardless of how many times the app restarts.
• Find-or-make. A handler that needs a tag, category, or content-type row to attach to a write: Tag::objects().get_or_create(tag::SLUG.eq(slug), Tag { ... }).

upsert(row): INSERT or UPDATE keyed on the primary key

INSERT-or-UPDATE for cases where you have a fully-formed row and want it to "win" against any existing row with the same PK. Sea-query emits INSERT ... ON CONFLICT(<pk>) DO UPDATE SET col = excluded.col, ...; the SQLite and Postgres syntax happens to match.

let cached = CacheEntry::objects()
    .upsert(CacheEntry {
        key: "homepage:html".into(),
        value: rendered_html.into_bytes(),
        expires_at: Some(Utc::now() + Duration::seconds(60)),
    })
    .await?;

Returns the row as the DB stored it post-upsert. Every non-PK column in the supplied instance overwrites the existing one on a conflict; columns omitted from the serialised instance (rare with #[derive(Model)] since every field is serialised) keep their current value via sea-query's DO NOTHING shape.

Compared to get_or_create, upsert is the right call when you want to OVERWRITE on a conflict rather than preserve the existing row. get_or_create is read-then-create; upsert is "this is the canonical row now".

What's next

• Register the model with the migration engine so makemigrations tracks it.
• Relationships (ForeignKey): declare ForeignKey<T> fields, query by FK, and eager-load with select_related.
• Transactions: wrap multiple writes in umbral::transaction(...) to commit or roll back atomically.
• Querying: F-expressions, Q-objects, exclude, projections, sugar (earliest/latest/distinct/explain), mutate-side terminals, subqueries + set ops, JSON column ops.
• Read the spec at docs/specs/04-orm-model-and-fields.md for the full field-type catalogue and the QuerySet surface.