In our last post, we introduced a new Entity format - designed to be more concise, more readable, and easy to write by hand.

With this format, you can embrace an Entity‑first workflow: stay focused on your domain model without getting bogged down in database tables or migration scripts.

And the best part? Pair it with Seaography and you'll have a working GraphQL API instantly - meaning you can skip writing most of the backend logic code until much later in your project's lifecycle.

This combination keeps you in the flow, and lets you focus on what really matters: building apps.

What's Entity first?​

SeaORM used to adopt a schema‑first approach: meaning you design database tables and write migration scripts first, then generate entities from that schema.

Entity‑first flips the flow: you hand-write the entity files, and let SeaORM generates the tables and foreign keys for you.

All you have to do is to add the following to your main.rs right after creating the database connection:

let db = &Database::connect(db_url).await?;
// synchronizes database schema with entity definitions
db.get_schema_registry("my_crate::entity::*").sync(db).await?;

This requires two feature flags schema-sync and entity-registry, and we're going to explain what they do.

Unfolding​

Entity Registry​

The above function get_schema_registry unfolds into the following:

db.get_schema_builder()
    .register(comment::Entity)
    .register(post::Entity)
    .register(profile::Entity)
    .register(user::Entity)
    .sync(db)
    .await?;

You might be wondering: how can SeaORM recognize my entities when, at compile time, the SeaORM crate itself has no knowledge of them?

Rest assured, there's no source‑file scanning or other hacks involved - this is powered by the brilliant inventory crate. The inventory crate works by registering items (called plugins) into linker-collected sections.

At compile-time, each Entity module registers itself to the global inventory along with their module paths and some metadata. On runtime, SeaORM then filters the Entities you requested and construct a SchemaBuilder.

The EntityRegistry is completely optional and just adds extra convenience, it's perfectly fine for you to register Entities manually like above.

Resolving Entity Relations​

If you remember from the previous post, you'll notice that comment has a foreign key referencing post. Since SQLite doesn't allow adding foreign keys after the fact, the post table must be created before the comment table.

This is where SeaORM shines: it automatically builds a dependency graph from your entities and determines the correct topological order to create the tables, so you don't have to keep track of them in your head.

Schema Sync in Action​

The second feature, schema-sync, compares the in‑memory entity definitions with the live database schema, detects missing tables, columns, and keys, and creates them idempotently - no matter how many times you run sync, the schema converges to the same state.

Let's walk through the different scenarios:

Adding Table​

Let's say you added a new Entity under mod.rs

//! `SeaORM` Entity, @generated by sea-orm-codegen 2.0.0-rc.14

pub mod prelude;

pub mod post;
pub mod upvote; // ⬅ new entity module
..

The next time you cargo run, you'll see the following:

CREATE TABLE "upvote" ( "id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, .. )

This will create the table along with any foreign keys.

Adding Columns​

use sea_orm::entity::prelude::*;

#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
#[sea_orm(table_name = "profile")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    pub picture: String,
    pub date_of_birth: Option<DateTimeUtc>, // ⬅ new column
    ..
}

impl ActiveModelBehavior for ActiveModel {}

The next time you cargo run, you'll see the following:

ALTER TABLE "profile" ADD COLUMN "date_of_birth" timestamp with time zone

How about adding a non-nullable column? You can set a default_value or default_expr:

#[sea_orm(default_value = 0)]
pub post_count: i32,

// this doesn't work in SQLite
#[sea_orm(default_expr = "Expr::current_timestamp()")]
pub updated_at: DateTimeUtc,

Rename Column​

If you only want to rename the field name in code, you can simply remap the column name:

pub struct Model {
    ..
    #[sea_orm(column_name = "date_of_birth")]
    pub dob: Option<DateTimeUtc>, // ⬅ renamed for brevity
}

This doesn't involve any schema change.

If you want to actually rename the column, then you have to add a special attribute. Note that you can't simply change the field name, as this will be recognized as adding a new column.

pub struct Model {
    ..
    #[sea_orm(renamed_from = "date_of_birth")] // ⬅ special annotation
    pub dob: Option<DateTimeUtc>,
}

The next time you cargo run, you'll see the following:

ALTER TABLE "profile" RENAME COLUMN "date_of_birth" TO "dob"

Nice, isn't it?

Add Foreign Key​

Let's create a new table with a foreign key:

use sea_orm::entity::prelude::*;

#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
#[sea_orm(table_name = "upvote")]
pub struct Model {
    #[sea_orm(primary_key, auto_increment = false)]
    pub post_id: i32,
    #[sea_orm(belongs_to, from = "post_id", to = "id")]
    pub post: HasOne<super::post::Entity>,
    ..
}

impl ActiveModelBehavior for ActiveModel {}

The next time you cargo run, you'll see the following:

CREATE TABLE "upvote" (
    "post_id" integer NOT NULL PRIMARY KEY,
    ..
    FOREIGN KEY ("post_id") REFERENCES "post" ("id")
)

If however, the post relation is added after the table has been created, then the foreign key couldn't be created for SQLite. Relational queries would still work, but functions completely client-side.

Add Unique Key​

Now, let's say we've forgotten to add a unique constraint on user name:

use sea_orm::entity::prelude::*;

#[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(unique)] // ⬅ add unique key
    pub name: String,
    #[sea_orm(unique)]
    pub email: String,
    ..
}

The next time you cargo run, you'll see the following:

CREATE UNIQUE INDEX "idx-user-name" ON "user" ("name")

As mentioned in the previous blog post, you'll also get a shorthand method generated on the Entity:

user::Entity::find_by_name("Bob")..

Remove Unique Key​

Well, you've changed your mind and want to remove the unique constraint on user name:

pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    // no annotation
    pub name: String,
    #[sea_orm(unique)]
    pub email: String,
    ..
}

The next time you cargo run, you'll see the following:

DROP INDEX "idx-user-name"

