logo
Expand description

SeaORM

🐚 An async & dynamic ORM for Rust

crate docs build status

SeaORM

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

Getting Started

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

Discord Join our Discord server to chat with others in the SeaQL community!

Integration examples

Features

  1. Async

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

  2. Dynamic

    Built upon SeaQuery, SeaORM allows you to build complex queries without ‘fighting the ORM’.

  3. Testable

    Use mock connections to write unit tests for your logic.

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

  1. Design
  2. Architecture
  3. Release Model
  4. Change Log

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

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.

Re-exports

pub use entity::*;
pub use error::*;
pub use query::*;
pub use schema::*;
pub use sea_query;
pub use strum;

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

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 impl QueryTrait.

Structs

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

The result of a DELETE operation

Handles DELETE operations in a ActiveModel using DeleteStatement

Defines the result of executing an operation

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

Defines a Mock database suitable for testing

Defines a connection for the MockDatabase

Defines a database driver for the MockDatabase

Defines the results obtained from a MockDatabase

Defines the structure of a test Row for the MockDatabase which is just a BTreeMap<String, Value>

Defines a transaction that is has not been committed

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.

Perform an operation on an entity that can yield a Value

Defines a type to get a Model

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 the [sqlx::postgres] connector

Defines a sqlx PostgreSQL pool

Defines the [sqlx::sqlite] connector

Defines a sqlx SQLite pool

Defines an SQL statement

Defines a database transaction as it holds a Vec<Statement>

The self-referencing struct.

The result of an update operation on an ActiveModel

Defines an update operation

Enums

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.

Defines errors for handling transaction failures

An error from trying to get a row from a Model

Value variants

Traits

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

Identifier

A trait to get a MockRow from a type useful for testing in the MockDatabase

A Trait for any type wanting to perform operations on the MockDatabase

A Trait for any type that can paginate results

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

Perform a query on multiple columns

Functions

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

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.