Crate sea_orm

Expand description

This is proprietary software. If you are granted an “Evaluation License” to this library, you can develop software using this library until the specified expiry date of the license. However, to deploy the software, please purchase a “Production License” from us.

SeaORM is a powerful ORM for building web services in Rust

Support us with a ⭐ !

§🐚 SeaORM

中文文档

§Advanced Relations

Model complex relationships 1-1, 1-N, M-N, and even self-referential in a high-level, conceptual way.

§Familiar Concepts

Inspired by popular ORMs in the Ruby, Python, and Node.js ecosystem, SeaORM offers a developer experience that feels instantly recognizable.

§Feature Rich

SeaORM is a batteries-included ORM with filters, pagination, and nested queries to accelerate building REST, GraphQL, and gRPC APIs.

§Production Ready

With 250k+ weekly downloads, SeaORM is production-ready, trusted by startups and enterprises worldwide.

§Getting Started

Join our Discord server to chat with others!

Documentation

Integration examples:

If you want a simple, clean example that fits in a single file that demonstrates the best of SeaORM, you can try:

Quickstart

API Docs:

§Installation

§Local Dependency

Clone this repository to your local machine. Then install sea-orm-cli with command

cargo install --path "<SEA_ORM_X_ROOT>/sea-orm-x/sea-orm-cli"

Add sea-orm-x dependency to your Cargo.toml

sea-orm = { path = "<SEA_ORM_X_ROOT>/sea-orm-x", features = ["runtime-tokio-rustls", "sqlz-mssql"] }
sea-orm-migration = { path = "<SEA_ORM_X_ROOT>/sea-orm-x/sea-orm-migration" }

§Git Dependency

Assuming you already finished setup your SSH environment.

Read more about Git Authentication in the official Cargo Book

Install sea-orm-cli with command

cargo install --git ssh://git@github.com/SeaQL/sea-orm-x.git sea-orm-cli

Add sea-orm-x dependency to your Cargo.toml

sea-orm = { git = "ssh://git@github.com/SeaQL/sea-orm-x.git", features = ["runtime-tokio-rustls", "sqlz-mssql"] }
sea-orm-migration = { git = "ssh://git@github.com/SeaQL/sea-orm-x.git" }

§Troubleshooting Git Authentication Errors

You might saw this error when building sea-orm-x.

$ cargo update

    Updating crates.io index
    Updating git repository `ssh://git@github.com/SeaQL/sea-orm-x.git`
error: failed to get `sea-orm-x` as a dependency of package `actix-example-service v0.1.0 (mssql_actix_example/service)`

Caused by:
  failed to load source for dependency `sea-orm-x`

Caused by:
  Unable to update ssh://git@github.com/SeaQL/sea-orm-x.git

Caused by:
  failed to fetch into: ~/.cargo/git/db/sea-orm-x-6642849d9d02f831

Caused by:
  failed to authenticate when downloading repository

  * attempted ssh-agent authentication, but no usernames succeeded: `git`

  if the git CLI succeeds then `net.git-fetch-with-cli` may help here
  https://doc.rust-lang.org/cargo/reference/config.html#netgit-fetch-with-cli

Caused by:
  no authentication methods succeeded

By default Cargo use its built-in SSH client. We can force Cargo to use the SSH client of the host machine by enabling git-fetch-with-cli option inside Cargo’s config file.

# ~/.cargo/config.toml

[net]
git-fetch-with-cli = true

§Quick Start

§Connection

let db = Database::connect(db_url).await?;

Connection string has the following format:

mssql://sa:password@localhost:1433/db_name?trustCertificate=true
mssql://sa:password@sql.host.com/my_db?currentSchema=my_schema

If you run into SSL error you can try adding trustCertificate=true and use rustls instead of native-tls.

§Query Builder

// A table create statement
let table = Table::create()
    .table(Glyph::Table)
    .col(
        ColumnDef::new(Glyph::Id)
            .integer()
            .not_null()
            .auto_increment()
            .primary_key(),
    )
    .col(ColumnDef::new(Glyph::Aspect).integer().not_null())
    .col(ColumnDef::new(Glyph::Image).string().not_null())
    .foreign_key(
        ForeignKey::create()
            .name("FK_2e303c3a712662f1fc2a4d0aad6")
            .from(Glyph::Table, Glyph::Id)
            .to(CharGlyph::Table, CharGlyph::GlyphId)
            .on_delete(ForeignKeyAction::Cascade)
            .on_update(ForeignKeyAction::Cascade),
    )
    .to_owned();