Footnotes​

Note that in general schema sync would not attempt to do any destructive actions, so meaning no DROP on tables, columns and foreign keys. Dropping index is an exception here.

Every time the application starts, a full schema discovery is performed. This may not be desirable in production, so sync is gated behind a feature flag schema-sync that can be turned off based on build profile.

🧭 Instant GraphQL API​

With Seaography, the Entities you wrote can instantly be exposed as a GraphQL schema, with full CRUD, filtering and pagination. No extra macros, no Entity re-generation is needed!

With SeaORM and Seaography, you can prototype quickly and stay in the flow. And because Seaography is highly customizable, you can gradually shift resolver logic into your own implementation as the application evolves, and layer access control on top before the project goes to production.

The Entity:

#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
#[sea_orm(table_name = "user")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    pub name: String,
    #[sea_orm(unique)]
    pub email: String,
    #[sea_orm(has_one)]
    pub profile: HasOne<super::profile::Entity>,
    #[sea_orm(has_many)]
    pub posts: HasMany<super::post::Entity>,
}

Instantly turned into a GraphQL type:

type User {
  id: Int!
  name: String!
  email: String!
  profile: Profile
  post(
    filters: PostFilterInput
    orderBy: PostOrderInput
    pagination: PaginationInput
  ): PostConnection!
}

🖥️ SeaORM Pro: Admin Panel​

SeaORM Pro is an admin panel solution allowing you to quickly and easily launch an admin panel for your application - frontend development skills not required, but certainly nice to have!

SeaORM Pro has been updated to support the latest features in SeaORM 2.0.

Features:

• Full CRUD
• Built on React + GraphQL
• Built-in GraphQL resolver
• Customize the UI with TOML config
• Role Based Access Control (new in 2.0)

🦀 Rustacean Sticker Pack​

The Rustacean Sticker Pack is the perfect way to express your passion for Rust. Our stickers are made with a premium water-resistant vinyl with a unique matte finish.

Sticker Pack Contents:

• Logo of SeaQL projects: SeaQL, SeaORM, SeaQuery, Seaography
• Mascots: Ferris the Crab x 3, Terres the Hermit Crab
• The Rustacean wordmark

Support SeaQL and get a Sticker Pack!

SeaORM’s current entity format is explicit, but it can feel verbose, making it difficult to write by hand. In SeaORM 2.0, we’re introducing a more information‑dense entity format, along with new features that make relational queries easier and more powerful.

Gist​

Suppose now we're making a blogging platform. We're designing a simple schema starting from users.

user 1-1 profile
user 1-N post
post 1-N comment

Defining the user Entity as follows:

mod user {
    use sea_orm::entity::prelude::*;

    #[sea_orm::model]
    #[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
    #[sea_orm(table_name = "user")]
    pub struct Model {
        #[sea_orm(primary_key)]
        pub id: i32,
        pub name: String,
        #[sea_orm(unique)]
        pub email: String,
        #[sea_orm(has_one)]
        pub profile: HasOne<super::profile::Entity>,
        #[sea_orm(has_many)]
        pub posts: HasMany<super::post::Entity>,
    }

    impl ActiveModelBehavior for ActiveModel {}
}

You will be able to query a user with their profile along with all their blog posts in one operation:

// join paths:
// user -> profile
// user -> post -> comment
let user: Option<user::ModelEx> = user::Entity::load()
    .filter_by_id(12)
    .with(profile::Entity)
    .with((post::Entity, comment::Entity))
    .one(db)
    .await?;

// has the following shape:
assert_eq!(user.unwrap(), user::ModelEx {
    id: 12,
    name: "Bob".into(),
    email: "bob@sea-ql.org".into(),
    profile: Some(profile::ModelEx {
        ..
    }),
    posts: vec![
        post::ModelEx {
            title: "Nice day for a walk",
            comments: vec![comment::ModelEx { .. }, .. ],
        },
        post::ModelEx { .. },
    ],
});

Full example can be found here.

The Schema​

The definition of the user Entity is already shown above, let's look at profile and post:

mod profile {
    use sea_orm::entity::prelude::*;

    #[sea_orm::model]
    #[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
    #[sea_orm(table_name = "profile")]
    pub struct Model {
        #[sea_orm(primary_key)]
        pub id: i32,
        pub picture: String,
        #[sea_orm(unique)]
        pub user_id: i32,
        #[sea_orm(belongs_to, from = "user_id", to = "id")]
        pub user: HasOne<super::user::Entity>,
    }

    impl ActiveModelBehavior for ActiveModel {}
}

profile has a foreign key user_id -> user.id relating back to the user table. By applying a unique constraint, we're effectively making the relation 1-1.

mod post {
    use sea_orm::entity::prelude::*;

    #[sea_orm::model]
    #[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
    #[sea_orm(table_name = "post")]
    pub struct Model {
        #[sea_orm(primary_key)]
        pub id: i32,
        pub user_id: i32,
        pub title: String,
        pub body: String,
        #[sea_orm(belongs_to, from = "user_id", to = "id")]
        pub author: HasOne<super::user::Entity>,
        #[sea_orm(has_many)]
        pub comments: HasMany<super::comment::Entity>,
    }

    impl ActiveModelBehavior for ActiveModel {}
}

Similarly, post has a foreign key to the user table, but without the unique constraint. The comment entity is very similar.

mod comment {
    use sea_orm::entity::prelude::*;

    #[sea_orm::model]
    #[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
    #[sea_orm(table_name = "comment")]
    pub struct Model {
        #[sea_orm(primary_key)]
        pub id: i32,
        pub comment: String,
        pub post_id: i32,
        #[sea_orm(belongs_to, from = "post_id", to = "id")]
        pub post: HasOne<super::post::Entity>,
    }

    impl ActiveModelBehavior for ActiveModel {}
}

Under the hood​

