Skip to main content

Module entity

sea_orm

Module entity 

Source
Expand description

Entities and the types and traits that describe them.

In SeaORM, every database table is represented by an Entity — a unit struct implementing EntityTrait. The Entity ties together:

Each Entity has two companion types:

  • Model — a plain struct mirroring a row of the table, used for reads.
  • ActiveModel — a struct where every field is wrapped in ActiveValue, used for inserts and partial updates.

From an Entity you can build select, insert, update, and delete queries via EntityTrait::find, EntityTrait::insert, EntityTrait::update, and EntityTrait::delete (plus their _many / _by_id siblings).

§Defining an Entity (2.0 dense format)

The recommended way to define an entity in SeaORM 2.0 is the dense entity format, where the relations live directly on the Model struct as HasOne / HasMany fields:

mod cake {
    use sea_orm::entity::prelude::*;

    #[sea_orm::model]
    #[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
    #[sea_orm(table_name = "cake")]
    pub struct Model {
        #[sea_orm(primary_key)]
        pub id: i32,
        pub name: String,
        #[sea_orm(has_many)]
        pub fruits: HasMany<super::fruit::Entity>,
    }

    impl ActiveModelBehavior for ActiveModel {}
}

§Defining an Entity (1.0 compact format)

The 1.0 compact format remains supported. Here relations are declared as a separate Relation enum implementing RelationTrait, plus an explicit Related impl per foreign entity:

mod cake {
    use sea_orm::entity::prelude::*;

    #[derive(Clone, Debug, PartialEq, Eq, 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()
        }
    }

    impl ActiveModelBehavior for ActiveModel {}
}

Entity files are usually generated for you with sea-orm-cli against an existing database. See the crate-level documentation for a walkthrough of the most common operations.

Re-exports§

pub use compound::EntityLoaderTrait;
pub use ActiveValue::NotSet;
pub use ActiveValue::Set;
pub use ActiveValue::Unchanged;

Modules§

compound
prelude
Re-exports the types and traits most commonly needed to define and use entities. Glob-import this module in entity files: use sea_orm::entity::prelude::*;.

Structs§

BoolColumn
BorrowedIdentityIter
Borrowing iterator over the columns of an Identity.
BytesColumn
ColumnDef
Schema metadata for a single column: SQL type, nullability, defaults, constraints, and other DDL-level options.
DateLikeColumn
Supports both chrono and time Date
DateTimeLikeColumn
Supports both chrono and time DateTime
GenericArrayColumn
IpNetworkColumn
JsonColumn
NumericArrayColumn
NumericColumn
A column of numeric type, including integer, float and decimal
NumericColumnNullable
A column of numeric type, including integer, float and decimal that is also nullable
OwnedIdentityIter
Owning iterator over the columns of an Identity (returned by IntoIterator for Identity).
RelationBuilder
Fluent builder for a RelationDef. Construct one via EntityTrait::belongs_to / has_one / has_many.
RelationDef
Concrete description of a relation between two entities: which tables and columns participate, whether Self is the FK-owning side, and the optional foreign-key constraint metadata.
SeaographyColumnAttr
Column-level attributes consumed by Seaography when generating GraphQL schemas.
StringColumn
StringColumnNullable
TextUuidColumn
TimeLikeColumn
Supports both chrono and time Time
UuidColumn

Enums§

ActiveModelAction
Which save operation an ActiveModel is about to perform — used by hooks and helpers that need to branch on the kind of write.
ActiveValue
The state of a field in an ActiveModel.
ColumnType
All column types
HasManyModel
State carried by a has_many (or many-to-many) field on an ActiveModelEx. Chooses between “leave alone”, “additive write”, and “destructive replace” semantics.
HasOneModel
State carried by a belongs_to or has_one field on an ActiveModelEx. Mirrors the NotSet / Set shape of ActiveValue but for a related model.
Identity
A one-or-many column identifier — the abstraction SeaORM uses to refer to either a single column or a composite (e.g. a composite primary key or foreign key).
RelationType
Cardinality of a relation.
Value
Value variants

Traits§

ActiveEnum
A Rust representation of enum defined in database.
ActiveEnumValue
The Rust Value backing ActiveEnums
ActiveModelBehavior
Lifecycle hooks for an ActiveModelTrait.
ActiveModelTrait
The editable counterpart of a Model, used to build INSERT and UPDATE statements.
ArrowSchemawith-arrow
Apache Arrow schema for an entity.
ColumnTrait
Operations and comparisons available on every entity column.
ColumnTypeTrait
Extension methods on ColumnType for building ColumnDefs and inspecting database ENUM metadata.
EntityName
Names the SQL table backing an Entity, plus the optional schema and comment metadata.
EntityTrait
The contract every SeaORM entity implements — a static description of a table plus the CRUD entry points used to query it.
FromQueryResult
Construct a value from a QueryResult row.
IdenStatic
An identifier (table or column name) that can be borrowed as a &'static str.
IdentityOf
Conversion into an Identity whose columns are guaranteed to belong to entity E. Used by RelationBuilder::from / to so the type system enforces that relation columns reference the right table.
IntoActiveModel
A Trait for any type that can be converted into an ActiveModel, can be derived using DeriveIntoActiveModel.
IntoActiveValue
Any type that can be converted into an ActiveValue
IntoIdentity
Conversion into an Identity. Implemented for &str/String, a single column iden, and tuples of column idens (for composites up to 12 columns).
IntoOption
Iterable
This trait designates that an Enum can be iterated over. It can be auto generated using the EnumIter derive macro.
Linked
A multi-hop traversal between two entities: a chain of LinkDef hops from FromEntity to ToEntity.
ModelTrait
The interface implemented by every Model — an instance of an EntityTrait, roughly an OOP “object” whose fields are the table’s columns.
PartialModelTrait
A partial projection of a Model — a struct that holds only some of the entity’s columns, used to avoid overfetching in SELECT queries.
PrimaryKeyArity
Number of columns a primary key spans — 1 for a single-column key, n for a composite key represented as an n-tuple.
PrimaryKeyToColumn
Conversion between an entity’s PrimaryKey enum and its Column enum. Generated alongside PrimaryKeyTrait for every entity.
PrimaryKeyTrait
Describes the primary key of an entity: which column variants make it up, the Rust value type (a tuple for composite keys), and whether the database auto-generates it.
Related
Self is related to entity R, which lets queries join the two tables without a manual ON clause. For many-to-many relations, override via to point at the junction table.
RelatedSelfVia
Self-referential many-to-many relation: Self <-> Self through a junction table (e.g. user_follower).
RelationTrait
Each variant of an entity’s Relation enum implements this trait, providing the RelationDef that backs joins, foreign keys, and related-model lookups.
TryIntoModel
Fallible conversion into a ModelTrait value.

Functions§

UnsetDeprecated
Defines an not set operation on an ActiveValue

Type Aliases§

ForeignKeyAction
ON DELETE / ON UPDATE action attached to a foreign key. Re-exported from sea_query for convenience.
LinkDef
One hop in a multi-hop Linked chain. Alias for RelationDef.