Trait EntityTrait

pub trait EntityTrait: EntityName {
    type Model: ModelTrait<Entity = Self> + FromQueryResult;
    type ActiveModel: ActiveModelBehavior<Entity = Self>;
    type Column: ColumnTrait;
    type Relation: RelationTrait;
    type PrimaryKey: PrimaryKeyTrait + PrimaryKeyToColumn<Column = Self::Column>;

    // Provided methods
    fn belongs_to<R>(related: R) -> RelationBuilder<Self, R>
       where R: EntityTrait { ... }
    fn has_one<R>(_: R) -> RelationBuilder<Self, R>
       where R: EntityTrait + Related<Self> { ... }
    fn has_many<R>(_: R) -> RelationBuilder<Self, R>
       where R: EntityTrait + Related<Self> { ... }
    fn find() -> Select<Self> { ... }
    fn find_by_id<T>(values: T) -> Select<Self>
       where T: Into<<Self::PrimaryKey as PrimaryKeyTrait>::ValueType> { ... }
    fn insert<A>(model: A) -> Insert<A>
       where A: ActiveModelTrait<Entity = Self> { ... }
    fn insert_many<A, I>(models: I) -> Insert<A>
       where A: ActiveModelTrait<Entity = Self>,
             I: IntoIterator<Item = A> { ... }
    fn update<A>(model: A) -> UpdateOne<A>
       where A: ActiveModelTrait<Entity = Self> { ... }
    fn update_many() -> UpdateMany<Self> { ... }
    fn delete<A>(model: A) -> DeleteOne<A>
       where A: ActiveModelTrait<Entity = Self> { ... }
    fn delete_many() -> DeleteMany<Self> { ... }
    fn delete_by_id<T>(values: T) -> DeleteMany<Self>
       where T: Into<<Self::PrimaryKey as PrimaryKeyTrait>::ValueType> { ... }
}

An abstract base class for defining Entities.

This trait provides an API for you to inspect it’s properties

• Column (implemented ColumnTrait)
• Relation (implemented RelationTrait)
• Primary Key (implemented PrimaryKeyTrait and PrimaryKeyToColumn)

This trait also provides an API for CRUD actions

• Select: find, find_*
• Insert: insert, insert_*
• Update: update, update_*
• Delete: delete, delete_*

Required Associated Types

type Model: ModelTrait<Entity = Self> + FromQueryResult

type ActiveModel: ActiveModelBehavior<Entity = Self>

type Column: ColumnTrait

type Relation: RelationTrait

type PrimaryKey: PrimaryKeyTrait + PrimaryKeyToColumn<Column = Self::Column>

Provided Methods

fn belongs_to<R>(related: R) -> RelationBuilder<Self, R>

where R: EntityTrait,

Construct a belongs to relation

fn has_one<R>(_: R) -> RelationBuilder<Self, R>

where R: EntityTrait + Related<Self>,

Construct a has one relation

fn has_many<R>(_: R) -> RelationBuilder<Self, R>

where R: EntityTrait + Related<Self>,

Construct a has many relation

fn find() -> Select<Self>

Construct select statement to find one / all models

• To select columns, join tables and group by expressions, see QuerySelect
• To apply where conditions / filters, see QueryFilter
• To apply order by expressions, see QueryOrder

Example

use sea_orm::{entity::*, query::*, tests_cfg::cake};

assert_eq!(
    cake::Entity::find().one(&db).await?,
    Some(cake::Model {
        id: 1,
        name: "New York Cheese".to_owned(),
    })
);

assert_eq!(
    cake::Entity::find().all(&db).await?,
    [
        cake::Model {
            id: 1,
            name: "New York Cheese".to_owned(),
        },
        cake::Model {
            id: 2,
            name: "Chocolate Forest".to_owned(),
        },
    ]
);

assert_eq!(
    db.into_transaction_log(),
    [
        Transaction::from_sql_and_values(
            DbBackend::Postgres,
            r#"SELECT "cake"."id", "cake"."name" FROM "cake" LIMIT $1"#,
            [1u64.into()]
        ),
        Transaction::from_sql_and_values(
            DbBackend::Postgres,
            r#"SELECT "cake"."id", "cake"."name" FROM "cake""#,
            []
        ),
    ]
);

fn find_by_id<T>(values: T) -> Select<Self>

where T: Into<<Self::PrimaryKey as PrimaryKeyTrait>::ValueType>,

