Crate sea_orm

source ¡
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.

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

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

§Getting Started

Integration examples:

§Support

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

Professional support on Rust programming and best practices is available. You can email us for a quote!

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

  3. Testable

    Use mock connections and/or SQLite to write tests for your application logic.

  4. Service Oriented

    Quickly build services that join, filter, sort and paginate data in REST, GraphQL and gRPC 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([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: GraphQL integration (preview)

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!

Starting 0.12, seaography integration is built into sea-orm. While Seaography development is still in an early stage, it is especially useful in prototyping and building internal-use admin panels.

Look at the Seaography Example to learn more.

§Learn More

  1. Design
  2. Architecture
  3. Engineering
  4. Change Log

§Who’s using SeaORM?

See Built with SeaORM. Feel free to submit yours!

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

SeaORM is a community driven project. We welcome you to participate, contribute and together help build Rust’s future.

A big shout out to our contributors!

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.

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

§Gold Sponsors

§Mascot

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

Terres

Re-exports§

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

Macros§

Structs§

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
  • DatabaseConnection
    Handle a database connection depending on the backend enabled by the feature flags. This creates a database pool.
  • IsolationLevel
    Isolation level
  • 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§

Functions§

Type Aliases§

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.