Introduction to SeaORM
Relevant source files
The following files were used as context for generating this wiki page:
SeaORM is a powerful and batteries-included Object-Relational Mapper (ORM) designed for building web services in Rust. It offers a developer experience inspired by popular ORMs in Python, Ruby, and Node.js ecosystems, providing a high-level conceptual way to model complex relationships such as 1-1, 1-N, and M-N.
The library supports both asynchronous and synchronous workflows, making it versatile for high-performance web servers as well as lightweight CLI tools. SeaORM 2.0 introduces several advancements, including a "dense" entity format, a smart entity loader to solve the N+1 problem, and an "entity-first" workflow for schema management.
Sources: README.md:1-25, src/lib.rs:24-40, sea-orm-sync/src/lib.rs:43-58
Core Features and Architecture
SeaORM is built on a modular architecture that separates entity definitions, query execution, and database drivers. It leverages sea-query for SQL building and supports multiple database backends including MySQL, PostgreSQL, and SQLite.
| Feature | Description |
|---|---|
| Advanced Relations | Model 1-1, 1-N, M-N, and self-referential relationships. |
| Async & Sync | Supports async runtimes (Tokio, Actix, async-std) and a dedicated sync crate. |
| Smart Loader | Automatically chooses JOINs or Data Loaders to optimize nested queries. |
| Entity-First | Define entities in Rust and sync them to the database schema automatically. |
| Type Safety | Utilizes strongly-typed columns and macros to prevent runtime errors. |
| Sources: README.md:27-100, src/lib.rs:42-120, sea-orm-sync/src/lib.rs:60-130 |
System Workflow
The following diagram illustrates how SeaORM processes data from Rust entities to the database.
This diagram shows the bidirectional flow between Rust data structures and the underlying database engine.
Sources: src/lib.rs:596-620, CLAUDE.md:160-185
Entity and Model Definitions
In SeaORM 2.0, entities are defined using the #[sea_orm::model] macro. This unified format allows developers to define the table name, columns, primary keys, and relations directly on a single struct.
Relationship Mapping
Relationships are defined within the model struct using attributes like has_one, has_many, and belongs_to. This replaces the older pattern of separate trait implementations.
The ER diagram represents a standard "dense" entity relationship structure supported by SeaORM's internal loader.
Sources: README.md:42-81, CLAUDE.md:16-52
Entity Registry
The SchemaRegistry is a core component of the "Entity-First" workflow. It allows SeaORM to resolve foreign key dependencies and create tables in the correct topological order based on Rust definitions.
Sources: README.md:130-142, CLAUDE.md:116-123
Querying and Persistence
SeaORM provides two primary styles for interacting with data: the Repository style and the Active Record style.
ActiveModel and Persistence
ActiveModel is the mutable version of a Model. It tracks changed fields to avoid unnecessary updates and race conditions. Persistence of entire object graphs (nested objects) can be performed in a single operation using the builder API.
The sequence shows the nested persistence flow where SeaORM automatically resolves dependency order.
Sources: src/lib.rs:323-345, CLAUDE.md:84-103
Smart Entity Loader
The Entity Loader is designed to eliminate the N+1 query problem. For 1-1 relations, it uses SQL JOIN. For 1-N relations, it uses a data loader to fetch related records in batches.
Sources: README.md:83-100, src/lib.rs:125-145
Database Interaction Methods
SeaORM offers multiple ways to execute queries depending on complexity:
- Fluent API: For standard CRUD operations using
Entity::find(),insert(),update(), anddelete(). - Partial Models: Used to select only a subset of columns, preventing over-fetching.
- Raw SQL: The
raw_sql!macro allows writing custom SQL with parameter interpolation and protection against SQL injection.
Sources: src/lib.rs:175-220, sea-orm-sync/src/lib.rs:250-300, CLAUDE.md:134-148
Database Drivers and Runtimes
SeaORM supports various asynchronous runtimes through feature flags.
| Runtime / Driver | Feature Flag |
|---|---|
| Tokio | runtime-tokio-native-tls |
| Actix | runtime-actix-native-tls |
| Async-Std | runtime-async-std-rustls |
| PostgreSQL | sqlx-postgres |
| MySQL | sqlx-mysql |
| SQLite | sqlx-sqlite |
| Sources: CONTRIBUTING.md:87-105, sea-orm-cli/Cargo.toml:75-120 |
Integration and Ecosystem
SeaORM integrates with various frameworks through specialized crates and tools:
- Seaography: Generates a GraphQL server from SeaORM entities.
- SeaORM Pro: A professional admin panel solution built with React and GraphQL.
- SeaORM Sync: A version of the ORM that does not require an async runtime, ideal for SQLite-based CLI applications.
Sources: README.md:370-420, sea-orm-sync/src/lib.rs:210-230, examples/seaography_example/README.md:1-20
Summary
SeaORM serves as a comprehensive SQL toolkit for the Rust ecosystem. By combining a familiar developer experience with Rust's type safety and performance, it allows for efficient development of data-intensive applications. Its ability to handle complex relations, optimize queries automatically, and support both sync/async workflows makes it a foundational component for many open-source projects and enterprises.
Sources: README.md:465-490, COMMUNITY.md:10-40