Crate sea_orm

Expand description

SeaORM

🐚 An async & dynamic ORM for Rust

§SeaORM

§SeaORM is a relational ORM to help you build web services in Rust with the familiarity of dynamic languages.

If you like what we do, consider starring, sharing and contributing!

Please help us with maintaining SeaORM by completing the SeaQL Community Survey 2024!

Join our Discord server to chat with other members of the SeaQL community!

§Getting Started

Integration examples:

§Features

Async

Relying on SQLx, SeaORM is a new library with async support from day 1.
Dynamic

Built upon SeaQuery, SeaORM allows you to build complex dynamic queries.
Service Oriented

Quickly build services that join, filter, sort and paginate data in REST, GraphQL and gRPC APIs.
Production Ready

SeaORM is feature-rich, well-tested and used in production by companies and startups.

§A quick taste of SeaORM

§Entity

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

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

#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
pub enum Relation {
    #[sea_orm(has_many = "super::fruit::Entity")]
    Fruit,
}

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

§Select

// 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 fruits: Vec<fruit::Model> = cheese.find_related(Fruit).all(db).await?;

// find related models (eager)
let cake_with_fruits: Vec<(cake::Model, Vec<fruit::Model>)> =
    Cake::find().find_with_related(Fruit).all(db).await?;

§Insert

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
let pear = pear.insert(db).await?;

// insert many
Fruit::insert_many([apple, pear]).exec(db).await?;

§Update

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 one
let pear: fruit::Model = pear.update(db).await?;

// update many: UPDATE "fruit" SET "cake_id" = NULL WHERE "fruit"."name" LIKE '%Apple%'
Fruit::update_many()
    .col_expr(fruit::Column::CakeId, Expr::value(Value::Int(None)))
    .filter(fruit::Column::Name.contains("Apple"))
    .exec(db)
    .await?;

§Save

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.name = Set("Banana Mongo".to_owned());

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

§Delete

// delete one
let orange: Option<fruit::Model> = Fruit::find_by_id(1).one(db).await?;
let orange: fruit::Model = orange.unwrap();
fruit::Entity::delete(orange.into_active_model())
    .exec(db)
    .await?;

