This version is in beta. Some features may change before release.

Orm

Browse the documentation in this section.

Declaring models

One struct, one

Column types

Every Rust field type the Model derive recognises, what it maps to on Postgres and SQLite, and how to handle column constraints (length, default, unique, index).

Relationships

Declare foreign keys with ForeignKey<T>, what DDL gets emitted, and how to load the referenced row at runtime.

Querying

The full QuerySet surface: F-expressions, Q-objects, exclude, projections, sugar, subqueries, set ops, JSON ops, and the write-side terminals (update_or_create, bulk_update, raw).

Aggregates and annotate

Count, Sum, Avg, Max, Min on a QuerySet, with single-row aggregates and GROUP BY annotate.

Transactions

Atomic multi-statement operations - commit on Ok, roll back on Err.

Signals

Lifecycle hooks fired by the ORM (per-row, bulk, m2m) plus the actor task-local that flows through every payload.

Soft delete

Tag a model with soft_delete and deletes become reversible. Rows hide instead of dying.

Forms learn relations

#[derive(Form)] on a model with ForeignKey, OneToOne, M2M, and choices fields. FK/O2O become a ModelChoice, M2M a ModelMultiChoice, choices a Select, and reverse relations are auto-skipped.

Deep joins

Span relations in one round-trip with INNER/LEFT/RIGHT control, nested paths, auto-inference, and an M2M-hop chain.

File and image fields

FileField and ImageField store a Storage key in a TEXT column and resolve it to a public URL through the ambient storage backend.

Masked fields (encrypt at rest)

Encrypt sensitive columns at rest with public-key cryptography. GDPR-style field encryption with Masked<T>.

Cross-model search

Search several models at once and get one relevance-ranked list of hits.

Database routing (multiple databases)

Route different models to different databases with named pools, per-model and per-plugin routing, per-database migrations.

Database router (swappable routing)

Take over how umbral picks the database and read/write target per request - read replicas and custom per-request routing.

Connection pooling

Configure the database connection pool - max/min connections, acquire/idle timeouts, max lifetime, and pre-acquire health checks - plus graceful shutdown.