69 posts tagged with "news"

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:

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: HasOne::Loaded(profile::ModelEx {
        ..
    }),
    posts: HasMany::Loaded(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:

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.

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.

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: 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(())
}

That's it! I hope the information above can get you started.

Conclusion​

RBAC is a new feature in SeaORM 2.0. We'd love for you to try it out and help shape the final release by sharing your feedback.

The RBAC engine is a first class construct in SeaORM, implemented underneath the application layer but above the database layer.

We believe this is the most robust approach: if it's implemented on the web framework level, it's easy to forget permission checks or some code paths can accidentally escape. Plus it will work for your application, whether you're building REST, gRPC, or GraphQL servers.

In SeaORM, analysis is done on SeaQuery AST, so it's almost free - we already have the AST in memory. Thanks to SeaQuery's feature-rich API, you can construct any complex query, including CTEs!

Compared to using the database engine's native access control capabilities, SeaORM is much easier to setup, reason about, and develop with. Plus it is database generic, so you can use it with SQLite.

Everything, including the code and rules is defined in one place, so you have a single source of truth. We believe Rust and SeaQL ecosystem is the best way to build performant, scalable and robust applications!

We'll dive into GraphQL with Seaography in the next post, so keep an eye out for the next update!

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, including RBAC support.

🖥️ 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!

Features:

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

SeaORM Pro will be updated to support the latest features in SeaORM 2.0, RBAC support is now available for preview in SeaORM Pro Plus.

RBAC-related features in SeaORM Pro Plus:

• Permission editor GUI
• Role hierarchy visualization
• User role assignment
• Add/remove user overrides

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!

In the previous blog post, we highlighted some of the new features in SeaORM 2.0. In this post, we're going to take a closer look to some of the changes under the hood.

Overhauled Entity::insert_many​

#2628 We've received many issue reports around the insert_many API. Previously, insert_many shares the same helper struct with insert_one, which led to an awkard API:

let res = Bakery::insert_many(std::iter::empty())
    .on_empty_do_nothing() // <- you needed to add this,
                           // otherwise insert empty [] would lead to error
    .exec(db)
    .await;

assert!(matches!(res, Ok(TryInsertResult::Empty)));

After careful consideration, we made a number of changes in 2.0:

1. removed APIs (e.g. Insert::add) that can panic
2. new helper struct InsertMany, last_insert_id is now Option<Value>
3. on empty iterator, None (for last_insert_id) or vec![] (when returning) is returned on execution
4. TryInsert API is unchanged

i.e. now last_insert_id is Option<Value> for InsertMany:

struct InsertManyResult<A: ActiveModelTrait>
{
    pub last_insert_id: Option<<PrimaryKey<A> as PrimaryKeyTrait>::ValueType>,
}

Which means the awkardness is removed:

let res = Entity::insert_many::<ActiveModel, _>([]).exec(db).await;

assert_eq!(res?.last_insert_id, None); // insert nothing return None

let res = Entity::insert_many([ActiveModel { id: Set(1) }, ActiveModel { id: Set(2) }])
    .exec(db)
    .await;

assert_eq!(res?.last_insert_id, Some(2)); // insert something return Some

Exec with returning now returns a Vec<Model>, so it feels intuitive:

assert!(
    Entity::insert_many::<ActiveModel, _>([])
        .exec_with_returning(db)
        .await?
        .is_empty() // no footgun, nice
);

assert_eq!(
    Entity::insert_many([
        ActiveModel {
            id: NotSet,
            value: Set("two".into()),
        }
    ])
    .exec_with_returning(db)
    .await
    .unwrap(),
    [
        Model {
            id: 2,
            value: "two".into(),
        }
    ]
);

Same on conflict API as before:

let res = Entity::insert_many([ActiveModel { id: Set(3) }, ActiveModel { id: Set(4) }])
    .on_conflict_do_nothing()
    .exec(db)
    .await;

assert!(matches!(conflict_insert, Ok(TryInsertResult::Conflicted)));

Overhauled ConnectionTrait API​

#2657 We overhauled the ConnectionTrait API. execute, query_one, query_all, stream now takes in SeaQuery statement instead of raw SQL statement.

So you don't have to access the backend to build the query yourself.

// old
let query: SelectStatement = Entity::find().filter(..).into_query();
let backend = self.db.get_database_backend();
let stmt = backend.build(&query);
let rows = self.db.query_all(stmt).await?;

// new
let query: SelectStatement = Entity::find().filter(..).into_query();
let rows = self.db.query_all(&query).await?;

A new set of methods execute_raw, query_one_raw, query_all_raw, stream_raw is added, so you can still do the following:

let backend = self.db.get_database_backend();
let stmt = backend.build(&query);

// new
let rows = self.db.query_all_raw(stmt).await?;

Better error handling in UpdateOne / DeleteOne​

#2726 UpdateOne and DeleteOne no longer implement QueryFilter and QueryTrait directly. Those implementations could expose an incomplete SQL query with an incomplete condition that touches too many records.

// bad: the following is basically update all
let query: UpdateStatement = Update::one(cake::ActiveModel::default()).into_query();