Find a model by primary key

Example

use sea_orm::{entity::*, query::*, tests_cfg::cake};

assert_eq!(
    cake::Entity::find_by_id(11).all(&db).await?,
    [cake::Model {
        id: 11,
        name: "Sponge Cake".to_owned(),
    }]
);

assert_eq!(
    db.into_transaction_log(),
    [Transaction::from_sql_and_values(
        DbBackend::Postgres,
        r#"SELECT "cake"."id", "cake"."name" FROM "cake" WHERE "cake"."id" = $1"#,
        [11i32.into()]
    )]
);

Find by composite key

use sea_orm::{entity::*, query::*, tests_cfg::cake_filling};

assert_eq!(
    cake_filling::Entity::find_by_id((2, 3)).all(&db).await?,
    [cake_filling::Model {
        cake_id: 2,
        filling_id: 3,
    }]
);

assert_eq!(
    db.into_transaction_log(),
    [Transaction::from_sql_and_values(
        DbBackend::Postgres,
        [
            r#"SELECT "cake_filling"."cake_id", "cake_filling"."filling_id" FROM "cake_filling""#,
            r#"WHERE "cake_filling"."cake_id" = $1 AND "cake_filling"."filling_id" = $2"#,
        ].join(" ").as_str(),
        [2i32.into(), 3i32.into()]
    )]);

Panics

Panics if arity of input values don’t match arity of primary key

fn insert<A>(model: A) -> Insert<A>

where A: ActiveModelTrait<Entity = Self>,

Insert a model into database

Example (Postgres)

use sea_orm::{entity::*, query::*, tests_cfg::cake};

let apple = cake::ActiveModel {
    name: Set("Apple Pie".to_owned()),
    ..Default::default()
};

let insert_result = cake::Entity::insert(apple).exec(&db).await?;

assert_eq!(dbg!(insert_result.last_insert_id), 15);

assert_eq!(
    db.into_transaction_log(),
    [Transaction::from_sql_and_values(
        DbBackend::Postgres,
        r#"INSERT INTO "cake" ("name") VALUES ($1) RETURNING "id""#,
        ["Apple Pie".into()]
    )]
);

Example (MySQL)

use sea_orm::{entity::*, query::*, tests_cfg::cake};

let apple = cake::ActiveModel {
    name: Set("Apple Pie".to_owned()),
    ..Default::default()
};

let insert_result = cake::Entity::insert(apple).exec(&db).await?;

assert_eq!(insert_result.last_insert_id, 15);

assert_eq!(
    db.into_transaction_log(),
    [Transaction::from_sql_and_values(
        DbBackend::MySql,
        r#"INSERT INTO `cake` (`name`) VALUES (?)"#,
        ["Apple Pie".into()]
    )]
);

To get back inserted Model

use sea_orm::{entity::*, query::*, tests_cfg::fruit};

assert_eq!(
    cake::Entity::insert(cake::ActiveModel {
        id: NotSet,
        name: Set("Apple Pie".to_owned()),
    })
    .exec_with_returning(&db)
    .await?,
    cake::Model {
        id: 1,
        name: "Apple Pie".to_owned(),
    }
);

assert_eq!(
    db.into_transaction_log()[0].statements()[0].sql,
    r#"INSERT INTO "cake" ("name") VALUES ($1) RETURNING "id", "name""#
);

fn insert_many<A, I>(models: I) -> Insert<A>

where A: ActiveModelTrait<Entity = Self>, I: IntoIterator<Item = A>,

Insert many models into database

Example (Postgres)

use sea_orm::{entity::*, query::*, tests_cfg::cake};

let apple = cake::ActiveModel {
    name: Set("Apple Pie".to_owned()),
    ..Default::default()
};
let orange = cake::ActiveModel {
    name: Set("Orange Scone".to_owned()),
    ..Default::default()
};

let insert_result = cake::Entity::insert_many([apple, orange]).exec(&db).await?;

assert_eq!(insert_result.last_insert_id, 28);

assert_eq!(
    db.into_transaction_log(),
    [Transaction::from_sql_and_values(
        DbBackend::Postgres,
        r#"INSERT INTO "cake" ("name") VALUES ($1), ($2) RETURNING "id""#,
        ["Apple Pie".into(), "Orange Scone".into()]
    )]
);

Example (MySQL)

use sea_orm::{entity::*, query::*, tests_cfg::cake};