It looks clean right? But what magic is going on under the hood? Let's break it down step by step, at the end it actally expands into the current entity format. Such that this new entity format is perfectly backwards-compatible.

A bit of history​

In the early days of SeaORM, language servers didn't have very strong macro expansion capabilities. As such, types generated by derive macros can't be seen and picked up by IDEs for auto-completion. That's why in that era crates would prefer to be macro-light, it's also the reason SeaORM (still) has an expanded entity format. The current compact entity format expands into the expanded entity format.

Generating the Relation enum and Related impl​

An existing SeaORM entity has three sections, Model, Relation and ActiveModel.

use sea_orm::entity::prelude::*;

pub struct Model { .. }

pub enum Relation { .. }

impl Related<> for Entity {}

impl ActiveModelBehavior for ActiveModel {}

We've hid the Relation / Related section into the Model itself.

For the user entity, a Relation enum is generated:

pub enum Relation {
    #[sea_orm(has_one = "super::profile::Entity")]
    Profile,
    #[sea_orm(has_many = "super::post::Entity")]
    Post,
}

In addition, some Related impls are also generated:

impl Related<super::profile::Entity> for Entity {
    fn to() -> RelationDef {
        Relation::Profile.def()
    }
}

impl Related<super::post::Entity> for Entity {
    fn to() -> RelationDef {
        Relation::Post.def()
    }
}

For the profile entity, it gets slightly more elaborate:

pub enum Relation {
    #[sea_orm(
        belongs_to = "super::user::Entity",
        from = "Column::UserId",
        to = "super::user::Column::Id"
    )]
    User,
}

impl Related<super::user::Entity> for Entity {
    fn to() -> RelationDef {
        Relation::User.def()
    }
}

Generating the Model​

Note that the Model is now not 'plain-old', as it has some nested fields:

pub struct Model {
    pub id: i32,
    pub name: String,
    pub email: String,
    pub profile: HasOne<super::profile::Entity>, // <-
    pub posts: HasMany<super::post::Entity>,     // <-
}

We have to drop these fields to make the struct simple, such that we can still do the following:

let user = user::Model { id: 1, name: "Bob".into(), email: "bob@sea-ql.org" };

That's why as you may have noticed, we need an attribute macro:

#[sea_orm::model]

We call the compound Model with nested fields ModelEx. May be it can have a better name, but you should rarely need to name this type explicitly.

More relation types​

What makes SeaORM stand-apart is that we support many different kinds of relations in real-world complex schemas. Many users may never encounter them, but they're there when you need them.

Many to many relation with junction table​

SeaORM is unique in its ability to model many‑to‑many relations as first‑class constructs. Most APIs treat both 1-N and M-N synonymously, and you never need to manually specify the junction table when writing queries.

Let's say post M-N tag, all you need is to specify the junction with the via attribute:

mod post {
    use sea_orm::entity::prelude::*;

    #[sea_orm::model]
    #[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
    #[sea_orm(table_name = "post")]
    pub struct Model {
        #[sea_orm(primary_key)]
        pub id: i32,
        #[sea_orm(has_many, via = "post_tag")]
        pub tags: HasMany<super::tag::Entity>,
    }

    impl ActiveModelBehavior for ActiveModel {}
}

This is the junction table:

mod post_tag {
    use sea_orm::entity::prelude::*;

    #[sea_orm::model]
    #[derive(Clone, Debug, PartialEq, DeriveEntityModel, Eq)]
    #[sea_orm(table_name = "post_tag")]
    pub struct Model {
        #[sea_orm(primary_key, auto_increment = false)]
        pub post_id: i32,
        #[sea_orm(primary_key, auto_increment = false)]
        pub tag_id: i32,
        #[sea_orm(belongs_to, from = "post_id", to = "id")]
        pub post: Option<super::post::Entity>,
        #[sea_orm(belongs_to, from = "tag_id", to = "id")]
        pub tag: Option<super::tag::Entity>,
    }

    impl ActiveModelBehavior for ActiveModel {}
}

To query posts with tags, you call the exact same method, without even mentioning the junction.

let posts = post::Entity::load().with(tag::Entity).all(db).await?;

assert_eq!(posts, vec![post::ModelEx {
    tags: vec![ tag::ModelEx { .. }, .. ]
}]);

// or you can use the model loader API:

let posts: Vec<post::Model> = post::Entity::find().all(db).await?;
let tags: Vec<tag::Model> = posts.load_many(tag::Entity, db).await?;

Self-referencing relations​

#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Eq)]
#[sea_orm(table_name = "staff")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    pub name: String,
    pub manager_id: i32,
    #[sea_orm(
        self_ref,
        relation_enum = "Manager",
        from = "manager_id",
        to = "id"
    )]
    pub manager: HasOne<Entity>,
}

The generated enum will have a variant like:

pub enum Relation {
    #[sea_orm(
        belongs_to = "Entity",
        from = "Column::ManagerId",
        to = "Column::Id",
    )]
    Manager, // <- relation_enum
}

This aspect is not so different from 1.0. A Related impl will not be generated, but the relation can still be used in loader or join queries.

Composite foreign key​

You don't use it very often, but SeaORM actually supports it since 0.1. Some lines are omitted for brevity.

mod composite_a {
    #[sea_orm::model]
    #[sea_orm(table_name = "composite_a")]
    pub struct Model {
        #[sea_orm(primary_key)]
        pub id: i32,
        #[sea_orm(unique_key = "pair")] // <- name this unique key
        pub left_id: i32,
        #[sea_orm(unique_key = "pair")]
        pub right_id: i32,
        #[sea_orm(has_one)]
        pub b: Option<super::composite_b::Entity>,
    }
}

mod composite_b {
    #[sea_orm::model]
    #[sea_orm(table_name = "composite_b")]
    pub struct Model {
        #[sea_orm(primary_key)]
        pub id: i32,
        pub left_id: i32,
        pub right_id: i32,
        #[sea_orm(
            belongs_to,
            from = "(left_id, right_id)",
            to = "(left_id, right_id)"
        )]
        pub a: Option<super::composite_a::Entity>,
    }
}

