61 posts tagged with "news"

In our last post, we introduced a Smart Entity Loader that made querying multi-path relations into nested models simple and efficient. That solved the read side of the problem.

With nested ActiveModel, you can now do the reverse: persist a nested object back into the database in one operation. SeaORM walks the tree, detects changes, constructs the insert and update statements, and executes them in the correct order to respect foreign key dependencies.

Gist​

The following operation saves a new set of user + profile + post + tag + post_tag into the database atomically:

let user = user::ActiveModel::builder()
    .set_name("Bob")
    .set_email("bob@sea-ql.org")
    .set_profile(profile::ActiveModel::builder().set_picture("image.jpg"))
    .add_post(
        post::ActiveModel::builder()
            .set_title("Nice weather")
            .add_tag(tag::ActiveModel::builder().set_tag("sunny")),
    )
    .save(db)
    .await?;

Unfolding​

This builder pattern constructs the following object tree:

user::ActiveModelEx {
    name: Set("Bob".into()),
    email: Set("bob@sea-ql.org".into()),
    profile: HasOneModel::Set(profile::ActiveModelEx {
        picture: Set("image.jpg".into()),
        ..Default::default()
    }),
    posts: HasManyModel::Append(post::ActiveModelEx {
        title: Set("Nice weather".into()),
        tags: HasManyModel::Append(tag::ActiveModel {
            tag: Set("sunny".into()),
            ..Default::default()
        }),
        ..Default::default()
    }),
    ..Default::default()
}
.save(db)
.await?

.. which is equivalent to doing the following manually:

let txn = db.begin().await?;

// insert a user
let user = user::ActiveModelEx {
    name: Set("Bob".into()),
    email: Set("bob@sea-ql.org".into()),
    ..Default::default()
}.insert(&txn).await?;

// profile belongs_to user (1-1)
let profile = profile::ActiveModelEx {
    user_id: Set(user.id),
    picture: Set("image.jpg".into()),
    ..Default::default()
}.insert(&txn).await?;

// post belongs_to user (1-N)
let post = post::ActiveModelEx {
    user_id: Set(user.id),
    title: Set("Nice weather".into()),
    ..Default::default()
}.insert(&txn).await?;

// insert a tag
let tag = tag::ActiveModel {
    tag: Set("sunny".into()),
    ..Default::default()
}
.insert(&txn)
.await?;

// associate tag to post
post_tag::ActiveModel {
    post_id: Set(post.id),
    tag_id: Set(tag.id),
}
.insert(&txn)
.await?;

txn.commit().await?;

Relational Dependency​

The core of the problem lies in figuring the foreign key relations between Entities and executing the queries in the correct order. SeaORM supports the following:

Has One / Belongs To​

User 1-1 Profile

#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
#[sea_orm(table_name = "user")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    #[sea_orm(has_one)]
    pub profile: HasOne<super::profile::Entity>,
    ..
}

There is a unique key on user_id, making this relation one-to-one.

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

Since profile belongs to user, the user has to be inserted first to obtain it's id.

In SeaORM, it doesn't matter which way the model is nested, it will be executed in the correct order.

// also okay:
profile::ActiveModel::builder()
    .set_user(
        user::ActiveModel::builder()
            .set_name("Alice")
            .set_email("alice@rust-lang.org"),
    )
    .set_picture("image.jpg")
    .save(db)
    .await?;

Has Many​

User 1-N Post

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

This is very similar to 1-1, with the nested model being a vector instead of option.

There are two possible actions: Replace and Append. The default action is append, which is non-destructive.

Let's say Bob has written a new blog post, there is no reason having to query all posts bob has written; we can simply do the following:

// query user, but no posts
let bob = user::Entity::load().filter_by_email("bob@sea-ql.org").one(db).await?.unwrap();

let mut bob.into_active_model();
bob.posts.push(post::ActiveModel::builder().set_title("Another weekend"));
bob.save(db).await?; // INSERT INTO post ..

However, sometimes we do want an empty vector to mean 'delete all', or we want to specify the exact set of children. Then we can use Replace.

bob.posts.replace_all([]); // delete all
bob.posts.replace_all([post_1]); // retain only this post

