GraphQL & Seaography
Relevant source files
The following files were used as context for generating this wiki page:
Seaography is a GraphQL framework specifically built for SeaORM that enables the rapid construction of GraphQL resolvers. It allows developers to launch a fully-featured GraphQL server directly from SeaORM entities, providing built-in support for advanced features such as complex filters, pagination, relational queries, and mutations with minimal manual coding.
Within the SeaORM ecosystem, Seaography acts as a bridge between the relational database layer and GraphQL clients. It leverages SeaORM’s expressive entity format and smart loaders to solve common GraphQL challenges, such as the N+1 problem, by intelligently using joins or data loaders for relational data fetching.
Sources: README.md:425-432, sea-orm-sync/src/lib.rs:718-725
Framework Architecture and Workflow
The Seaography workflow typically starts with an existing database schema, from which SeaORM entities are generated, followed by the generation of the GraphQL project structure using the Seaography CLI.
Integration Flow
The following diagram illustrates the lifecycle of setting up a GraphQL API using SeaORM and Seaography.
This diagram shows the transition from a raw database to a functional GraphQL server through the SeaORM and Seaography CLI tools.
Sources: examples/seaography_example/README.md:79-84
Key Components
| Component | Description |
|---|---|
sea-orm-cli | Used to generate dense entity formats from a database schema with the --seaography flag. |
seaography-cli | Generates the GraphQL project structure, supporting frameworks like Axum. |
| GraphQL Resolvers | Automatically generated logic that handles incoming queries and maps them to SeaORM operations. |
| Smart Entity Loader | SeaORM backend logic used by Seaography to handle 1-1 (via joins) and 1-N (via data loaders) relations. |
Sources: examples/seaography_example/README.md:76-84, README.md:92-95
GraphQL Query Features
Seaography supports sophisticated querying capabilities including relational traversal and conditional filtering.
Relational Traversal
Seaography allows clients to traverse relationships defined in SeaORM entities (1-1, 1-N, M-N) within a single GraphQL request. For example, a query can fetch a bakery, its associated cakes, and the bakers for each cake in a nested structure.
{
bakery(pagination: { page: { limit: 10, page: 0 } }, orderBy: { name: ASC }) {
nodes {
name
cake {
nodes {
name
baker {
nodes { name }
}
}
}
}
}
}
Sources: examples/seaography_example/README.md:52-66
Filtering and "Having" Clauses
Seaography provides two primary ways to restrict result sets:
- Filters: Direct conditions on the entity's fields (e.g., name contains "Chocolate").
- Having: Conditions applied to related entities (e.g., cakes that have a baker named "Alice").
This diagram represents the logical branching of query constraints in a Seaography resolver.
Sources: examples/seaography_example/README.md:28-50
SeaORM Pro and Admin Panels
Seaography serves as the built-in GraphQL resolver for SeaORM Pro, a professional admin panel solution. This integration allows for a "frontend-less" development experience where the admin UI is customized via TOML configuration while Seaography handles the data communication.
Admin Panel Features
- Full CRUD: Create, Read, Update, and Delete operations handled via GraphQL mutations and queries.
- RBAC: Role-Based Access Control integrated into the GraphQL layer (new in SeaORM 2.0).
- Loco Integration: Seaography can be added to Loco (a Rust web framework) to provide instant GraphQL support for starter applications.
Sources: README.md:434-450, examples/react_admin/README.md:3-8, examples/loco_seaography/README.md:3-7
Implementation Details
When generating entities for Seaography, the sea-orm-cli utilizes the dense entity format. The relations are defined directly on the Model struct using specific attributes that Seaography interprets to build the GraphQL schema.
#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
#[sea_orm(table_name = "user")]
pub struct Model {
#[sea_orm(primary_key)]
pub id: i32,
#[sea_orm(has_one)]
pub profile: HasOne<super::profile::Entity>,
#[sea_orm(has_many)]
pub posts: HasMany<super::post::Entity>,
}
Sources: CLAUDE.md:15-32, README.md:68-88
Seaography is a critical component for developers seeking to build production-ready GraphQL APIs in Rust. By automating resolver generation and leveraging SeaORM's advanced relational mapping, it significantly reduces the boilerplate required to expose a relational database as a GraphQL service.