Ormada
The ergonomic ORM for Rust โ Django's power meets Rust's safety
Ormada brings Django's beloved ORM ergonomics to Rust while maintaining full compile-time type safety. Built on SeaORM, it provides an expressive query API, automatic validation, and production-ready features out of the box.
Why Ormada?
๐ฏ Compile-Time Safety with Typestate Pattern
Catch query errors at compile time, not runtime:
// โ
Valid: filter โ order โ paginate โ execute
objects
.filter
.order_by_asc
.limit
.all.await?;
// โ Compile error: can't filter after ordering
objects
.order_by_asc
.filter // Error: Ordered doesn't implement CanFilter
.all.await?;
๐ Django-Like Ergonomics
Familiar API for developers who love Django's ORM:
// Intuitive Model.objects() pattern
let books = objects
.filter
.exclude
.order_by_desc
.limit
.all
.await?;
// Complex queries with Q objects
let q = any
.add
.add;
let books = objects.filter.all.await?;
๐ Simple Model Definition
Define models with intuitive attributes โ no boilerplate:
๐ Smart Database Routing
Automatic primary/replica routing with read-your-writes consistency:
let primary = connect.await?;
let replica = connect.await?;
let router = new;
// Writes automatically go to primary
objects.create.await?;
// Reads go to replica (or primary after recent write)
objects.all.await?;
๐๏ธ Built-in Soft Delete
First-class soft delete support โ no manual filtering:
// Soft delete (sets deleted_at)
objects.filter.delete.await?;
// Queries exclude deleted by default
objects.all.await?;
// Include deleted, only deleted, or restore
objects.with_deleted.all.await?;
objects.only_deleted.all.await?;
objects.filter.restore.await?;
โก Lifecycle Hooks
Execute logic before/after CRUD operations:
๐ Ergonomic Transactions
Two ways to handle atomic operations:
// Option 1: tx! macro
let = tx!.await?;
// Option 2: #[atomic] decorator
async
๐ฆ Declarative Migrations
Same syntax as your models โ no new DSL to learn:
// migrations/m001_initial.rs
// migrations/m002_add_isbn.rs โ delta migrations
Comparison
| Feature | Ormada | SeaORM | Diesel |
|---|---|---|---|
Django-like Model.objects() API |
โ | โ | โ |
| Compile-time query validation (typestate) | โ | โ | โ |
| FK validation at creation | โ | โ | โ |
get_or_create / update_or_create |
โ | Manual | Manual |
| Built-in soft delete | โ | Manual | Manual |
| Primary/replica routing | โ | Manual | Manual |
| Lifecycle hooks | โ | Manual | Manual |
| Declarative migrations (same syntax) | โ | โ | โ |
| Streaming iterators | โ | โ | Manual |
| Async support | โ | โ | โ |
Features at a Glance
| Category | Features |
|---|---|
| Safety | Typestate query builder, FK validation, compile-time relation checks |
| Ergonomics | Model.objects() API, Q objects, Django-style error types |
| Performance | Bulk ops (10-100x faster), query caching, streaming iterators |
| Database | Primary/replica routing, read-your-writes, multi-DB support |
| CRUD | get_or_create, update_or_create, upsert_many, bulk create |
| Relations | select_related (JOIN), prefetch_related (N+1 prevention) |
| Lifecycle | before_create, after_save, before_delete, and more |
| Soft Delete | with_deleted(), only_deleted(), restore(), force_delete() |
| Aggregations | COUNT, SUM, AVG, MIN, MAX, GROUP BY with projections |
| Debugging | explain(), explain_analyze(), debug_sql() |
| Migrations | Declarative schema, delta migrations, data migrations |
Installation
[]
= "0.1"
Quick Start
use *;
async
Documentation
๐ Full API Documentation โ Complete reference with examples
See also: docs/guide.md for comprehensive usage guide.
Crate Structure
| Crate | Description |
|---|---|
ormada |
Core ORM library |
ormada-derive |
Proc macros (#[ormada_model], #[atomic], etc.) |
ormada-schema |
Schema types for migrations |
ormada-cli |
CLI for migration management |
Performance
Benchmarks on SQLite in-memory (M1 Mac, release build):
| Operation | 1,000 rows | 10,000 rows |
|---|---|---|
all() |
~764 ยตs | ~7.3 ms |
count() |
~33 ยตs | ~33 ยตs |
| Cached queries | -98.9% | -49.2% overhead |
| Bulk insert | 10-100x faster than individual |
Run benchmarks: cargo bench
Database Support
| Database | Status |
|---|---|
| PostgreSQL | โ Full support (recommended) |
| SQLite | โ Full support |
| MySQL | ๐ถ Partial support |
Minimum Supported Rust Version
Rust 1.75 or later.
Contributing
Contributions welcome! Please read our Contributing Guide.
License
MIT License โ see LICENSE for details.