This will result in the following actions, where posts other than post 1 will be deleted:

SELECT FROM post WHERE user_id = bob.id
DELETE FROM post WHERE id = 2

Many to Many​

Post M-N Tag

Many-to-many relations are essential when modeling complex schemas. A unique feature of SeaORM is that it models many-to-many relations as a first-class construct, so you don't need to think about the junction table.

#[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 title: String,
    #[sea_orm(has_many, via = "post_tag")] // ⬅ specify junction table
    pub tags: HasMany<super::tag::Entity>,
    ..
}

#[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)] // ⬅ composite key
    pub post_id: i32,
    #[sea_orm(primary_key, auto_increment = false)] // ⬅ composite key
    pub tag_id: i32,
    #[sea_orm(belongs_to, from = "post_id", to = "id")] // ⬅ belongs to both
    pub post: Option<super::post::Entity>,
    #[sea_orm(belongs_to, from = "tag_id", to = "id")] // ⬅ belongs to both
    pub tag: Option<super::tag::Entity>,
}

#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
#[sea_orm(table_name = "tag")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    #[sea_orm(unique)]
    pub tag: String,
}

M-N relations is not just 1-N + 1-1, it actually breaks away from the notion. Let's look at the following example, insert a new post with 2 tags:

// Insert one tag for later use
let sunny = tag::ActiveModel::builder().set_tag("sunny").save(db).await?;

// Insert a new post with 2 tags
let post = post::ActiveModel::builder()
    .set_title("A sunny day")
    .set_user(bob)
    .add_tag(sunny) // an existing tag
    .add_tag(tag::ActiveModel::builder().set_tag("outdoor")) // a new tag
    .save(db) // new tag will be created and associcated to the new post
    .await?;

Which results in the following actions:

INSERT INTO post (user_id, title) VALUES (bob.id, 'A sunny day') RETURNING id
INSERT INTO tag (tag) VALUES ('outdoor') RETURNING id
INSERT INTO post_tag (post_id, tag_id) VALUES (post.id, sunny.id) (post.id, outdoor.id)

Their relation is no longer "belongs to", they are just associated with each other. Removing tags from post does not delete the tags, but only the associations in the junction table.

post.tags.replace_all([outdoor]); // let's say we remove the tag sunny

Results in:

DELETE FROM post_tag WHERE (post_id, tag_id) IN ((post.id, sunny.id))

One more example to make this easier to grasp: in a Film M-N Actor relation, deleting a film does not delete its actors, since they can still appear in other films.

Note​

SeaORM also supports using a surrogate primary key on the junction table, though a composite primary key is recommended.

#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
#[sea_orm(table_name = "film_actor")]
pub struct Model {
    #[sea_orm(primary_key)] // ⬅ normal primary key
    pub id: i32,
    #[sea_orm(unique_key = "film_actor")] // ⬅ unique key
    pub film_id: i32,
    #[sea_orm(unique_key = "film_actor")] // ⬅ unique key
    pub actor_id: i32,
    #[sea_orm(belongs_to, from = "film_id", to = "id")]
    pub film: HasOne<super::film::Entity>,
    #[sea_orm(belongs_to, from = "actor_id", to = "id")]
    pub actor: HasOne<super::actor::Entity>,
}

Change Detection​

Let's go back to the basics, in SeaORM every Model is backed by an ActiveModel:

pub struct ModelEx {
    #[sea_orm(primary_key)]
    pub id: i32,
    pub user_id: i32,
    pub title: String,
    pub author: HasOne<super::user::Entity>,
    pub tags: HasMany<super::tag::Entity>,
}

// generated by macro:
pub struct ActiveModelEx {
    #[sea_orm(primary_key)]
    pub id: ActiveValue<i32>,
    pub user_id: ActiveValue<i32>,
    pub title: ActiveValue<String>,
    pub author: HasOneModel<super::user::Entity>,
    pub tags: HasManyModel<super::tag::Entity>,
}

Each ActiveValue is a tri-state.

pub enum ActiveValue<V>
{
    Set(V),
    Unchanged(V),
    NotSet,
}