Designing an ORM that can support all these scenario is hard with exploding complexities, but this is exactly what makes SeaORM powerful and sets it apart. Even if you don’t need these features today, choosing SeaORM helps ensure your application is future-proof.

New find/filter by unique key methods​

To improve ergonomics, SeaORM 2.0 now automatically generates type-safe shorthand methods for unique keys:

user::Entity::find_by_email("bob@sea-ql.org").one(db).await?

user::Entity::load().filter_by_email("bob@sea-ql.org").one(db).await?

It even works on composite unique keys!

// the name `pair` is user-defined above
composite_a::Entity::find_by_pair((1, 2)).one(db).await?

composite_a::Entity::load().filter_by_pair((2, 3)).one(db).await?

(Smart) Entity Loader​

We've spent a lot of engineering effort in designing the new Entity Loader. You can see it as magic, because it eliminates the N+1 problem even when doing nested queries while preventing over-fetching at the same time.

In the nested query we shown you in the beginning, 3 queries are executed:

SELECT FROM user JOIN profile WHERE id = $
SELECT FROM post JOIN user WHERE user_id IN (..)
SELECT FROM comment WHERE post_id IN (..)

For 1-1 relations, it does a join and select up to three tables together in a single query.

For 1-N or M-N relations, it uses the data loader. Note that, it's a single query even for M-N relation, as the junction table will be joined.

For nested queries, it uses the data loader. It consolidates the id of all the posts in the 2nd query and issue one query for the comments.

Backwards compatibility​

The new Entity format is perfectly backwards compatible as it gets expanded into the current compact format. However, the Entity Loader generates a bit of extra code under the hood, and it's not available for compact entities. We've introduced a transitional macro, in case you want to take advantage of the Entity Loader without migrating to the new format.

#[sea_orm::compact_model] // <- add this
#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
#[sea_orm(table_name = "post")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    pub user_id: i32,
    pub body: String,
    // #[sea_orm(belongs_to, from = "user_id", to = "id")] // <- not needed
    pub author: HasOne<super::user::Entity>, // <- add these compound fields
}

// the rest of the Entity file is exactly the same as before

#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
pub enum Relation { .. }

Now you can do:

post::Entity::load().with(super::user::Entity)..

The current compact entity format has more flexibility, as you can:

1. add new Relation enum variants
2. add on_condition on relations

Updated codegen​

sea-orm-cli has been updated to generate this new entity format, including with Seaography support. You can run the same entity generate command, but with an additional --entity-format dense flag. We may turn this on by default in the future.

sea-orm-cli generate entity --output-dir ./src/entity --entity-format dense

More to come​

SeaORM 2.0 is shaping up to be our most significant release yet - with a few breaking changes, plenty of enhancements, and a clear focus on developer experience. We'll dive into Entity-first workflow in the next post, so keep an eye out for the next update!

SeaORM 2.0 will launch alongside SeaQuery 1.0. If you make extensive use of SeaQuery, we recommend checking out our earlier blog post on SeaQuery 1.0 to get familiar with the changes.

SeaORM 2.0 has reached its release candidate phase. We'd love for you to try it out and help shape the final release by sharing your feedback.

SQL Server Support​

SQL Server for SeaORM offers the same SeaORM API for MSSQL. We ported all test cases and examples, complemented by MSSQL specific documentation. If you are building enterprise software, you can request commercial access. It is currently based on SeaORM 1.0, but we will offer free upgrade to existing users when SeaORM 2.0 is finalized.

🖥️ SeaORM Pro: Professional Admin Panel​

SeaORM Pro is an admin panel solution allowing you to quickly and easily launch an admin panel for your application - frontend development skills not required, but certainly nice to have!

SeaORM Pro has been updated to support the latest features in SeaORM 2.0.

Features:

• Full CRUD
• Built on React + GraphQL
• Built-in GraphQL resolver
• Customize the UI with TOML config
• Role Based Access Control (new in 2.0)

Sponsors​

Gold Sponsor​

QDX pioneers quantum dynamics–powered drug discovery, leveraging AI and supercomputing to accelerate molecular modeling. We're grateful to QDX for sponsoring the development of SeaORM, the SQL toolkit that powers their data intensive applications.

GitHub Sponsors​

If you feel generous, a small donation will be greatly appreciated, and goes a long way towards sustaining the organization.

A big shout out to our GitHub sponsors 😇:

🦀 Rustacean Sticker Pack​

The Rustacean Sticker Pack is the perfect way to express your passion for Rust. Our stickers are made with a premium water-resistant vinyl with a unique matte finish.

Sticker Pack Contents:

• Logo of SeaQL projects: SeaQL, SeaORM, SeaQuery, Seaography
• Mascots: Ferris the Crab x 3, Terres the Hermit Crab
• The Rustacean wordmark

Support SeaQL and get a Sticker Pack!

GraphQL has become the preferred interface for product teams. Both frontend and backend developers benefit from its type-safety, contractual guarantees, and composability. Yet the real challenge lies on the backend: implementing relational resolvers that can traverse complex schemas is often difficult and time-consuming.

Yes, there are libraries that can spin up a GraphQL resolver quickly, but they often come with trade-offs: they're hard to customize, making it painful to add additional endpoints when your application grows beyond the basics.

The hardest challenge is customization. Real-world applications demand fine-grained permissions and context-dependent business logic. Seaography is designed to solve this exact problem, offering:

• Automatic GraphQL resolver generation with data loader integration to solve the N+1 problem
• Extensive customization options and the ability to add custom endpoints easily
• Authorization: Role-Based Access Control (RBAC) and fine-grained control with hooks / guards

🧭 What is Seaography​