assert_eq!(
    table.to_string(MsSqlQueryBuilder),
    [
        r#"CREATE TABLE [glyph] ("#,
        r#"[id] int NOT NULL IDENTITY PRIMARY KEY,"#,
        r#"[aspect] int NOT NULL,"#,
        r#"[image] nvarchar(255) NOT NULL,"#,
        r#"CONSTRAINT [FK_2e303c3a712662f1fc2a4d0aad6]"#,
        r#"FOREIGN KEY ([id]) REFERENCES [character_glyph] ([glyph_id])"#,
        r#"ON DELETE CASCADE ON UPDATE CASCADE"#,
        r#")"#,
    ]
    .join(" ")
);

// A prepared select statement
assert_eq!(
    Query::select()
        .column(Glyph::Image)
        .from(Glyph::Table)
        .and_where(Expr::col(Glyph::Image).like("A"))
        .and_where(Expr::col(Glyph::Id).is_in([1, 2, 3]))
        .build(MsSqlQueryBuilder),
    (
        "SELECT [image] FROM [glyph] WHERE [image] LIKE @P1 AND [id] IN (@P2, @P3, @P4)"
            .to_owned(),
        Values(vec![
            Value::String(Some(Box::new("A".to_owned()))),
            Value::Int(Some(1)),
            Value::Int(Some(2)),
            Value::Int(Some(3))
        ])
    )
);

// A raw select statement
assert_eq!(
    Query::select()
        .column(Glyph::Id)
        .from(Glyph::Table)
        .cond_where(
            Cond::any()
                .add(
                    Cond::all()
                        .add(Expr::col(Glyph::Aspect).is_null())
                        .add(Expr::col(Glyph::Image).is_null())
                )
                .add(
                    Cond::all()
                        .add(Expr::col(Glyph::Aspect).is_in([3, 4]))
                        .add(Expr::col(Glyph::Image).like("A%"))
                )
        )
        .to_string(MsSqlQueryBuilder),
    [
        r#"SELECT [id] FROM [glyph]"#,
        r#"WHERE ([aspect] IS NULL AND [image] IS NULL)"#,
        r#"OR ([aspect] IN (3, 4) AND [image] LIKE 'A%')"#,
    ]
    .join(" ")
);

§Schema Discovery

let options: MsSqlConnectOptions = "mssql://sa:YourStrong()Passw0rd@localhost/AdventureWorksLT2016".parse()?;
let connection = MsSqlPool::connect_with(options).await?;
// Set the target schema: "SalesLT" or None (defaults to "dbo")
let schema_discovery = SchemaDiscovery::new(connection, Some("SalesLT"));