This allows SeaORM to keep track of what's changed. When you first query a fresh Model from database, the default state is Unchanged. When you perform some change in code, the state will be changed to Set. So when you run save, only the changed columns are updated.

let post = post::Entity::find_by_id(22).one(db).await?.unwrap(); // Model
let mut post = post.into_active_model(); // ActiveModel
post.title = Set("The weather changed!");
post.save(db).await?; // UPDATE post SET title = '..' WHERE id = 22

This has two advantages: it avoids over-updating, reducing the amount of data sent over the wire. More importantly, multiple API endpoints can safely update different column sets without risk of race conditions and without relying on transactions or locking mechanisms.

This concept is extended to nested ActiveModels, allowing SeaORM to walk the nested object tree and determine which sub-tree has been changed and requires updating.

For example:

let mut bob: user::ActiveModel = ..;

// update post title
bob.posts[0].title = Set("Lorem ipsum dolor sit amet".into());
// update post comment
bob.posts[0].comments[0].comment = Set("nice post! I learnt a lot".into());
// add a new comment too
bob.posts[1].comments.push(
    comment::ActiveModel::builder().set_comment("interesting!")
);
bob.save(db).await?;

Results in:

BEGIN TRANSACTION

UPDATE post SET title = '..' WHERE id = post.id
UPDATE comment SET comment = '..' WHERE id = comment.id
INSERT INTO comment (post_id, comment) VALUES (post.id. '..')

COMMIT

It's a lot to take in, but once you build a clear mental model of SeaORM's concepts and mechanisms, you'll find yourself far more productive!

You can find all the techniques described in this blog post in a single-file example application.

Cascade Delete​

If the relations are defined with ON DELETE CASCADE, this problem does not exist. However, SeaORM can also perform cascade deletes on the client side. It applies the same rules described above, but in reverse.

For example, Post belongs to User. All posts must be deleted before the user; otherwise, the SQL operation will fail.

let user_4 = user::Entity::find_by_id(4).one(db).await?.unwrap();

user_4.cascade_delete(db).await?; // equivalent to below
user_4.into_ex().delete(db).await?;

-- query the profile belonging to user
SELECT FROM profile INNER JOIN user ON user.id = profile.user_id WHERE user.id = 4 LIMIT 1
-- delete the profile, if exist
DELETE FROM profile WHERE profile.id = 2
-- query the posts belonging to user
SELECT FROM post INNER JOIN user ON user.id = post.user_id WHERE user.id = 4
-- query the comments belonging to post
SELECT FROM comment INNER JOIN post ON post.id = comment.post_id WHERE post.id = 7
-- delete the comments, if exist
DELETE FROM comment WHERE comment.id = 5
-- query the post's tags
SELECT FROM post_tag INNER JOIN post ON post_tag.post_id = post.id WHERE post.id = 7
-- delete the post-tag associations
DELETE FROM post_tag WHERE (post_id, tag_id) IN ((7, 2), (7, 3), (7, 4))
-- post has no dependents, safe to delete now
DELETE FROM post WHERE post.id = 7
-- user has no dependents, safe to delete now
DELETE FROM user WHERE user.id = 4

Weak Belongs To​

There is one more special case of the Belongs To relation not yet mentioned: weak 1-N associations, where an entity may have an owner, but is not strictly required.

To give an example, Post 1-N Attachment. However users can upload attachments before drafting posts, thus some attachments may have no associated posts.

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

// this post has attachment_2
let post_1 = post::Entity::find_by_id(1).one(db).await?.unwrap();
post_1.cascade_delete(db).await?;

// post_id of attachment will be set to null, instead of deleting the attachment
let attachment_2 = attachment::Entity::find_by_id(2).one(db).await?.unwrap();
assert!(attachment_2.post_id.is_none());

Idempotence​

The general rule of thumb is idempotence: saving an ActiveModel a second time should be a no-op. Unless you use replace or delete, no delete will be executed.

let post = post.save(db).await?;
let post = post.save(db).await?; // no-op, as all fields are unchanged

The ActiveModel you provides is a snapshot of the desired final state of the data, and SeaORM should ensure that it ends up that way. This can be complicated, so please report any bugs.

Tips​