A video is worth a thousand words, so let's look at a quick demo.

In under a minute, we've done the following:

1. Generate SeaORM entities from an existing sakila database (SQLite in demo)
2. Generate a GraphQL web server around the entities (supports Axum, Actix, Poem)
3. Launch it and run some queries with GraphQL playground

This is of course a speed run, but you can follow the same steps easily, and the generated framework is fully customizable.

What kinds of queries are supported?​

Filter, Ordering and Pagination​

{
  film(
    filters: {
      title: { contains: "sea" } # ⬅ like '%sea%'
      and: [{ releaseYear: { gt: "2000" } }, { length: { gt: 120 } }]
      # ⬆ composable attribute filters
    }
    orderBy: { filmId: ASC }
    pagination: { page: { page: 0, limit: 10 } }
    # ⬆ cursor based pagination is also supported:
    #    pagination: { cursor: { limit: 10, cursor: "Int[3]:100" } }
  ) {
    nodes {
      filmId
      title
      description
    }
    paginationInfo {
      pages
      current
    }
  }
}

Nested Relational Query​

The following query finds us all the documentaries starred by the actor "David" along with the stores having it in stock so that we can go rent it.

{
  film(
    # ⬇ filter by related entity
    having: { # ⬅ where exists (..) AND (..)
      actor: { firstName: { eq: "David" } }
      category: { name: { eq: "Documentary" } }
    }
  ) {
    nodes {
      filmId
      title
      # ⬇ skipped the film_actor junction
      actor {
        nodes {
          firstName
          lastName
        }
      }
      # ⬇ nested relational query
      inventory {
        nodes {
          store {
            address {
              address
              city {
                city
              }
            }
          }
        }
      }
    }
  }
}

There are two join paths in this query:

film -> film_actor -> actor
     -> inventory -> store -> address -> city

A data loader is used for resolving the relations, such that it does not suffers from the N+1 problem.

Mutations: create, update, delete​

Full CRUD is supported, including CreateOne CreateBatch Update and Delete.

mutation {
  # ⬇ operations will be executed inside a transaction
  filmTextCreateBatch(
    data: [
      { filmId: 1, title: "Foo bar", description: "Lorem ipsum dolor sit amet" }
      { filmId: 2, title: "Fizz buzz", description: "Consectetur adipiscing elit" }
    ]
    ) {
      filmId
      title
      description
    }
}

Custom Query​

The above is not something entirely new, as some features already exist in Seaography 1.0. The real game-changer is how you can implement custom endpoints and mix-and-match them with SeaORM entities. Let's dive into it!

Custom Query with pagination​

Seaography 2.0 introduced a set of macros to allow you to write custom query endpoints by reusing facilities in Seaography.

Let's say we have a Customer entity:

//! This is an entity from the sakila schema, generated by sea-orm-cli
use sea_orm::entity::prelude::*;

#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Eq)]
#[sea_orm(table_name = "customer")]
pub struct Model {
    #[sea_orm(primary_key, auto_increment = false)]
    pub customer_id: i32,
    pub store_id: i32,
    pub first_name: String,
    pub last_name: String,
    ..
}

We want to create a custom endpoint, like the one Seaography already provides, but with an additional requirement: only return customers of the current store from which the user makes request from.

use seaography::{apply_pagination, Connection, CustomFields, PaginationInput};

pub struct Operations;

#[CustomFields]
impl Operations {
    async fn customer_of_current_store(
        ctx: &Context<'_>,
        pagination: PaginationInput,
        //          ⬆ this input struct is provided by Seaography
    ) -> async_graphql::Result<Connection<customer::Entity>> {
        //  this output struct ⬆ is provided by Seaography
        let db = ctx.data::<DatabaseConnection>()?;
        //  ⬆ this is a normal SeaORM db connection
        let session = ctx.data::<Session>()?;
        //  ⬆ this session is inject by the HTTP handler
        let query = customer::Entity::find()
        //          ⬆ this is the same old SeaORM API
            .filter(customer::Column::StoreId.eq(session.store_id));
        //  ⬆ here we implement our custom logic
        // note that here, we haven't execute the query yet ..
        // instead, we pass it to Seaography to handle the rest!
        let connection = apply_pagination(&CONTEXT, db, query, pagination).await?;
        //                                         now the query executes ⬆ 

        Ok(connection)
    }
}

This would expose the following query endpoint:

customer_of_current_store(
  pagination: PaginationInput
): CustomerConnection!

Query it like the following:

{
  customer_of_current_store(pagination: { page: { page: 0, limit: 10 } }) {
    nodes {
      storeId
      customerId
      firstName
      lastName
      email
    }
    paginationInfo {
      pages
      current
    }
  }
}

It's almost effortless, right? In just a few lines of code, we've added a new API endpoint that does a lot under the hood. But the heavylifting is done by Seaography + SeaORM.

How does it work?​

On a very high-level, how it all works:

1. Seaography bridges SeaORM types with Async GraphQL, such that any SeaORM entity can be used as GraphQL output
2. The schema meta of SeaORM entities are transformed into GraphQL schema on-the-fly on application startup

The lifecycle of a GraphQL request:

1. Async GraphQL parses the HTTP request and construct a GraphQL request context
2. Your http handler intercepts this request and adds in additional session context
3. This GraphQL request is passed to Seaography
4. Seaography parses the input types and then construct the Rust types
5. Your async resolver is called, performing some business logic and returns result to Seaography
6. Seaography transforms the output and return to Async GraphQL
7. Async GraphQL does some final checks and serializes everything into a HTTP response

You may wonder, isn't the above kind of already possible by using Async GraphQL's derive macros, for example, by deriving SimpleObject on a SeaORM entity?

Actually this is how Seaography 0.1 worked in its initial release. However, the complex queries we shown you in the beginning is only achievable with a dynamic schema, but in Async GraphQL the static and dynamic schemas are completely different type systems - they can't inter-operate ... until now!