let apple = cake::ActiveModel {
    name: Set("Apple Pie".to_owned()),
    ..Default::default()
};
let orange = cake::ActiveModel {
    name: Set("Orange Scone".to_owned()),
    ..Default::default()
};

let insert_result = cake::Entity::insert_many([apple, orange]).exec(&db).await?;

assert_eq!(insert_result.last_insert_id, 28);

assert_eq!(
    db.into_transaction_log(),
    [Transaction::from_sql_and_values(
        DbBackend::MySql,
        r#"INSERT INTO `cake` (`name`) VALUES (?), (?)"#,
        ["Apple Pie".into(), "Orange Scone".into()]
    )]
);

Before 1.1.3, if the active models have different column set, this method would panic. Now, it’d attempt to fill in the missing columns with null (which may or may not be correct, depending on whether the column is nullable):

use sea_orm::{
    entity::*,
    query::*,
    tests_cfg::{cake, cake_filling},
    DbBackend,
};

assert_eq!(
    cake::Entity::insert_many([
        cake::ActiveModel {
            id: NotSet,
            name: Set("Apple Pie".to_owned()),
        },
        cake::ActiveModel {
            id: NotSet,
            name: Set("Orange Scone".to_owned()),
        }
    ])
    .build(DbBackend::Postgres)
    .to_string(),
    r#"INSERT INTO "cake" ("name") VALUES ('Apple Pie'), ('Orange Scone')"#,
);

assert_eq!(
    cake_filling::Entity::insert_many([
        cake_filling::ActiveModel {
            cake_id: ActiveValue::set(2),
            filling_id: ActiveValue::NotSet,
        },
        cake_filling::ActiveModel {
            cake_id: ActiveValue::NotSet,
            filling_id: ActiveValue::set(3),
        }
    ])
    .build(DbBackend::Postgres)
    .to_string(),
    r#"INSERT INTO "cake_filling" ("cake_id", "filling_id") VALUES (2, NULL), (NULL, 3)"#,
);

To get back inserted Models

use sea_orm::{entity::*, query::*, tests_cfg::fruit};

assert_eq!(
    cake::Entity::insert_many([
        cake::ActiveModel {
            id: NotSet,
            name: Set("Apple Pie".to_owned()),
        },
        cake::ActiveModel {
            id: NotSet,
            name: Set("Choco Pie".to_owned()),
        },
    ])
    .exec_with_returning_many(&db)
    .await?,
    [
        cake::Model {
            id: 1,
            name: "Apple Pie".to_owned(),
        },
        cake::Model {
            id: 2,
            name: "Choco Pie".to_owned(),
        }
    ]
);

assert_eq!(
    db.into_transaction_log()[0].statements()[0].sql,
    r#"INSERT INTO "cake" ("name") VALUES ($1), ($2) RETURNING "id", "name""#
);

fn update<A>(model: A) -> UpdateOne<A>

where A: ActiveModelTrait<Entity = Self>,

Update a model in database

• To apply where conditions / filters, see QueryFilter

Example (Postgres)

use sea_orm::{entity::*, query::*, tests_cfg::fruit};

let orange = fruit::ActiveModel {
    id: Set(1),
    name: Set("Orange".to_owned()),
    ..Default::default()
};

assert_eq!(
    fruit::Entity::update(orange.clone())
        .filter(fruit::Column::Name.contains("orange"))
        .exec(&db)
        .await?,
    fruit::Model {
        id: 1,
        name: "Orange".to_owned(),
        cake_id: None,
    }
);

assert_eq!(
    db.into_transaction_log(),
    [Transaction::from_sql_and_values(
        DbBackend::Postgres,
        r#"UPDATE "fruit" SET "name" = $1 WHERE "fruit"."id" = $2 AND "fruit"."name" LIKE $3 RETURNING "id", "name", "cake_id""#,
        ["Orange".into(), 1i32.into(), "%orange%".into()]
    )]);

Example (MySQL)

use sea_orm::{entity::*, query::*, tests_cfg::fruit};

let orange = fruit::ActiveModel {
    id: Set(1),
    name: Set("Orange".to_owned()),
    ..Default::default()
};

assert_eq!(
    fruit::Entity::update(orange.clone())
        .filter(fruit::Column::Name.contains("orange"))
        .exec(&db)
        .await?,
    fruit::Model {
        id: 1,
        name: "Orange".to_owned(),
        cake_id: None,
    }
);

