sea-orm

SeaORM is an async, dynamic ORM for building web services in Rust, inspired by the developer experience of popular ORMs in the Ruby, Python, and Node.js ecosystems. It models 1-1, 1-N, and M-N relationships at the entity level, generates typed entity structs from an existing database via sea-orm-cli, and its Smart Entity Loader automatically picks a JOIN for 1-1 relations and a batched data loader for 1-N/M-N relations to eliminate the N+1 query problem even across nested queries.

Beyond querying, SeaORM’s ActiveModel API supports nested persistence for an entire object graph in a single builder call, an Entity First Workflow that diffs entity definitions against the live schema and auto-generates migrations, and a raw_sql! macro for format!-like, injection-safe raw SQL when the query builder isn’t expressive enough. With 250k+ weekly downloads and integrations for Actix, Axum, Rocket, Poem, Salvo, and GraphQL via Seaography, it’s used in production by projects like Zed and Servo.

What You Get

• Entity codegen from an existing database via sea-orm-cli, including a new 2.0 dense entity format with inline relation fields
• A Smart Entity Loader that auto-selects JOIN (1-1) or data-loader batching (1-N/M-N) to avoid N+1 queries on nested .with() chains
• ActiveModel builder API for nested persistence — insert a user, profile, posts, and tags in one dependency-ordered call
• An Entity First Workflow (schema-sync feature) that detects entity changes and creates matching tables, columns, and foreign keys automatically
• A raw_sql! macro for injection-safe raw SQL with nested parameter interpolation and array/tuple expansion
• Backend support for MySQL, Postgres, and SQLite through sqlx, plus a synchronous mode via the companion sea-orm-sync crate

Common Use Cases

• Building REST, GraphQL, or gRPC API backends in Rust frameworks like Actix, Axum, Rocket, and Poem
• Generating typed entity models from an existing production database schema instead of hand-writing structs
• Persisting deeply nested object graphs (parent + related children) in a single transactional call
• Exposing an instant GraphQL API over existing entities via the Seaography integration
• Running lightweight CLI tools against SQLite without pulling in a full async runtime, via sea-orm-sync

Under The Hood

Architecture SeaORM separates concerns cleanly across src/database (connection pooling, executor, transaction management, mock and proxy backends), src/driver (backend-specific adapters for sqlx-mysql/postgres/sqlite plus a pure rusqlite path), src/query (typed select/insert/update/delete/loader builders that compile down to sea-query ASTs), and src/entity (the Model/ActiveModel/Entity trait system, plus the newer dense entity macro and registry for schema-sync). The sea-orm-macros proc-macro crate generates entity boilerplate (DeriveEntityModel, DerivePartialModel) at compile time, while sea-query supplies the actual SQL AST and backend abstraction that SeaORM executes over sqlx or rusqlite. This layering means swapping database backends only touches the driver layer while query-builder and entity code stay backend-agnostic, and the workspace is split into separate crates (sea-orm-macros, sea-orm-codegen, sea-orm-arrow) so compile-time codegen and runtime library code have distinct release cycles.

Tech Stack Built on sqlx 0.9 (async DB driver, optional per backend) and sea-query 1.0 (SQL builder/AST, a hard dependency), with Tokio or async-std selectable through runtime-* feature flags. Optional value-type integrations — chrono, time, uuid, rust_decimal, bigdecimal, ipnetwork — sit behind with-* feature flags, serde/serde_json back JSON columns, thiserror implements the DbErr error enum, and sea-schema powers live schema discovery and sync. sea-orm-macros generates derive implementations at compile time, sea-orm-codegen backs the sea-orm-cli entity generator, and sea-orm-arrow adds Arrow/Parquet export. The crate targets Rust edition 2024 with an MSRV of 1.94.

Code Quality The tests/ directory holds 80+ integration test files (CRUD, cursor pagination, active enums, partial models, Arrow schema, RBAC, entity-loader N+1 avoidance, and more) exercised against real MySQL, Postgres, and SQLite instances in CI (.github/workflows/rust.yml). lib.rs enforces #![warn(missing_docs)] and #![deny(missing_debug_implementations, clippy::unwrap_used, clippy::print_stderr, clippy::print_stdout)], a strict lint gate uncommon even in mature Rust crates. Errors are consolidated into a single #[non_exhaustive] DbErr enum built with thiserror, explicitly wrapping backend-specific SQLx errors rather than discarding context.

API Design The 2.0 entity format (#[sea_orm::model] plus DeriveEntityModel) puts HasOne/HasMany/BelongsTo relation fields directly on the Model struct, so a single .with() chain triggers smart eager-loading that automatically picks a JOIN for 1-1 relations and a batched data loader for 1-N/M-N relations. ActiveModel::builder() extends this to writes, supporting nested persistence of an entire object graph with automatically resolved insert/delete ordering. The raw_sql! macro gives format!-like ergonomics for raw SQL with nested field interpolation and array/tuple expansion, and the Entity First Workflow diffs entity definitions against the live schema to auto-create tables, columns, and foreign keys — a notably differentiated developer experience compared to typical Rust ORMs like Diesel.