The difference is, the transformation between SeaORM Model <-> GraphQL Model happens dynamically, so there's not a ton of code generated beneath the surface.

Custom Mutation​

Let's continue on making custom mutation endpoints. Say now we want to create a transactional endpoint for staff members in store to handle customer rentals.

First we can design the data structures for the input form:

use sea_orm::entity::prelude::{DateTimeUtc};
use seaography::{async_graphql, CustomFields, CustomInputType};

#[derive(Clone, CustomInputType)]
pub struct RentalRequest {
    pub customer: String,
    pub film: String,
    pub coupon: Option<Coupon>,
    pub timestamp: DateTimeUtc,
}

#[derive(Clone, CustomInputType)]
pub struct Coupon {
    pub code: String,
    pub points: Option<Decimal>,
}

Then we can define the mutation endpoint. The business logic is:

1. Look up the specifc customer and film
2. Find if there is inventory in store. If not, return error
3. Create a new rental record and remove the item from inventory

#[CustomFields]
impl Operations {
    async fn rental_request(
        ctx: &Context<'_>,
        rental_request: RentalRequest,
        //              ⬆ our custom input struct
    ) -> async_graphql::Result<rental::Model> {
        //                     ⬆ a normal SeaORM Model
        let db = ctx.data::<DatabaseConnection>()?;
        let session = ctx.data::<Session>()?;
        let txn = db.begin().await?;
        //  ⬆ create a transaction to make operation atomic

        let customer = Customer::find_by_name(rental_request.customer, &txn).await?;
        let film = Film::find_by_title(rental_request.film, &txn).await?;
        //  ⬆ helper methods to find the corresponding customer and film

        //  ⬇ find if there is inventory in current store
        let inventory = Inventory::find()
            .filter(inventory::Column::FilmId.eq(film.id))
            .filter(inventory::Column::StoreId.eq(session.store_id))
            .one(&txn)
            .unwrap_or(Error::NoInventory)?;
        //  ⬆ return error if no inventory

        let rental = rental::ActiveModel {
            rental_date: Set(rental_request.timestamp),
            inventory_id: Set(inventory.id),
            customer_id: Set(customer.id),
            staff_id: Set(session.staff_id), // ⬅ current staff
            last_update: Set(Utc::now()),
            ..Default::default()
        }.insert(&txn).await?;

        inventory.delete(&txn).await?;
        //       ⬆ now remove it from inventory
        txn.commit().await?;
        // ⬇ return the newly created rental record
        Ok(rental)
    }
}

The Coupon object is used to demonstrate that nested objects are supported, and it will be reflected in the GraphQL schema. I will leave it as an exercise for you to fit in the logic for handling it.

Custom methods and unions​

The GraphQL type system is very expressive (so is Rust), and so I want to demonstrate two more advanced features:

#[derive(Clone, CustomInputType, CustomOutputType)]
pub struct Rectangle {
    pub origin: Point,
    pub size: Size,
}

#[CustomFields]
impl Rectangle {
    pub async fn area(&self) -> async_graphql::Result<f64> {
        //            ⬆ this is an instance method
        Ok(self.size.width * self.size.height)
    }
}

#[derive(Clone, CustomInputType, CustomOutputType)]
pub struct Circle {
    pub center: Point,
    pub radius: f64,
}

#[CustomFields]
impl Circle {
    pub async fn area(&self) -> async_graphql::Result<f64> {
        Ok(std::f64::consts::PI * self.radius * self.radius)
    }
}

#[derive(Clone, CustomInputType, CustomOutputType)]
pub enum Shape {
    Rectangle(Rectangle),
    Circle(Circle),
    Triangle(Triangle),
}

After registering as complex_custom_outputs, they will appear like below in the GraphQL schema:

union Shape = Rectangle | Circle | Triangle

type Rectangle {
  origin: Point!
  size: Size!
  area: Float! # ⬅ as a 'computed property'
}

The area method will only be invoked when a query includes this field. Note that it is an async function, so you can even do database queries inside the function. For example, you can return a SimpleObject from a related model.

The union type definition allows you to use union types in input / output, a very natural construct in Rust.

Full example can be found here.

Lifecycle hooks​

In Seaography, all logic is centralized in the same process, and it allows you to inject arbitrary custom logic throughout the request lifecycle using hooks. You can even implement access control this way.

Fine‑grained Access Control​

Imagine you have a drawing app, and users can only access projects they own. You can implement the access control logic like the following:

struct AccessControlHook;

impl LifecycleHooksInterface for AccessControlHook {
    fn entity_filter(
        &self,
        ctx: &ResolverContext,
        entity: &str,
        _action: OperationType, // ⬅ Read, Create, Update, Delete
    ) -> Option<Condition> {
        let session = ctx.data::<Session>()?;
        //  ⬆ extract user session
        match entity {
            "Project" => Some(
                Condition::all()
                    .add(project::Column::OwnerId.eq(session.user_id))
                //  ⬆ add custom filter condition
            ),
            _ => None,
        }
    }
}

By registering that into Seaography, this function will be called every time an Entity is being accessed:

lazy_static::lazy_static! {
    static ref CONTEXT : BuilderContext = {
        BuilderContext {
            hooks: LifecycleHooks::new(AccessControlHook),
            ..Default::default()
        }
    };
}

Other hooks​

There are many useful hooks for type conversion, access guard, event notification, etc.

pub trait LifecycleHooksInterface: Send + Sync {
    /// This happens before an Entity is accessed
    fn entity_guard(
        &self, ctx: &ResolverContext, entity: &str, action: OperationType
    ) -> GuardAction {
        GuardAction::Allow
    }

    /// This happens after an Entity is mutated
    async fn entity_watch(
        &self, ctx: &ResolverContext, entity: &str, action: OperationType
    ) {}
}

🖥️ SeaORM Pro: A Seaography Showcase​

