Web Framework Integrations
Relevant source files
The following files were used as context for generating this wiki page:
SeaORM is a batteries-included Object-Relational Mapper (ORM) designed to accelerate the development of REST, GraphQL, and gRPC APIs in Rust. It provides a set of tools and architectural patterns that allow developers to integrate database operations seamlessly with various web frameworks, supporting both asynchronous and synchronous runtimes.
The integration strategy focuses on providing "service-oriented" structures where SeaORM entities, models, and paginators can be utilized within framework-specific handlers or controllers. This enables high-level operations such as filtering, sorting, and pagination of data through web interfaces.
Sources: src/lib.rs:25-30, src/docs.rs:90-95
Supported Frameworks and Examples
SeaORM provides extensive integration examples for the most prominent frameworks in the Rust ecosystem. These examples demonstrate how to manage database connections and execute queries within the lifecycle of a web request.
| Framework | Purpose / Integration Type | Example Reference |
|---|---|---|
| Actix Web | Asynchronous Web Framework | examples/actix_example |
| Axum | Ergonimic Web Framework (Tokio stack) | examples/axum_example |
| Rocket | High-level Web Framework | examples/rocket_example |
| Poem | Modern Web Framework | examples/poem_example |
| Salvo | Simple and powerful Web Framework | examples/salvo_example |
| Tonic | gRPC Framework | examples/tonic_example |
| Loco.rs | Full-stack productivity framework | examples/loco_example |
Sources: src/lib.rs:52-65, README.md:46-59
Integration Architecture
The integration typically follows a pattern where the web framework manages the DbConn (Database Connection) as a shared state, which is then accessed by request handlers to perform operations on SeaORM entities.
Request Flow with SeaORM
The following diagram illustrates how a standard web request interacts with SeaORM to retrieve paginated data.
The SeaORM Paginator handles the complexity of calculating total pages and fetching specific segments of data.
Sources: src/docs.rs:90-130, sea-orm-sync/src/docs.rs:90-130
Service-Oriented APIs
SeaORM is designed to build services that simplify API development. Key features used in web integrations include:
- Paginator: Used to easily list data in web views with page-based navigation.
- Filters and Sorting: Handlers can map URL query parameters directly to
filter()andorder_by_*()methods on SeaORM entities. - Eager Loading: To prevent the N+1 problem in REST/GraphQL responses, the Entity Loader uses joins (1-1) or data loaders (1-N) to fetch nested data.
Sources: src/docs.rs:100-110, src/lib.rs:135-150, README.md:129-140
Entity Loading Logic
Sources: src/lib.rs:150-160, src/docs.rs:95-105
Synchronous vs. Asynchronous Integration
SeaORM supports two primary integration modes depending on the needs of the application:
- Async (SQLx-based): This is the default mode for high-performance web servers like Actix and Axum. It relies on
sqlxand supports parallel query execution usingfutures_util. - Sync (sea-orm-sync): Targeted at lightweight CLI tools or specific environments where an async runtime is not desired. It provides the same API but executes operations synchronously, often used with SQLite.
Sources: src/docs.rs:5-15, sea-orm-sync/src/lib.rs:245-250, README.md:235-240
GraphQL Integration: Seaography
Beyond traditional REST frameworks, SeaORM integrates with Seaography to provide instant GraphQL APIs. Seaography generates GraphQL resolvers directly from SeaORM entities, supporting complex relational queries, pagination, and mutations without manual boilerplate.
Sources: src/lib.rs:360-370, README.md:355-365
Summary
Web framework integration in SeaORM is characterized by its "batteries-included" approach, providing specific examples for Actix, Axum, Rocket, and more. By leveraging features like the Smart Entity Loader and built-in Paginators, developers can build robust, production-ready APIs while maintaining clean, service-oriented code structures.
Sources: src/lib.rs:25-30, COMMUNITY.md:140-150