Keeping track of whether to use insert or update can be hard, unless the intended action is "create new from scratch". Use save as the default, and let SeaORM decide when to execute insert or update.

(If you already find these concepts familiar, it's no surprise that it's called ActiveModel.)

Backwards Compatibility​

All the 2.0 features introduced in this post are fully backwards compatible with 1.0, since only new types and methods have been added: ActiveModelEx, HasOneModel, HasManyModel and a few methods. ActiveModel continues to behave exactly as before.

However, due to the macros needing the relations' attributes to generate the implementations, these features are only available to #[sea_orm::model], but not #[sea_orm::compact_model].

🧭 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. 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)

🌟 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:

Godwin Effiong

Adam Israel

Ryan Swart

OteroRafael

Yuta Hinokuma

wh7f

MS

Numeus

Data Intuitive

Caido Community

Marcus Buffett

MasakiMiyazaki

KallyDev

Manfred Lee

Afonso Barracha

Dean Sheather

🦀 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 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).

An admin panel is essential for operating backend applications. But it often is an after-thought, or no dedicated resources is put into developing them.

SeaORM Pro is designed to bridge this gap, providing a solution that is both quick to implement and reliable for long-term use.

Table View​

There are two kinds of table view in SeaORM Pro, raw table and composite table:

Raw Table​

Each raw table corresponds to a table in the database, by default it will display all columns for all tables. You can configure the displayed columns and other settings via TOML.

[table]
title = "Products"
table_size = "middle"
page_size = 30
order_by = { field = "product_id", order = "desc" }
columns = [
    { title = "ID", field = "product_id", width = 80 },
    { title = "Thumbnail", field = "thumb_nail_photo", input_type = "image", width = 120 },
    { title = "Product Category", field = "name", relation = "product_category", ellipsis = false, width = 180 },
]
hidden_columns = [ "size", "weight" ]
all_columns = false

Composite Table​

This is where SeaORM Pro shine. You can construct table views with data joining from multiple related tables. The underlying GraphQL query can be deeply nested.

Data from parent-child relations (e.g. Order -> OrderItem) are represented as collapsible nested tables. You can configure the settings via TOML.

[parent]
name = "sales_order_header"

[parent.table]
columns = [
    { title = "ID", field = "sales_order_id", width = 80 },
    { field = "order_date" },
    { field = "purchase_order_number" },
    { field = "account_number" },
    { field = "ship_method" },
    { field = "sub_total" },
    { field = "tax_amt" },
    { field = "freight" },
]
all_columns = false


[[children]]
relation = "customer"

[children.table]
columns = [
    { title = "ID", field = "customer_id", width = 80 },
    { field = "title", width = 100 },
    { field = "first_name", width = 120 },
    { field = "middle_name", width = 120 },
    { field = "last_name", width = 120 },
]
hidden_columns = [ "name_style", "suffix", "email_address", "phone", "rowguid", "created_date" ]


[[children]]
relation = "address1"

[children.table]
title = "Shipping Address"
columns = [
    { title = "ID", field = "address_id", width = 80 },
]
hidden_columns = [ "rowguid", "created_date" ]


[[children]]
relation = "address2"

[children.table]
title = "Billing Address"
columns = [
    { title = "ID", field = "address_id", width = 80 },
]
hidden_columns = [ "rowguid", "created_date" ]


[[children]]
relation = "sales_order_detail"

[children.table]
columns = [
    { title = "Thumbnail", field = "thumb_nail_photo", relation = "product", input_type = "image", width = 120 },
    { field = "name", relation = "product", width = 300 },
    { field = "product_number", relation = "product" },
    { field = "color", relation = "product" },
    { field = "size", relation = "product" },
    { field = "weight", relation = "product" },
    { field = "order_qty" },
    { field = "unit_price" },
    { field = "unit_price_discount" },
]
hidden_columns = [ "sales_order_id", "sales_order_detail_id", "product_id", "rowguid", "created_date" ]

Editor​

Data is not editable by default. You can configure create, update and delete forms via TOML. You can also configure which columns are editable. Non-editable columns will be shown as read-only.

Pop-up Editor​

By default, the pop-up editor will be used to create and update database table.

Create​

Enable create on this database table, this is disabled by default. Columns can be hidden from the create form but it's still visible on the view table.