assert_eq!(
    schema_discovery.discover().await?,
    Schema {
        database: "AdventureWorksLT2016",
        schema: "SalesLT",
        version: Version {
            name: "Microsoft SQL Server 2017",
            service_pack: "RTM-CU31-GDR",
            version: "14.0.3465.1",
            edition: "Developer Edition",
        },
        tables: vec![
            TableDef {
                name: "Address",
                columns: vec![
                    ColumnInfo {
                        name: "AddressID",
                        col_type: Int,
                        null: false,
                        is_identity: true,
                        collation: None,
                        default: None,
                        comment: Some("Primary key for Address records."),
                    },
                    ColumnInfo {
                        name: "AddressLine1",
                        col_type: Nvarchar(N(60)),
                        null: false,
                        is_identity: false,
                        collation: Some(Collation("SQL_Latin1_General_CP1_CI_AS")),
                        default: None,
                        comment: Some("First street address line."),
                    },
                    ColumnInfo {
                        name: "AddressLine2",
                        col_type: Nvarchar(N(60)),
                        null: true,
                        is_identity: false,
                        collation: Some(Collation("SQL_Latin1_General_CP1_CI_AS")),
                        default: None,
                        comment: Some("Second street address line."),
                    },
                    ColumnInfo {
                        name: "City",
                        col_type: Nvarchar(N(30)),
                        null: false,
                        is_identity: false,
                        collation: Some(Collation("SQL_Latin1_General_CP1_CI_AS")),
                        default: None,
                        comment: Some("Name of the city."),
                    },
                    ColumnInfo {
                        name: "StateProvince",
                        col_type: Nvarchar(N(50)),
                        null: false,
                        is_identity: false,
                        collation: Some(Collation("SQL_Latin1_General_CP1_CI_AS")),
                        default: None,
                        comment: Some("Name of state or province."),
                    },
                    ColumnInfo {
                        name: "CountryRegion",
                        col_type: Nvarchar(N(50)),
                        null: false,
                        is_identity: false,
                        collation: Some(Collation("SQL_Latin1_General_CP1_CI_AS")),
                        default: None,
                        comment: None,
                    },
                    ColumnInfo {
                        name: "PostalCode",
                        col_type: Nvarchar(N(15)),
                        null: false,
                        is_identity: false,
                        collation: Some(Collation("SQL_Latin1_General_CP1_CI_AS")),
                        default: None,
                        comment: Some("Postal code for the street address."),
                    },
                    ColumnInfo {
                        name: "rowguid",
                        col_type: UniqueIdentifier,
                        null: false,
                        is_identity: false,
                        collation: None,
                        default: Some(NewId),
                        comment: Some("ROWGUIDCOL number uniquely identifying the record. Used to support a merge replication sample."),
                    },
                    ColumnInfo {
                        name: "ModifiedDate",
                        col_type: DateTime,
                        null: false,
                        is_identity: false,
                        collation: None,
                        default: Some(GetDate),
                        comment: Some("Date and time the record was last updated."),
                    },
                ],
                indexes: vec![
                    IndexInfo {
                        is_primary_key: false,
                        is_unique: true,
                        name: "AK_Address_rowguid",
                        index_type: NonClustered,
                        parts: vec![
                            IndexPart { column: "rowguid", order: Ascending },
                        ],
                    },
                    IndexInfo {
                        is_primary_key: false,
                        is_unique: false,
                        name: "IX_Address_AddressLine1_AddressLine2_City_StateProvince_PostalCode_CountryRegion",
                        index_type: NonClustered,
                        parts: vec![
                            IndexPart { column: "AddressLine1", order: Ascending },
                            IndexPart { column: "AddressLine2", order: Ascending },
                            IndexPart { column: "City", order: Ascending },
                            IndexPart { column: "StateProvince", order: Ascending },
                            IndexPart { column: "PostalCode", order: Ascending },
                            IndexPart { column: "CountryRegion", order: Ascending },
                        ],
                    },
                    IndexInfo {
                        is_primary_key: false,
                        is_unique: false,
                        name: "IX_Address_StateProvince",
                        index_type: NonClustered,
                        parts: vec![
                            IndexPart { column: "StateProvince", order: Ascending },
                        ],
                    },
                    IndexInfo {
                        is_primary_key: true,
                        is_unique: true,
                        name: "PK_Address_AddressID",
                        index_type: Clustered,
                        parts: vec![
                            IndexPart { column: "AddressID", order: Ascending },
                        ],
                    },
                ],
                foreign_keys: vec![],
                comment: Some("Street address information for customers."),
            },
            // ...
        ],
    }
);

§Entity Generation

# Generate entity file from database schema
$ sea-orm-cli generate entity --database-url "mssql://sa:YourStrong()Passw0rd@localhost/AdventureWorksLT2016" --database-schema "SalesLT"

Connecting to MSSQL ...
Discovering schema ...
... discovered.
Generating address.rs
    > Column `AddressID`: i32, auto_increment, not_null
    > Column `AddressLine1`: String, not_null
    > Column `AddressLine2`: Option<String>
    > Column `City`: String, not_null
    > Column `StateProvince`: String, not_null
    > Column `CountryRegion`: String, not_null
    > Column `PostalCode`: String, not_null
    > Column `rowguid`: Uuid, not_null, unique
    > Column `ModifiedDate`: DateTime, not_null
...


# Inside the generated entity file
$ cat address.rs

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

#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Eq)]
#[sea_orm(schema_name = "SalesLT", table_name = "Address")]
pub struct Model {
    #[sea_orm(column_name = "AddressID", primary_key)]
    pub address_id: i32,
    #[sea_orm(column_name = "AddressLine1")]
    pub address_line1: String,
    #[sea_orm(column_name = "AddressLine2")]
    pub address_line2: Option<String>,
    #[sea_orm(column_name = "City")]
    pub city: String,
    #[sea_orm(column_name = "StateProvince")]
    pub state_province: String,
    #[sea_orm(column_name = "CountryRegion")]
    pub country_region: String,
    #[sea_orm(column_name = "PostalCode")]
    pub postal_code: String,
    #[sea_orm(unique)]
    pub rowguid: Uuid,
    #[sea_orm(column_name = "ModifiedDate")]
    pub modified_date: DateTime,
}

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