With SeaORM Pro, you can launch a ready-to-use admin panel in minutes. Built on Seaography, it demonstrates the seamless integration of the full technology stack - async Rust backend, React frontend, and GraphQL as the protocol.

SeaORM Pro has been updated to support the latest features in SeaORM 2.0, with RBAC support now available for preview in SeaORM Pro Plus.

Features:

• Full CRUD
• Built on React + GraphQL
• Customize the UI with TOML config
• GraphQL resolver using Seaography
• Custom GraphQL endpoints (new in 2.0)
• Role Based Access Control (new in 2.0)

Conclusion​

It took us a long time to get here, but this is our vision for application development in Rust: a framework that makes it effortless to get started, gives developers a ton of functionality out of the box, and still provides the power and flexibility to build complex applications.

We're heavily inspired by tools in the Python, Ruby and node.js ecosystem. You can draw some parallels between Seaography and FastAPI:

In another sense, Seaography is like PostGraphile, offering instant GraphQL API for SQL databases:

Sponsors​

This Seaography release has been made possible through the generous sponsorship of QDX and their close collaboration with SeaQL.org. QDX has built their data-driven applications with the Seaography + SeaORM stack, and we are deeply grateful for their contributions - both financial and technical - that helped bring this release to reality.

We welcome companies to collaborate with SeaQL.org to adopt and unlock the full potential of the Rust + SeaQL ecosystem, with our team providing expert technical consulting to support their software development.

Gold Sponsor​

QDX pioneers quantum dynamics–powered drug discovery, leveraging AI and supercomputing to accelerate molecular modeling. We're grateful to QDX for sponsoring SeaQL.org.

SeaORM 2.0 introduces Role-Based Access Control (RBAC), bringing first-class authorization into your data layer. No more bolting on ad-hoc permission checks or scattering business rules across services - SeaORM lets you define roles and permission rules and enforce access policies directly inside the database connection. It's a powerful tool for building multi‑faceted applications that demand authorization.

Overview of SeaORM RBAC​

Here is a high level overview of the design and the requirements that shaped them:

1. Table‑level access control

Different user groups can only read or modify certain tables, e.g. customers can only read invoices, but not modify them.

Design: RBAC engine is table‑scoped so permissions can be expressed directly in terms of CRUD on tables.

2. Simplicity of user assignment

Each user should have a clear, unambiguous role to avoid confusion.

Design: one user = one role. This prevents complexity of multiple roles per user.

3. Role hierarchy and inheritance

We want to create roles that inherit from multiple roles like A = B + C where A will have the union of permissions from B and C.

We want to avoid duplicating permission sets across roles. For example, a 'Manager' should automatically get all 'Employee' permissions, plus extras.

Design: Hierarchical roles with multiple inheritance.

4. Granular, composable permissions

We need to allow fine‑grained control like 'read customers but not update them'. We want permission grant to be easy to reason about.

Design: Role can be assigned set of permissions (CRUD) on resources (tables). Permissions are additive, once granted, cannot be taken away (but can be overridden on a per user basis).

5. Extensibility

We want to extend beyond tables (e.g. application specific actions, or even non‑DB resources).

Design: Engine is generic - resource + permission abstraction can be applied to more than just CRUD operations on SQL tables.

6. Wildcard for convenience

Sometimes we need to grant superusers full access without enumerating every resource/permission.

Design: Opt‑in * wildcard for 'all permissions' or 'all resources.'

7. Per‑user overrides

Occasionally, a single user needs an exception (e.g. a contractor who can only read one table, or a manager who should be denied one sensitive table).

Design: User‑level overrides to grant/deny permissions.

Why reinventing the wheel?​

Our first thought is to look into the possibility of integrating an existing open-source RBAC engine, but we developed our own in the end, because we want to integrate it tightly with SeaORM.

1. Rules and permissions live in the same database as your app

By storing roles and permissions in the same database as your application data, you keep everything in one place. There's no separate DSL, no external policy files, and no risk of your access rules drifting out of sync with your schema. So you can query and update RBAC rules in migrations, just like other tables. Having a single source of truth simplifies development and deployment.

2. The hard part isn't expressing rules, it's enforcing them

Most policy engines are great at describing rules in abstract terms, but the real challenge is: how do you actually enforce those rules against SQL queries? With an external library, we still need to analyze raw SQL statements ourselves and match that up with the rule definitions. By embedding RBAC directly into SeaORM, we can analyze all queries and enforce those rules.

3. Lightweight and performant

Because the RBAC engine is part of SeaORM itself, it's lightweight and integrated - no extra runtime or external dependency. The runtime cost is also minimal, and most importantly, you don't pay for what you don't use. This feature can be turned off completely.

Concepts​

Let's take a look at the RBAC schema and go through the entities.

Entities​

User​

The user table is defined by your application. SeaORM doesn't manage that. However we currently require it to have an integer key.

Role​

Each role comes with a set of privileges. For example, 'admin', 'sales manager' and 'customer service'.

Permissions​

The actions we can perform on resources. There are 4 basic permissions, select, insert, update and delete. You can define more for your application.

Resources​

The resources being accessed. In our case they are database tables.

Relations​

User <-> Role​

As mentioned in the design above, User has a 1-1 relationship with role, meaning each user can only be assigned at most 1 role.

Role Hierarchy​

Role has a self-referencing relation, and they form a DAG (Directed Acyclic Graph). Most commonly they form a hierarchy tree that somewhat resembles an organization chart.

A simple tree example:

admin <- manager <- sales
                 <- warehouse

If we add the following to the graph, such that each role can have multiple super roles, then it becomes a DAG.

admin <- sourcing <- warehouse

Each role has their own set of permissions. On runtime, the engine will walk the role hierarchy and take the union of all permissions of the sub-graph.

Role <-> Permission <-> Resource​