[create]
# Enable create for this table
enable = true
# Columns that are hidden on the create form
hidden_columns = [ "created_date" ]

Update​

Enable update on this database table, this is disabled by default. Columns can be hidden from the update form but it's still visible on the view table. Fields can also be readonly on the update form.

[update]
# Enable update for this table
enable = true
# Columns that are hidden on the update form
hidden_columns = [ "created_date" ]
# Columns that are readonly on the update form
readonly_columns = [ "product_id" ]

Delete​

Enable delete on this database table, this is disabled by default.

[delete]
# Enable delete for this table
enable = true

Model Editor​

Enable the use of model editor on this database table, this is disabled by default. The configuration of each fields are specified here in sequence, displaying across table view, create and update editor.

[editor]
# Enable model editor for this table
enable = true
# Title field to be shown
title_field = "address_line1"
# Display following columns in sequence
fields = [
    { title = "ID", field = "address_id", span = 8 },
    { field = "rowguid", span = 8 },
    { field = "created_date", span = 8 },
    { field = "address_line1", span = 12, input_type = "textarea", rows = 4 },
    { field = "address_line2", span = 12, input_type = "textarea", rows = 4 },
    { field = "city", span = 6 },
    { field = "state_province", span = 6 },
    { field = "country_region", span = 6 },
    { field = "postal_code", span = 6 },
]

Role-Based Access Control​

SeaORM Pro has been updated to support the latest features in SeaORM 2.0. Role-Based Access Control (RBAC) is fully integrated into SeaORM Pro Plus. It offers a GUI editor to edit RBAC permissions and assign user roles. Without the corresponding select permission, users will not be able to see relevant tables in the GUI. Similarly, edit buttons will be hidden if user does not have update permission.

Opt-in RBAC​

Upon upgrading to SeaORM 2.0, you can opt-in RBAC by enabling the rbac feature flag in the Rust backend:

seaography = { version = "2.0", features = ["rbac"] }

And enabling RBAC in the SeaORM Pro admin panel:

[site.rbac]
# Is RBAC enabled?
enable = true

Role Permissions​

View Role Hierarchy Diagram​

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 <- public
                 <- ...etc.

Update Role Permission​

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.

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

Role Hierarchy​

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.

User Role​

User has a 1-1 relationship with role, meaning each user can only be assigned at most 1 role.

User Override​

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

What's Next?​

There's really a lot we want to build, to make SeaORM Pro suit the needs of every project. Please consider being a sponsor and take part in shaping its future!

Here's what we have in mind:

• Single Sign On: To be able to sign-in with Google Workspace or Microsoft Business email.
• Audit Log: And so, we'd want to keep a record of users' action and being able to audit them.
• Advanced Dashboard: We want to make it super easy to design graphs and charts for the Admin Dashboard.
• Tasks: To be able to visualize and control scheduled tasks, and kick start once off tasks in ad-hoc way.
• Data Export: Export data to various formats, including CSV, Excel, and DataFrame!

🌟 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:

Godwin Effiong

Adam Israel

Ryan Swart

OteroRafael

Yuta Hinokuma

wh7f

MS

Numeus

Data Intuitive

Caido Community

Marcus Buffett

MasakiMiyazaki

KallyDev

Manfred Lee

Afonso Barracha

Dean Sheather

🦀 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 our last post, we introduced a new Entity format - designed to be more concise, more readable, and easy to write by hand.

We've also added a new COLUMN constant to make it more ergonomic, along with other enhancements.

Bye-bye CamelCase​

Previously, column names in queries had to be written in CamelCase. This was because the Column type was defined as an enum, it's simpler for the type system and faster to compile than generating a struct per column, but at the cost of losing column‑specific type information.

Our new design keeps compilation fast while restoring stronger type guarantees. As a bonus, it eliminates the need for CamelCase and even saves a keystroke.

// old
user::Entity::find().filter(user::Column::Name.contains("Bob"))

// new
user::Entity::find().filter(user::COLUMN.name.contains("Bob"))

// compile error: the trait `From<{integer}>` is not implemented for `String`
user::Entity::find().filter(user::COLUMN.name.like(2))