impl ActiveModelBehavior for ActiveModel {}

Let’s have a quick walk through of the unique features of SeaORM.

§Expressive Entity format

You don’t have to write this by hand! Entity files can be generated from an existing database using sea-orm-cli, following is generated with --entity-format dense (new in 2.0).

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>,
    }
}
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,
        #[sea_orm(belongs_to, from = "user_id", to = "id")]
        pub author: HasOne<super::user::Entity>,
        #[sea_orm(has_many, via = "post_tag")] // M-N relation with junction
        pub tags: HasMany<super::tag::Entity>,
    }
}

§Smart Entity Loader

The Entity Loader intelligently uses join for 1-1 and data loader for 1-N relations, eliminating the N+1 problem even when performing nested queries.

// join paths:
// user -> profile
// user -> post
//         post -> post_tag -> tag
let smart_user = user::Entity::load()
    .filter_by_id(42) // shorthand for .filter(user::COLUMN.id.eq(42))
    .with(profile::Entity) // 1-1 uses join
    .with((post::Entity, tag::Entity)) // 1-N uses data loader
    .one(db)
    .await?
    .unwrap();

// 3 queries are executed under the hood:
// 1. SELECT FROM user JOIN profile WHERE id = $
// 2. SELECT FROM post WHERE user_id IN (..)
// 3. SELECT FROM tag JOIN post_tag WHERE post_id IN (..)

smart_user
    == user::ModelEx {
        id: 42,
        name: "Bob".into(),
        email: "bob@sea-ql.org".into(),
        profile: HasOne::Loaded(
            profile::ModelEx {
                picture: "image.jpg".into(),
            }
            .into(),
        ),
        posts: HasMany::Loaded(vec![post::ModelEx {
            title: "Nice weather".into(),
            tags: HasMany::Loaded(vec![tag::ModelEx {
                tag: "sunny".into(),
            }]),
        }]),
    };

§ActiveModel: nested persistence made simple

Persist an entire object graph: user, profile (1-1), posts (1-N), and tags (M-N) in a single operation using a fluent builder API. SeaORM automatically determines the dependencies and inserts or deletes objects in the correct order.

// this creates the nested object as shown above:
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?;

§Schema first or Entity first? Your choice

SeaORM provides a powerful migration system that lets you create tables, modify schemas, and seed data with ease.

With SeaORM 2.0, you also get a first-class Entity First Workflow: simply define new entities or add columns to existing ones, and SeaORM will automatically detect the changes and create the new tables, columns, unique keys, and foreign keys.

// SeaORM resolves foreign key dependencies and creates the tables in topological order.
// Requires the `entity-registry` and `schema-sync` feature flags.
db.get_schema_registry("my_crate::entity::*").sync(db).await;

§Ergonomic Raw SQL

Let SeaORM handle 95% of your transactional queries. For the remaining cases that are too complex to express, SeaORM still offers convenient support for writing raw SQL.

let user = Item { name: "Bob" }; // nested parameter access
let ids = [2, 3, 4]; // expanded by the `..` operator

let user: Option<user::Model> = user::Entity::find()
    .from_raw_sql(raw_sql!(
        Sqlite,
        r#"SELECT "id", "name" FROM "user"
           WHERE "name" LIKE {user.name}
           AND "id" in ({..ids})
        "#
    ))
    .one(db)
    .await?;

§Basics

§Select

SeaORM models 1-N and M-N relationships at the Entity level, letting you traverse many-to-many links through a junction table in a single call.

// find all models
let cakes: Vec<cake::Model> = Cake::find().all(db).await?;

// find and filter
let chocolate: Vec<cake::Model> = Cake::find()
    .filter(Cake::COLUMN.name.contains("chocolate"))
    .all(db)
    .await?;

// find one model
let cheese: Option<cake::Model> = Cake::find_by_id(1).one(db).await?;
let cheese: cake::Model = cheese.unwrap();

// find related models (lazy)
let fruit: Option<fruit::Model> = cheese.find_related(Fruit).one(db).await?;

// find related models (eager): for 1-1 relations
let cake_with_fruit: Vec<(cake::Model, Option<fruit::Model>)> =
    Cake::find().find_also_related(Fruit).all(db).await?;

