Expand description
SeaORM
SeaORM is a relational ORM to help you build web services in Rust with the familiarity of dynamic languages.
Getting Started
If you like what we do, consider starring, commenting, sharing and contributing!
Join our Discord server to chat with others in the SeaQL community!
Integration examples
- Actix v4 Example
- Actix v3 Example
- Axum Example
- GraphQL Example
- jsonrpsee Example
- Poem Example
- Rocket Example
- Salvo Example
- Tonic Example
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 queries without ‘fighting the ORM’.
-
Testable
Use mock connections to write unit tests for your logic.
-
Service Oriented
Quickly build services that join, filter, sort and paginate data in APIs.
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(vec![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?;
Learn More
Who’s using SeaORM?
The following products are powered by SeaORM:
A lightweight web security auditing toolkit |
A Bitcoin lightning node implementation |
The enterprise ready webhooks service |
SeaORM is the foundation of StarfishQL, an experimental graph database and query engine developed by SeaQL.
For more projects, see Built with SeaORM.
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.
SeaORM is a community driven project. We welcome you to participate, contribute and together build for Rust’s future.
A big shout out to our contributors:
Modules
- Module for the Entity type and operations
- Error types for all database operations
- Holds types and methods to perform metric collection
- Holds types and methods to perform queries
- Holds types that defines the schemas of an Entity
- Strum
Macros
- Non-debug version
- Helper to get a raw SQL string from an object that impl
QueryTrait
. - Helper to get a
Statement
from an object that implQueryTrait
.
Structs
- Defines a Column for an Entity
- An error from a failed column operation when trying to convert the column to a string
- Represents the value of an
Condition::any
orCondition::all
: a set of disjunctive or conjunctive conditions. - Defines the configuration options of a database
- Cursor pagination
- Defines a database
- Defines a database transaction, whether it is an open transaction and the type of backend to use
- This structure provides debug capabilities
- Defines the structure for a delete operation
- Perform a delete operation on multiple models
- Perform a delete operation on a model
- The result of a DELETE operation
- Handles DELETE operations in a ActiveModel using DeleteStatement
- Defines the result of executing an operation
- Performs INSERT operations on a ActiveModel
- The result of an INSERT operation on an ActiveModel
- Defines a structure to perform INSERT operations in an ActiveModel
- Define a structure containing the numbers of items and pages of a Paginator
- Defined a structure to handle pagination of a result from a query operation on a Model
- Defines the result of a query operation on a Model
- The self-referencing struct.
- Defines a helper to build a relation
- Defines a relationship
- This is a helper struct to convert
EntityTrait
into differentsea_query
statements. - Defines a structure to perform select operations
- Implements the traits Iden and IdenStatic for a type
- Implements the traits Iden and IdenStatic for a type
- Perform an operation on an entity that can yield a Value
- Defines a type to get a Model
- Defines a structure to perform a SELECT operation on two Models
- Defines a structure to perform a SELECT operation on many Models
- Defines a type to get two Modelss
- Defines a type to do
SELECT
operations through a SelectStatement on a Model - Performs a raw
SELECT
operation on a model - Defines the [sqlx::sqlite] connector
- Defines a sqlx SQLite pool
- Defines an SQL statement
- The self-referencing struct.
- Defines a structure to perform UPDATE query operations on a ActiveModel
- Defines an UPDATE operation on multiple ActiveModels
- Defines an UPDATE operation on one ActiveModel
- The result of an update operation on an ActiveModel
- Defines an update operation
Enums
- Defines a stateful value used in ActiveModel.
- The type of column as defined in the SQL format
- The type of database backend for real world databases. This is enabled by feature flags as specified in the crate documentation
- Handle a database connection depending on the backend enabled by the feature flags. This creates a database pool.
- An error from unsuccessful database operations
- Defines an operation for an Entity
- Join types
- Ordering options
- Defines the type of relationship
- Defines errors for handling transaction failures
- An error from trying to get a row from a Model
- Value variants
Traits
- A Rust representation of enum defined in database.
- A Trait for overriding the ActiveModel behavior
- 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
- Wrapper of the identically named method in
sea_query::Expr
- Creates constraints for any structure that can create a database connection and execute SQL statements
- A trait for any type that can be turn into a cursor
- Identifier
- A Trait for mapping an Entity to a database table
- An Entity implementing
EntityTrait
represents a table in a database. - A Trait for implementing a QueryResult
- Identifier
- Ensure the identifier for an Entity can be converted to a static str
- Check the Identity of an Entity
- A Trait for any type that can be converted into an ActiveModel
- Constraints to perform the conversion of a type into an ActiveValue
- Performs a conversion into an Identity
- Performs a conversion to SimpleExpr
- This trait designates that an
Enum
can be iterated over. It can be auto generated usingstrum_macros
on your behalf. - A Trait for links between Entities
- A Trait for a Model
- A Trait for any type that can paginate results
- How to map a Primary Key to a column
- A Trait for to be used to define a Primary Key.
- Perform a FILTER opertation on a statement
- Performs ORDER BY operations
- Constraints for any type that needs to perform select statements on a Model
- A Trait for any type performing queries on a Model or ActiveModel
- Checks if Entities are related
- Constraints a type to implement the trait to create a relationship
- A Trait for any type that can perform SELECT queries
- Constraints for building a Statement
- Stream query results
- Spawn database transaction
- Try to convert a type to a u64
- Constrain any type trying to get a Row in a database
- Perform a query on multiple columns
Functions
- Defines a set operation on an ActiveValue
- Defines an unchanged operation on an ActiveValue
- UnsetDeprecatedDefines an not set operation on an ActiveValue
- Converts an [sqlx::error] connection error to a DbErr
- Converts an [sqlx::error] execution error to a DbErr
- Converts an [sqlx::error] query error to a DbErr
Type Definitions
- The same as DatabaseBackend just shorter :)
- The same as a DatabaseConnection
- Action to perform on a foreign key whenever there are changes to an ActiveModel
- Same as RelationDef
- Pin a Model so that stream operations can be performed on the model
Derive Macros
- A derive macro to implement
sea_orm::ActiveEnum
trait for enums. - The DeriveActiveModel derive macro will implement ActiveModelTrait for ActiveModel which provides setters and getters for all active values in the active model.
- Models that a user can override
- 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.
- Derive a column if column names are not in snake-case
- Create an Entity
- This derive macro is the ‘almighty’ macro which automatically generates Entity, Column, and PrimaryKey from a given Model.
- Derive into an active model
- The DeriveMigrationName derive macro will implement
sea_orm_migration::MigrationName
for a migration. - 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.
- 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.
- The DeriveRelation derive macro will implement RelationTrait for Relation.
- Creates a new type that iterates of the variants of an enum.
- Convert a query result into the corresponding Model.