Under the hood, each Column value is wrapped in a byte-sized struct TypeAwareColumn. This wrapper is generic over Entity, so whether a table has 1 column or 100, the compile‑time cost stays roughly the same.

COLUMN Constant​

pub struct NumericColumn<E: EntityTrait>(pub E::Column);

impl<E: EntityTrait> NumericColumn<E> {
    pub fn eq<V>(v: V) -> Expr { .. }
}

#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
#[sea_orm(table_name = "user")]
pub struct Model {
    ..
}

// expands into following:

pub struct TypedColumn {
    pub id: NumericColumn<Entity>,
    pub name: StringColumn<Entity>,
    pub date_of_birth: DateLikeColumn<Entity>,
}

pub const COLUMN: TypedColumn = TypedColumn {
    id: NumericColumn(Column::Id),
    name: StringColumn(Column::Name),
    date_of_birth: DateLikeColumn(Column::DateOfBirth),
};

impl Entity {
    pub const COLUMN: TypedColumn = COLUMN;
}

Type-Aware Helper Methods​

Each column type wrapper exposes a set of methods that's relevant for the column's type. For example StringColumn::contains and ArrayColumn::contains are distinct methods that do the right thing!

Entity::COLUMN.name.contains("Bob") // WHERE "name" LIKE '%Bob%'

// tags is Vec<String>
Entity::COLUMN.tags.contains(vec!["awesome"]) // WHERE "tags" @> ARRAY ['awesome']

Right now there are a set of types: BoolColumn, NumericColumn, StringColumn, BytesColumn, JsonColumn, DateLikeColumn, TimeLikeColumn, DateTimeLikeColumn, UuidColumn, IpNetworkColumn, and more relevant methods can be added, feel free to make sugguestions.

Column as typed value​

One advantage of this design is that Columns are values: you can pass them into functions, combine with reflection, and build safe dynamic queries:

// returns an Expression fragment that can be used to build queries
fn filter_by_column(col: post::Column) -> Expr {
    col.eq("attribute")
}

// get an integer from a model depends on runtime condition
fn get_value_from(model: &post::Model, col: post::Column) {
    let value: i32 = model.get(col).unwrap();
    // do something on value
}

Opt-in Only​

These new structs are generated only when using the new #[sea_orm::model] or #[sea_orm::compact_model] macros. This keeps the change fully backwards‑compatible, and you incur no cost if you don't use them.

More Entity Enhancements​

A big thanks to early-adopters who provided feedback to improve SeaORM 2.0.

Related Fields​

The nested types for HasOne and HasMany have been changed from transparent type aliases to wrapper types. This makes it possible to distinguish between a relation that hasn’t been loaded and one that has loaded but yielded no models.

pub enum HasOne<E: EntityTrait> {
    #[default]
    Unloaded,
    NotFound,
    Loaded(Box<<E as EntityTrait>::ModelEx>),
}

pub enum HasMany<E: EntityTrait> {
    #[default]
    Unloaded,
    Loaded(Vec<<E as EntityTrait>::ModelEx>),
}

We've added a range of methods to the wrapper type to make it feel as transparent as possible. The goal is to reduce friction while still preserving the benefits of a strong type system.

// len() / is_empty() methods
assert_eq!(users[0].posts.len(), 2);
assert!(!users[0].posts.is_empty());

// impl PartialEq
assert_eq!(users[0].posts, [post_1, post_2]);

// this creates HasOne::Loaded(Box<profile::ModelEx>)
profile: HasOne::loaded(profile::Model {
    id: 1,
    picture: "jpeg".into(),
    ..
})

Entity Loader Paginator​

Entity Loader now supports pagination. It has the same API as a regular Select:

let paginator = user::Entity::load()
    .with(profile::Entity)
    .order_by_asc(user::COLUMN.id)
    .paginate(db, 10);

let users: Vec<user::ModelEx> = paginator.fetch().await?;

Added delete_by_key​

In addition to find_by_key, now the delete_by_key convenience method is also added:

user::Entity::delete_by_email("bob@spam.com").exec(db).await?

The delete_by_* methods now return DeleteOne instead of DeleteMany. It doesn't change normal exec usage, but would change return type of exec_with_returning to Option<Model>:

fn delete_by_id<T>(values: T) -> DeleteMany<Self>         // old

fn delete_by_id<T>(values: T) -> ValidatedDeleteOne<Self> // new

Self-Referencing Relations​

Let's say we have a staff table, where each staff has a manager that they report to:

#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
#[sea_orm(table_name = "staff")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    pub name: String,
    pub reports_to_id: Option<i32>,
    #[sea_orm(
        self_ref,
        relation_enum = "ReportsTo",
        relation_reverse = "Manages",
        from = "reports_to_id",
        to = "id"
    )]
    pub reports_to: HasOne<Entity>,
    #[sea_orm(self_ref, relation_enum = "Manages", relation_reverse = "ReportsTo")]
    pub manages: HasMany<Entity>,
}

Entity Loader​

let staff = staff::Entity::load()
    .with(staff::Relation::ReportsTo)
    .with(staff::Relation::Manages)
    .all(db)
    .await?;

assert_eq!(staff[0].name, "Alan");
assert_eq!(staff[0].reports_to, None);
assert_eq!(staff[0].manages[0].name, "Ben");
assert_eq!(staff[0].manages[1].name, "Alice");

assert_eq!(staff[1].name, "Ben");
assert_eq!(staff[1].reports_to.as_ref().unwrap().name, "Alan");
assert!(staff[1].manages.is_empty());

assert_eq!(staff[2].name, "Alice");
assert_eq!(staff[2].reports_to.as_ref().unwrap().name, "Alan");
assert!(staff[2].manages.is_empty());

assert_eq!(staff[3].name, "Elle");
assert_eq!(staff[3].reports_to, None);
assert!(staff[3].manages.is_empty());

Model Loader​

let staff = staff::Entity::find().all(db).await?;

let reports_to = staff
    .load_self(staff::Entity, staff::Relation::ReportsTo, db)
    .await?;

assert_eq!(staff[0].name, "Alan");
assert_eq!(reports_to[0], None);

assert_eq!(staff[1].name, "Ben");
assert_eq!(reports_to[1].as_ref().unwrap().name, "Alan");

assert_eq!(staff[2].name, "Alice");
assert_eq!(reports_to[2].as_ref().unwrap().name, "Alan");

assert_eq!(staff[3].name, "Elle");
assert_eq!(reports_to[3], None);

It can work in reverse too.

let manages = staff
    .load_self_many(staff::Entity, staff::Relation::Manages, db)
    .await?;

assert_eq!(staff[0].name, "Alan");
assert_eq!(manages[0].len(), 2);
assert_eq!(manages[0][0].name, "Ben");
assert_eq!(manages[0][1].name, "Alice");

assert_eq!(staff[1].name, "Ben");
assert_eq!(manages[1].len(), 0);

assert_eq!(staff[2].name, "Alice");
assert_eq!(manages[2].len(), 0);

assert_eq!(staff[3].name, "Elle");
assert_eq!(manages[3].len(), 0);

Unix Timestamp Column Type​

Sometimes it may be desirable (or no choice but) to store a timestamp as i64 in database, but mapping it to a DateTimeUtc in application code.

We've created a new set of UnixTimestamp wrapper types that does this transparently:

#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
#[sea_orm(table_name = "access_log")]
pub struct Model {
    .. // with `chrono` crate
    pub ts: ChronoUnixTimestamp,
    pub ms: ChronoUnixTimestampMillis,
    .. // with `time` crate
    pub ts: TimeUnixTimestamp,
    pub ms: TimeUnixTimestampMillis,
}

let now = ChronoUtc::now();
let log = access_log::ActiveModel {
    ts: Set(now.into()),
    ..Default::default()
}
.insert(db)
.await?;

assert_eq!(log.ts.timestamp(), now.timestamp());

Entity-First Workflow​

SchemaBuilder can now be used in migrations.

#[async_trait::async_trait]
impl MigrationTrait for Migration {
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        let db = manager.get_connection();

        db.get_schema_builder()
            .register(user::Entity)
            .apply(db) // or sync(db)
            .await
    }
}

🧭 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. 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)

🌟 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 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?;