Each role can have many such entries, and permission is set for each resource individually. For example: manager - update - order.

User override​

The schema is a mirror of above: User <-> Permission <-> Resource, with an extra grant field, false means deny.

Usage​

There are two stages: rules definiton when the RBAC rules are defined, and runtime authorization when these rules are enforced.

Rules Definition​

You can actually update the rules using the provided SeaORM entities, but we provide a set of utilities to make mutating RBAC rules easier.

These methods are idempotent and can be used in migrations.

Create RBAC tables​

sea_orm::rbac::schema::create_tables(db, Default::default()).await?;

Add resources & permissions​

let mut context = RbacContext::load(db).await?;

let tables = [
    baker::Entity.table_name(),
    bakery::Entity.table_name(),
    cake::Entity.table_name(),
    cakes_bakers::Entity.table_name(),
    customer::Entity.table_name(),
    lineitem::Entity.table_name(),
    order::Entity.table_name(),
    "*", // WILDCARD
];

context.add_tables(db, &tables).await?;
context.add_crud_permissions(db).await?;

Define roles​

First we create the roles.

context.add_roles(db, &["admin", "manager", "public"]).await?;

Then we can define the role hierarchy.

admin <- manager <- public

context
    .add_role_hierarchy(
        db,
        &[
            RbacAddRoleHierarchy {
                super_role: "admin",
                role: "manager",
            },
            RbacAddRoleHierarchy {
                super_role: "manager",
                role: "public",
            },
        ],
    )
    .await?;

Add role permissions​

The permission and resource sets will be multiplied, i.e. Cartesian product taken.

// public can select everything, here wildcard is used
context.add_role_permissions(db, "public", &["select"], &["*"]).await?;

// manager can create / update cake and baker
context
    .add_role_permissions(
        db,
        "manager",
        &["insert", "update"],
        &["cake", "baker", "cakes_bakers"],
    )
    .await?;

// admin can CRUD everything
context
    .add_role_permissions(db, "admin", &["insert", "update", "delete"], &["*"])
    .await?;

Assign user role​

context
    .assign_user_role(db, &[
        // (user_id, role)
        (1, "admin"),
        (2, "manager"),
        (3, "public"),
    ])
    .await?;

Runtime Authorization​

With these rules defined, we can now use them in our application.

Initialize RBAC engine​

By default, it expects the RBAC tables are in the same database schema as the current connection. They can also be fetched from another database connection.

let db: &DbConn;

db.load_rbac().await?;

The RBAC rules are cached in memory and shared among all database connections via RwLock, so they can be reloaded anytime.

Authenticate user​

This can be done by a web framework, where the user identity is extracted from a JWT token from HTTP requests. Here we assign them manually.

use sea_orm::rbac::RbacUserId;
let admin = RbacUserId(1);
let manager = RbacUserId(2);
let public = RbacUserId(3);

Create restricted connection​

This is the key step. Once a RestrictedConnection is created, it is bounded to the user for the lifetime of the object. It is cheap to create and destroy them, as they are just Arc inside.

The RestrictedConnection implements the standard DatabaseConnection API, so it can be used in place of a normal DbConn.

All queries made through SeaORM, including through Entity (ActiveModel) or lower level APIs (Insert) are audited. Only queries with matching permissions will be executed. DDL (i.e. ALTER) and raw SQL are not supported for now, so they will be rejected.

let db: RestrictedConnection = db.restricted_for(admin)?;

By writing functions only accepting RestrictedConnection, you can safeguard all operations within the scope of the function, as there is no way from a type system sense for it to degrade into normal DatabaseConnection. (In Rust we normally don't do singleton / global scope, so any operation having global side effects is very obvious.)

// admin can create bakery
operation(db.restricted_for(admin)?).await?;

fn operation(db: RestrictedConnection) -> Result<(), DbErr> {
    let seaside_bakery = bakery::ActiveModel {
        name: Set("SeaSide Bakery".to_owned()),
        profit_margin: Set(10.2),
        ..Default::default()
    };

    let res = Bakery::insert(seaside_bakery).exec(&db).await?;
    let bakery: Option<bakery::Model> = 
        Bakery::find_by_id(res.last_insert_id).one(&db).await?;

    assert_eq!(bakery.unwrap().name, "SeaSide Bakery");
    Ok(())
}

// manager can't create bakery
operation(db.restricted_for(manager)?).await?;

fn operation(db: RestrictedConnection) -> Result<(), DbErr> {
    assert!(matches!(
        Bakery::insert(bakery::ActiveModel::default())
            .exec(db)
            .await,
        Err(DbErr::AccessDenied { .. })
    ));
    Ok(())
}

// manager can create cake & baker
operation(db.restricted_for(manager)?).await?;

fn operation(db: RestrictedConnection) -> Result<(), DbErr> {
    cake::Entity::insert(cake::ActiveModel {
        name: Set("Cheesecake".to_owned()),
        price: Set(2.into()),
        bakery_id: Set(Some(1)),
        gluten_free: Set(false),
        ..Default::default()
    })
    .exec(&db)
    .await?;

    // transaction is supported: using async closure
    db.transaction::<_, _, DbErr>(|txn| {
        Box::pin(async move {
            cake::Entity::insert(cake::ActiveModel {
                name: Set("Chocolate".to_owned()),
                price: Set(3.into()),
                bakery_id: Set(Some(1)),
                gluten_free: Set(true),
                ..Default::default()
            })
            .exec(txn)
            .await?;

            Ok(())
        })
    })
    .await?;

    // transaction using the begin / commit API
    let txn: RestrictedTransaction = db.begin().await?;

    baker::Entity::insert(baker::ActiveModel {
        name: Set("Master Baker".to_owned()),
        contact_details: Set(Default::default()),
        bakery_id: Set(Some(1)),
        ..Default::default()
    })
    .exec(&txn)
    .await?;

    txn.commit().await?;
    Ok(())
}