assert_eq!(
    db.into_transaction_log(),
    [
        Transaction::from_sql_and_values(
            DbBackend::MySql,
            r#"UPDATE `fruit` SET `name` = ? WHERE `fruit`.`id` = ? AND `fruit`.`name` LIKE ?"#,
            ["Orange".into(), 1i32.into(), "%orange%".into()]
        ),
        Transaction::from_sql_and_values(
            DbBackend::MySql,
            r#"SELECT `fruit`.`id`, `fruit`.`name`, `fruit`.`cake_id` FROM `fruit` WHERE `fruit`.`id` = ? LIMIT ?"#,
            [1i32.into(), 1u64.into()]
        )]);

fn update_many() -> UpdateMany<Self>

Update many models in database

• To apply where conditions / filters, see QueryFilter

Example

use sea_orm::{
    entity::*,
    query::*,
    sea_query::{Expr, Value},
    tests_cfg::fruit,
};

let update_result = fruit::Entity::update_many()
    .col_expr(fruit::Column::CakeId, Expr::value(Value::Int(None)))
    .filter(fruit::Column::Name.contains("Apple"))
    .exec(&db)
    .await?;

assert_eq!(update_result.rows_affected, 5);

assert_eq!(
    db.into_transaction_log(),
    [Transaction::from_sql_and_values(
        DbBackend::Postgres,
        r#"UPDATE "fruit" SET "cake_id" = $1 WHERE "fruit"."name" LIKE $2"#,
        [Value::Int(None), "%Apple%".into()]
    )]
);

fn delete<A>(model: A) -> DeleteOne<A>

where A: ActiveModelTrait<Entity = Self>,

Delete a model from database

• To apply where conditions / filters, see QueryFilter

Example

use sea_orm::{entity::*, query::*, tests_cfg::fruit};

let orange = fruit::ActiveModel {
    id: Set(3),
    ..Default::default()
};

let delete_result = fruit::Entity::delete(orange).exec(&db).await?;

assert_eq!(delete_result.rows_affected, 1);

assert_eq!(
    db.into_transaction_log(),
    [Transaction::from_sql_and_values(
        DbBackend::Postgres,
        r#"DELETE FROM "fruit" WHERE "fruit"."id" = $1"#,
        [3i32.into()]
    )]
);

fn delete_many() -> DeleteMany<Self>

Delete many models from database

• To apply where conditions / filters, see QueryFilter

Example

use sea_orm::{entity::*, query::*, tests_cfg::fruit};

let delete_result = fruit::Entity::delete_many()
    .filter(fruit::Column::Name.contains("Apple"))
    .exec(&db)
    .await?;

assert_eq!(delete_result.rows_affected, 5);

assert_eq!(
    db.into_transaction_log(),
    [Transaction::from_sql_and_values(
        DbBackend::Postgres,
        r#"DELETE FROM "fruit" WHERE "fruit"."name" LIKE $1"#,
        ["%Apple%".into()]
    )]
);

fn delete_by_id<T>(values: T) -> DeleteMany<Self>

where T: Into<<Self::PrimaryKey as PrimaryKeyTrait>::ValueType>,

Delete a model based on primary key

Example

use sea_orm::{entity::*, query::*, tests_cfg::fruit};

let delete_result = fruit::Entity::delete_by_id(1).exec(&db).await?;

assert_eq!(delete_result.rows_affected, 1);

assert_eq!(
    db.into_transaction_log(),
    [Transaction::from_sql_and_values(
        DbBackend::Postgres,
        r#"DELETE FROM "fruit" WHERE "fruit"."id" = $1"#,
        [1i32.into()]
    )]
);

Delete by composite key

use sea_orm::{entity::*, query::*, tests_cfg::cake_filling};

let delete_result = cake_filling::Entity::delete_by_id((2, 3)).exec(&db).await?;

assert_eq!(delete_result.rows_affected, 1);

assert_eq!(
    db.into_transaction_log(),
    [Transaction::from_sql_and_values(
        DbBackend::Postgres,
        r#"DELETE FROM "cake_filling" WHERE "cake_filling"."cake_id" = $1 AND "cake_filling"."filling_id" = $2"#,
        [2i32.into(), 3i32.into()]
    )]
);

Panics

Panics if arity of input values don’t match arity of primary key

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl EntityTrait for Entity

type Model = Model

type ActiveModel = ActiveModel

type Column = Column

type PrimaryKey = PrimaryKey

type Relation = Relation

Implementors