// find related models (eager): works for both 1-N and M-N relations
let cake_with_fillings: Vec<(cake::Model, Vec<filling::Model>)> = Cake::find()
    .find_with_related(Filling) // for M-N relations, two joins are performed
    .all(db) // rows are automatically consolidated by left entity
    .await?;

§Nested Select

Partial models prevent overfetching by letting you querying only the fields you need; it also makes writing deeply nested relational queries simple.

use sea_orm::DerivePartialModel;

#[derive(DerivePartialModel)]
#[sea_orm(entity = "cake::Entity")]
struct CakeWithFruit {
    id: i32,
    name: String,
    #[sea_orm(nested)]
    fruit: Option<fruit::Model>, // this can be a regular or another partial model
}

let cakes: Vec<CakeWithFruit> = Cake::find()
    .left_join(fruit::Entity) // no need to specify join condition
    .into_partial_model() // only the columns in the partial model will be selected
    .all(db)
    .await?;

§Insert

SeaORM’s ActiveModel lets you work directly with Rust data structures and persist them through a simple API. It’s easy to insert large batches of rows from different data sources.

let apple = fruit::ActiveModel {
    name: Set("Apple".to_owned()),
    ..Default::default() // no need to set primary key
};

let pear = fruit::ActiveModel {
    name: Set("Pear".to_owned()),
    ..Default::default()
};

// insert one: Active Record style
let apple = apple.insert(db).await?;
apple.id == 1;

// insert one: repository style
let result = Fruit::insert(apple).exec(db).await?;
result.last_insert_id == 1;

// insert many returning last insert id
let result = Fruit::insert_many([apple, pear]).exec(db).await?;
result.last_insert_id == Some(2);

§Insert (advanced)

You can take advantage of database specific features to perform upsert and idempotent insert.

// insert many with returning (if supported by database)
let models: Vec<fruit::Model> = Fruit::insert_many([apple, pear])
    .exec_with_returning(db)
    .await?;
models[0]
    == fruit::Model {
        id: 1, // database assigned value
        name: "Apple".to_owned(),
        cake_id: None,
    };

// insert with ON CONFLICT on primary key do nothing, with MySQL specific polyfill
let result = Fruit::insert_many([apple, pear])
    .on_conflict_do_nothing()
    .exec(db)
    .await?;

matches!(result, TryInsertResult::Conflicted);

§Update

ActiveModel avoids race conditions by updating only the fields you’ve changed, never overwriting untouched columns. You can also craft complex bulk update queries with a fluent query building API.

use sea_orm::sea_query::{Expr, Value};

let pear: Option<fruit::Model> = Fruit::find_by_id(1).one(db).await?;
let mut pear: fruit::ActiveModel = pear.unwrap().into();

pear.name = Set("Sweet pear".to_owned()); // update value of a single field

// update one: only changed columns will be updated
let pear: fruit::Model = pear.update(db).await?;

// update many: UPDATE "fruit" SET "cake_id" = "cake_id" + 2
//               WHERE "fruit"."name" LIKE '%Apple%'
Fruit::update_many()
    .col_expr(fruit::COLUMN.cake_id, fruit::COLUMN.cake_id.add(2))
    .filter(fruit::COLUMN.name.contains("Apple"))
    .exec(db)
    .await?;

§Save

You can perform “insert or update” operation with ActiveModel, making it easy to compose transactional operations.

let banana = fruit::ActiveModel {
    id: NotSet,
    name: Set("Banana".to_owned()),
    ..Default::default()
};

// create, because primary key `id` is `NotSet`
let mut banana = banana.save(db).await?;

banana.id == Unchanged(2);
banana.name = Set("Banana Mongo".to_owned());

// update, because primary key `id` is present
let banana = banana.save(db).await?;

§Delete

The same ActiveModel API consistent with insert and update.

// delete one: Active Record style
let orange: Option<fruit::Model> = Fruit::find_by_id(1).one(db).await?;
let orange: fruit::Model = orange.unwrap();
orange.delete(db).await?;

// delete one: repository style
let orange = fruit::ActiveModel {
    id: Set(2),
    ..Default::default()
};
fruit::Entity::delete(orange).exec(db).await?;

// delete many: DELETE FROM "fruit" WHERE "fruit"."name" LIKE '%Orange%'
fruit::Entity::delete_many()
    .filter(fruit::COLUMN.name.contains("Orange"))
    .exec(db)
    .await?;