// or simply
let orange: Option<fruit::Model> = Fruit::find_by_id(1).one(db).await?;
let orange: fruit::Model = orange.unwrap();
orange.delete(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?;

§🧭 Seaography: instant GraphQL API

Seaography is a GraphQL framework built on top of SeaORM. Seaography allows you to build GraphQL resolvers quickly. With just a few commands, you can launch a GraphQL server from SeaORM entities!

Look at the Seaography Example to learn more.

§🖥️ SeaORM Pro: Effortless 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 simple TOML

Learn More

§Releases

SeaORM 1.0 is a stable release. The 1.x version will be updated until at least October 2025, and we’ll decide whether to release a 2.0 version or extend the 1.x life cycle.

It doesn’t mean that SeaORM is ‘done’, we’ve designed an architecture to allow us to deliver new features without major breaking changes. In fact, more features are coming!

Change Log

§Who’s using SeaORM?

Here is a short list of awesome open source software built with SeaORM. Full list here. Feel free to submit yours!

Project	GitHub	Tagline
Zed		A high-performance, multiplayer code editor
OpenObserve		Open-source observability platform
RisingWave		Stream processing and management platform
LLDAP		A light LDAP server for user management
Warpgate		Smart SSH bastion that works with any SSH client
Svix		The enterprise ready webhooks service
Ryot		The only self hosted tracker you will ever need
Lapdev		Self-hosted remote development enviroment
System Initiative		DevOps Automation Platform
OctoBase		A light-weight, scalable, offline collaborative data backend

§License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

We invite you to participate, contribute and together help build Rust’s future.

A big shout out to our contributors!

§Sponsorship

SeaQL.org is an independent open-source organization run by passionate developers. If you enjoy using our libraries, please star and share our repositories. If you feel generous, a small donation via GitHub Sponsor will be greatly appreciated, and goes a long way towards sustaining the organization.

§Silver Sponsors

We’re immensely grateful to our sponsors: Digital Ocean, for sponsoring our servers. And JetBrains, for sponsoring our IDE.

§Mascot

A friend of Ferris, Terres the hermit crab is the official mascot of SeaORM. His hobby is collecting shells.

Modules§

entity: Module for the Entity type and operations
error: Error types for all database operations
metric: Holds types and methods to perform metric collection
query: Holds types and methods to perform queries
schema: Holds types that defines the schemas of an Entity
sea_query
sqlx: The async SQL toolkit for Rust, built with ❤️ by the LaunchBadge team.
strum: Strum

Macros§

debug_print: Uses the log crate to perform logging. This must be enabled using the feature flag debug-print.
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.

Structs§

ColumnDef: Defines a Column for an Entity
ColumnFromStrErr: Error during impl FromStr for Entity::Column
Condition: Represents the value of an Condition::any or Condition::all: a set of disjunctive or conjunctive conditions.
ConnectOptions: Defines the configuration options of a database
Cursor: Cursor pagination
Database: Defines a database
DatabaseTransaction: Defines a database transaction, whether it is an open transaction and the type of backend to use
DebugQuery: This structure provides debug capabilities
Delete: Defines the structure for a delete operation
DeleteMany: Perform a delete operation on multiple models
DeleteOne: Perform a delete operation on a model
DeleteResult: The result of a DELETE operation
Deleter: Handles DELETE operations in a ActiveModel using DeleteStatement
ExecResult: Defines the result of executing an operation
Insert: Performs INSERT operations on a ActiveModel
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
Paginator: Defined a structure to handle pagination of a result from a query operation on a Model
QueryResult: Defines the result of a query operation on a Model
QueryStream: The self-referencing struct.
RelationBuilder: Defines a helper to build a relation
RelationDef: Defines a relationship
Schema: This is a helper struct to convert EntityTrait into different sea_query statements.
Select: Defines a structure to perform select operations
SelectA: Implements the traits Iden and IdenStatic for a type
SelectB: Implements the traits Iden and IdenStatic for a type
SelectC: Implements the traits Iden and IdenStatic for a type
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
SelectThree: Defines a structure to perform a SELECT operation on two Models
SelectThreeModel: Helper class to handle query result for 3 Models
SelectTwo: Defines a structure to perform a SELECT operation on two Models
SelectTwoMany: Defines a structure to perform a SELECT operation on many 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
SqlxSqliteConnector: Defines the sqlx::sqlite connector
SqlxSqliteError
SqlxSqlitePoolConnection: Defines a sqlx SQLite pool
Statement: Defines an SQL statement
TransactionStream: The self-referencing struct.
TryInsert: Performs INSERT operations on a ActiveModel, will do nothing if input is empty.
Update: Defines a structure to perform UPDATE query operations on a ActiveModel
UpdateMany: Defines an UPDATE operation on multiple ActiveModels
UpdateOne: Defines an UPDATE operation on one ActiveModel
UpdateResult: The result of an update operation on an ActiveModel
Updater: Defines an update operation
Values

Enums§

AccessMode: Access mode
ActiveValue: Defines a stateful value used in ActiveModel.
ColumnType: All column types
ConnAcquireErr: Connection Acquire error
DatabaseBackend: The type of database backend for real world databases. This is enabled by feature flags as specified in the crate documentation
DatabaseConnection: Handle a database connection depending on the backend enabled by the feature flags. This creates a database pool. This will be Clone unless the feature flag mock is enabled.
DbErr: An error from unsuccessful database operations
Identity: List of column identifier
IsolationLevel: Isolation level
JoinType: Join types
JsonValue: Represents any valid JSON value.
Order: Ordering options
RelationType: Defines the type of relationship
RuntimeErr: Runtime error
SqlErr: An error from unsuccessful SQL query
SqlxError: Represents all the ways a method can fail within SQLx.
TransactionError: Defines errors for handling transaction failures
TryGetError: An error from trying to get a row from a Model
TryInsertResult: The types of results for an INSERT operation
Value: Value variants

Traits§

ActiveEnum: A Rust representation of enum defined in database.
ActiveEnumValue: The Rust Value backing ActiveEnums
ActiveModelBehavior: A Trait for overriding the ActiveModel behavior
ActiveModelTrait: A Trait for ActiveModel to perform Create, Update or Delete operation. The type must also implement the EntityTrait. See module level docs crate::entity for a full example
ColIdx: Column Index, used by TryGetable. Implemented for &str and usize
ColumnTrait: API for working with a Column. Mostly a wrapper of the identically named methods in sea_query::Expr
ColumnTypeTrait: SeaORM’s utility methods that act on ColumnType
ConditionalStatement
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
EntityName: A Trait for mapping an Entity to a database table
EntityOrSelect: Entity, or a Select; to be used as parameters in LoaderTrait
EntityTrait: An abstract base class for defining Entities.
FromQueryResult: A Trait for implementing a QueryResult
Iden: Identifier
IdenStatic: Ensure the identifier for an Entity can be converted to a static str
IdentityOf: Check the Identity of an Entity
IntoActiveModel: A Trait for any type that can be converted into an ActiveModel
IntoActiveValue: Any type that can be converted into an ActiveValue
IntoIdentity: Performs a conversion into an Identity
IntoSimpleExpr: Performs a conversion to SimpleExpr
Iterable: This trait designates that an Enum can be iterated over. It can be auto generated using the EnumIter derive macro.
Linked: A Trait for links between Entities
LoaderTrait: This trait implements the Data Loader API
ModelTrait: The interface for Model, implemented by data structs
OrderedStatement
PaginatorTrait: A Trait for any type that can paginate results
PartialModelTrait: A trait for a part of Model
PrimaryKeyArity: How many columns this Primary Key comprises
PrimaryKeyToColumn: How to map a Primary Key to a column
PrimaryKeyTrait: A Trait for to be used to define a Primary Key.
QueryFilter: Perform a FILTER opertation on a statement
QueryOrder: Performs ORDER BY operations
QuerySelect: Abstract API for performing queries
QueryTrait: A Trait for any type performing queries on a Model or ActiveModel
Related: Checks if Entities are related
RelationTrait: Defines the relations of an Entity
SelectColumns: Select specific column for partial model queries
SelectorTrait: A Trait for any type that can perform SELECT queries
StatementBuilder: Any type that can build a Statement
StreamTrait: Stream query results
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
TryIntoModel: A Trait for any type that can be converted into an Model

Functions§

UnsetDeprecated: Defines an not set operation on an ActiveValue

Type Aliases§

DbBackend: The same as DatabaseBackend just shorter :)
DbConn: The same as a DatabaseConnection
DynIden
ForeignKeyAction: Action to perform on a foreign key whenever there are changes to an ActiveModel
LinkDef: Same as RelationDef
PinBoxStream: Pin a Model so that stream operations can be performed on the 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
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.
DeriveCustomColumn: Derive a column if column names are not in snake-case
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::sea_query::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.
DerivePartialModel: The DerivePartialModel derive macro will implement [sea_orm::PartialModelTrait] for simplify partial model queries.
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.
Iden

Crate sea_ormCopy item path