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.
Getting Started
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
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.
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
Macros
Uses the log crate to perform logging.
This must be enabled using the feature flag debug-print.
Helper to get a raw SQL string from an object that impl QueryTrait.
Helper to get a Statement from an object that impl QueryTrait.
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 or Condition::all: a set of disjunctive or conjunctive conditions.
Defines the configuration options of a database
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
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
Defines a helper to build a relation
Defines a relationship
This is a helper struct to convert EntityTrait
into different sea_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::mysql] connector
Defines a sqlx MySQL pool
Defines an SQL statement
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
Represents any valid JSON value.
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
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 using strum_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
Defines 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 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.