§Raw SQL Query

The raw_sql! macro is like the format! macro but without the risk of SQL injection. It supports nested parameter interpolation, array and tuple expansion, and even repeating group, offering great flexibility in crafting complex queries.

#[derive(FromQueryResult)]
struct CakeWithBakery {
    name: String,
    #[sea_orm(nested)]
    bakery: Option<Bakery>,
}

#[derive(FromQueryResult)]
struct Bakery {
    #[sea_orm(alias = "bakery_name")]
    name: String,
}

let cake_ids = [2, 3, 4]; // expanded by the `..` operator

// can use many APIs with raw SQL, including nested select
let cake: Option<CakeWithBakery> = CakeWithBakery::find_by_statement(raw_sql!(
    Sqlite,
    r#"SELECT "cake"."name", "bakery"."name" AS "bakery_name"
       FROM "cake"
       LEFT JOIN "bakery" ON "cake"."bakery_id" = "bakery"."id"
       WHERE "cake"."id" IN ({..cake_ids})"#
))
.one(db)
.await?;

§Nested Transaction

assert_eq!(Bakery::find().all(txn).await?.len(), 0);

ctx.db
    .transaction::<_, _, DbErr>(|txn| {
        Box::pin(async move {
            let _ = bakery::ActiveModel { .. }.save(txn).await?;
            let _ = bakery::ActiveModel { .. }.save(txn).await?;
            assert_eq!(Bakery::find().all(txn).await?.len(), 2);

            // Try nested transaction committed
            txn.transaction::<_, _, DbErr>(|txn| {
                Box::pin(async move {
                    let _ = bakery::ActiveModel { .. }.save(txn).await?;
                    assert_eq!(Bakery::find().all(txn).await?.len(), 3);

                    // Try nested-nested transaction rollbacked
                    assert!(txn
                        .transaction::<_, _, DbErr>(|txn| {
                            Box::pin(async move {
                                let _ = bakery::ActiveModel { .. }.save(txn).await?;
                                assert_eq!(Bakery::find().all(txn).await?.len(), 4);

                                Err(DbErr::Query(RuntimeErr::Internal(
                                    "Force Rollback!".to_owned(),
                                )))
                            })
                        })
                        .await
                        .is_err());

                    assert_eq!(Bakery::find().all(txn).await?.len(), 3);

                    // Try nested-nested transaction committed
                    txn.transaction::<_, _, DbErr>(|txn| {
                        Box::pin(async move {
                            let _ = bakery::ActiveModel { .. }.save(txn).await?;
                            assert_eq!(Bakery::find().all(txn).await?.len(), 4);

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

                    assert_eq!(Bakery::find().all(txn).await?.len(), 4);

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

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

assert_eq!(Bakery::find().all(txn).await?.len(), 4);

§🧭 Seaography: instant GraphQL API

Seaography is a GraphQL framework built for SeaORM. Seaography allows you to build GraphQL resolvers quickly. With just a few commands, you can launch a fullly-featured GraphQL server from SeaORM entities, complete with filter, pagination, relational queries and mutations!

Look at the Seaography Example to learn more.

§🖥️ 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)

Read the Getting Started guide to learn more.

§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.

§Releases

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.

Change Log

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.

If you make extensive use of SeaQuery, we recommend checking out our blog post on SeaQuery 1.0 release:

The road to SeaQuery 1.0

Re-exports§

pub use crate::error::TryGetError;
pub use sea_query;
pub use strum;
pub use sqlx;
pub use sqlz;
pub use entity::*;
pub use error::*;
pub use query::*;
pub use schema::*;

Modules§

dynamic: The API of this module is not yet stable, and may have breaking changes between minor versions.
entity: Module for the Entity type and operations
error: Error types for all database operations
metric: Types and methods to perform metric collection
query: Types and methods to perform queries
schema: Types that defines the schemas of an Entity
value: Helpers for working with Value

Macros§

debug_print: Non-debug version
debug_query: Helper to get a raw SQL string from an object that impl QueryTrait.
debug_query_stmt: Helper to get a Statement from an object that impl QueryTrait.
raw_sql

Structs§

ConnectOptions: Defines the configuration options of a database
Cursor: Cursor pagination
Database: Defines a database
DatabaseConnection: Handle a database connection depending on the backend enabled by the feature flags. This creates a connection pool internally (for SQLx connections), and so is cheap to clone.
DatabaseTransaction: Defines a database transaction, whether it is an open transaction and the type of backend to use. Under the hood, a Transaction is just a wrapper for a connection where START TRANSACTION has been executed.
DeleteResult: The result of a DELETE operation
Deleter: Handles DELETE operations in a ActiveModel using DeleteStatement
ExecResult: Defines the result of executing an operation
InsertManyResult: The result of an INSERT many operation for a set of ActiveModels
InsertResult: The result of an INSERT operation on an ActiveModel
Inserter: Defines a structure to perform INSERT operations in an ActiveModel
ItemsAndPagesNumber: Define a structure containing the numbers of items and pages of a Paginator
MockDatabase: Defines a Mock database suitable for testing
MockDatabaseConnection: Defines a connection for the MockDatabase
MockDatabaseConnector: Defines a database driver for the MockDatabase
MockExecResult: Defines the results obtained from a MockDatabase
MockRow: Defines the structure of a test Row for the MockDatabase which is just a BTreeMap<String, Value>
OpenTransaction: Defines a transaction that is has not been committed
Paginator: Defined a structure to handle pagination of a result from a query operation on a Model
ProxyDatabaseConnection: Defines a connection for the [ProxyDatabase]
ProxyDatabaseConnector: Defines a database driver for the [ProxyDatabase]
ProxyExecResult: Defines the results obtained from a [ProxyDatabase]
ProxyRow: Defines the structure of a Row for the [ProxyDatabase] which is just a BTreeMap<String, Value>
QueryResult: Defines the result of a query operation on a Model
QueryStream: The self-referencing struct.
SelectFiveModel: Helper class to handle query result for 5 Models
SelectFourModel: Helper class to handle query result for 4 Models
SelectGetableTuple: Get tuple from query result based on column index
SelectGetableValue: Get tuple from query result based on a list of column identifiers
SelectModel: Helper class to handle query result for 1 Model
SelectSixModel: Helper class to handle query result for 6 Models
SelectThreeModel: Helper class to handle query result for 3 Models
SelectTwoModel: Helper class to handle query result for 2 Models
Selector: Defines a type to do SELECT operations through a SelectStatement on a Model
SelectorRaw: Performs a raw SELECT operation on a model
SqlxMySqlConnector: Defines the sqlx::mysql connector
SqlxMySqlPoolConnection: Defines a sqlx MySQL pool
SqlxPostgresConnector: Defines the sqlx::postgres connector
SqlxPostgresPoolConnection: Defines a sqlx PostgreSQL pool
SqlxSqliteConnector: Defines the sqlx::sqlite connector
SqlxSqlitePoolConnection: Defines a sqlx SQLite pool
SqlzMsSqlConnector: Defines the sqlz::mssql connector
SqlzMsSqlPoolConnection: Defines a sqlz MSSQL pool
Statement: Defines an SQL statement
Transaction: Defines a database transaction as it holds a Vec<Statement>
TransactionStream: The self-referencing struct.
UpdateResult: The result of an update operation on an ActiveModel
Updater: Defines an update operation
Values

Enums§

AccessMode: Access mode
DatabaseBackend: The type of database backend for real world databases. This is enabled by feature flags as specified in the crate documentation
DatabaseConnectionType: The underlying database connection type.
DatabaseExecutor: A wrapper that holds either a reference to a DatabaseConnection or DatabaseTransaction.
IsolationLevel: Isolation level
TransactionError: Defines errors for handling transaction failures
TryInsertResult: The result of executing a crate::TryInsert.
Value: Value variants

Traits§

ColIdx: Column Index, used by TryGetable. Implemented for &str and usize
ConnectionTrait: The generic API for a database connection that can perform query or execute statements. It abstracts database connection and transaction
CursorTrait: A trait for any type that can be turn into a cursor
Iden: Identifier
IntoDatabaseExecutor: A trait for converting into DatabaseExecutor
IntoMockRow: A trait to get a MockRow from a type useful for testing in the MockDatabase
MockDatabaseTrait: A Trait for any type wanting to perform operations on the MockDatabase
PaginatorTrait: A Trait for any type that can paginate results
ProxyDatabaseTrait: Defines the ProxyDatabaseTrait to save the functions
SelectExt: Helper trait for selectors with convenient methods
SelectorTrait: A Trait for any type that can perform SELECT queries
StatementBuilder: Any type that can build a Statement
StreamTrait: Stream query results
TransactionSession: Represents an open transaction
TransactionTrait: Spawn database transaction
TryFromU64: Try to convert a type to a u64
TryGetable: An interface to get a value from the query result
TryGetableArray: An interface to get an array of values from the query result. A type can only implement ActiveEnum or TryGetableFromJson, but not both. A blanket impl is provided for TryGetableFromJson, while the impl for ActiveEnum is provided by the DeriveActiveEnum macro. So as an end user you won’t normally touch this trait.
TryGetableFromJson: An interface to get a JSON from the query result
TryGetableMany: An interface to get a tuple value from the query result

Functions§

from_query_result_to_proxy_row: Convert QueryResult to ProxyRow
sqlz_conn_acquire_err: Converts an sqlz::error error to a DbErr
sqlz_error_to_conn_err: Converts an sqlz::error connection error to a DbErr
sqlz_error_to_exec_err: Converts an sqlz::error execution error to a DbErr
sqlz_error_to_query_err: Converts an sqlz::error query error to a DbErr
sqlz_map_err_ignore_not_found: Converts an sqlz::error error to a DbErr

Type Aliases§

DbBackend: A shorthand for DatabaseBackend.
DbConn: The same as a DatabaseConnection

Attribute Macros§

compact_model
model

Derive Macros§

DeriveActiveEnum: A derive macro to implement sea_orm::ActiveEnum trait for enums.
DeriveActiveModel: The DeriveActiveModel derive macro will implement ActiveModelTrait for ActiveModel which provides setters and getters for all active values in the active model.
DeriveActiveModelBehavior: Models that a user can override
DeriveActiveModelEx: Derive a complex active model with relational fields
DeriveColumn: The DeriveColumn derive macro will implement [ColumnTrait] for Columns. It defines the identifier of each column by implementing Iden and IdenStatic. The EnumIter is also derived, allowing iteration over all enum variants.
DeriveDisplay
DeriveEntity: Create an Entity
DeriveEntityModel: This derive macro is the ‘almighty’ macro which automatically generates Entity, Column, and PrimaryKey from a given Model.
DeriveIden: The DeriveIden derive macro will implement sea_orm::Iden for simplify Iden implementation.
DeriveIntoActiveModel: Derive into an active model
DeriveMigrationName: The DeriveMigrationName derive macro will implement sea_orm_migration::MigrationName for a migration.
DeriveModel: The DeriveModel derive macro will implement ModelTrait for Model, which provides setters and getters for all attributes in the mod It also implements FromQueryResult to convert a query result into the corresponding Model.
DeriveModelEx: Derive a complex model with relational fields
DerivePartialModel: The DerivePartialModel derive macro will implement [sea_orm::PartialModelTrait] for simplify partial model queries. Since 2.0, this macro cannot be used with the FromQueryResult macro.
DerivePrimaryKey: The DerivePrimaryKey derive macro will implement [PrimaryKeyToColumn] for PrimaryKey which defines tedious mappings between primary keys and columns. The EnumIter is also derived, allowing iteration over all enum variants.
DeriveRelatedEntity: The DeriveRelatedEntity derive macro will implement seaography::RelationBuilder for RelatedEntity enumeration.
DeriveRelation: The DeriveRelation derive macro will implement RelationTrait for Relation.
DeriveValueType: Implements traits for types that wrap a database value type.
EnumIter: Creates a new type that iterates of the variants of an enum.
FromJsonQueryResult
FromQueryResult: Convert a query result into the corresponding Model.

Crate sea_orm

Crate sea_orm Copy item path

SeaORM is a powerful ORM for building web services in Rust

§🐚 SeaORM

§Advanced Relations

§Familiar Concepts

§Feature Rich

§Production Ready

§Getting Started

§Installation

§Local Dependency

§Git Dependency

§Troubleshooting Git Authentication Errors

§Quick Start

§Connection

§Query Builder

§Schema Discovery

§Entity Generation

§Expressive Entity format

§Smart Entity Loader

§ActiveModel: nested persistence made simple

§Schema first or Entity first? Your choice

§Ergonomic Raw SQL

§Basics

§Select

§Nested Select

§Insert

§Insert (advanced)

§Update

§Save

§Delete

§Raw SQL Query

§Nested Transaction

§🧭 Seaography: instant GraphQL API

§🖥️ SeaORM Pro: Professional Admin Panel

§SQL Server Support

§Releases

Re-exports§

Modules§

Macros§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Derive Macros§

Crate sea_orm