diff --git a/SeaORM/docs/01-index.md b/SeaORM/docs/01-index.md index 8a6ca5c7c6..53e0fa13c5 100644 --- a/SeaORM/docs/01-index.md +++ b/SeaORM/docs/01-index.md @@ -24,7 +24,9 @@ 2.1 [Using `sea-orm-cli`](/docs/generate-entity/sea-orm-cli) - 2.2 [Entity Structure Dissection](/docs/generate-entity/entity-structure) + 2.2 [Expanded Entity Structure Dissection](/docs/generate-entity/expanded-entity-structure) + + 2.3 [Compact Entity Structure Dissection](/docs/generate-entity/compact-entity-structure) 3. Basic CRUD diff --git a/SeaORM/docs/03-generate-entity/02-entity-structure.md b/SeaORM/docs/03-generate-entity/02-expanded-entity-structure.md similarity index 96% rename from SeaORM/docs/03-generate-entity/02-entity-structure.md rename to SeaORM/docs/03-generate-entity/02-expanded-entity-structure.md index 78e70bec5f..fba92930f3 100644 --- a/SeaORM/docs/03-generate-entity/02-entity-structure.md +++ b/SeaORM/docs/03-generate-entity/02-expanded-entity-structure.md @@ -1,10 +1,14 @@ -# Entity Structure +# Expanded Entity Structure An entity file in SeaORM corresponds to a table in the database and should define the specifications including columns, keys and relations. It can be written by hand, or generated by `sea-orm-cli`. -Lets go through the sections of the example [cake](https://github.com/SeaQL/sea-orm/blob/master/src/tests_cfg/cake.rs) entity. +```shell +$ sea-orm-cli generate entity --expanded-format +``` + +Lets go through the sections of the example [cake](https://github.com/SeaQL/sea-orm/blob/master/src/tests_cfg/cake_expanded.rs) entity. ## Entity diff --git a/SeaORM/docs/03-generate-entity/03-compact-entity-structure.md b/SeaORM/docs/03-generate-entity/03-compact-entity-structure.md new file mode 100644 index 0000000000..2b128e29db --- /dev/null +++ b/SeaORM/docs/03-generate-entity/03-compact-entity-structure.md @@ -0,0 +1,261 @@ +# Compact Entity Structure + +Following content is written based on the assumption that you have read the [Expanded Entity Structure](/docs/generate-entity/expanded-entity-structure) section. If you haven't please read it before proceeding. + +It can be written by hand, or generated by `sea-orm-cli`. + +```shell +$ sea-orm-cli generate entity +``` + +Lets go through the sections of the example [cake](https://github.com/SeaQL/sea-orm/blob/master/src/tests_cfg/cake.rs) entity. + +## Model with DeriveEntityModel Macros + +```rust +#[derive(Clone, Debug, PartialEq, DeriveEntityModel)] +#[sea_orm(table_name = "cake")] +pub struct Model { + #[sea_orm(primary_key)] + pub id: i32, + pub name: String, +} +``` + +Adding derive macros [`DeriveEntityModel`](https://docs.rs/sea-orm/*/sea_orm/derive.DeriveEntityModel.html) to `Model` will helps you define following structs and implement its corresponding trait under the hood. +- [Entity](/docs/generate-entity/expanded-entity-structure#entity) +- [Column](/docs/generate-entity/expanded-entity-structure#column) +- [Primary Key](/docs/generate-entity/expanded-entity-structure#primary-key) +- [Active Model](/docs/generate-entity/expanded-entity-structure#active-model) + +You can customize each derived structs or enums by providing macros attributes `#[sea_orm( ... )]` to `Model` or attributes inside it. We will discuss the customizations available for each of them below. + +## Entity + +### Table Name + +```rust +#[derive(Clone, Debug, PartialEq, DeriveEntityModel)] +#[sea_orm(table_name = "cake")] +pub struct Model { ... } +``` + +This will be expanded into... + +```rust +#[derive(Copy, Clone, Default, Debug, DeriveEntity)] +pub struct Entity; + +impl EntityName for Entity { + fn table_name(&self) -> &str { + "cake" + } +} +``` + +## Column + +```rust +#[derive(Clone, Debug, PartialEq, DeriveEntityModel)] +pub struct Model { + // `i32` maps to `ColumnType::Integer` by default + pub id: i32, + // `String` maps to `ColumnType::String` by default + pub name: String, +} +``` + +This will be expanded into... + +```rust +#[derive(Copy, Clone, Debug, EnumIter, DeriveColumn)] +pub enum Column { + Id, + Name, +} + +impl ColumnTrait for Column { + type EntityName = Entity; + + fn def(&self) -> ColumnDef { + match self { + Self::Id => ColumnType::Integer.def(), + Self::Name => ColumnType::String(None).def(), + } + } +} +``` + +### Column Type + +You can override the default mappings between Rust type and `ColumnType` by providing `#[sea_orm(col_type = "...")]` to the target attribute. + +```rust +#[derive(Clone, Debug, PartialEq, DeriveEntityModel)] +pub struct Model { + #[sea_orm(column_type = "Text")] + pub name: String, +} +``` + +This will be expanded into... + +```rust +impl ColumnTrait for Column { + type EntityName = Entity; + + fn def(&self) -> ColumnDef { + match self { + Self::Name => ColumnType::Text(None).def(), + } + } +} +``` + +### Additional Properties + +```rust +#[derive(Clone, Debug, PartialEq, DeriveEntityModel)] +pub struct Model { + // For any Option with custom `column_type` you must also specify `nullable` + #[sea_orm(column_type = "Text", unique, indexed, nullable)] + pub name: Option, +} +``` + +This will be expanded into... + +```rust +impl ColumnTrait for Column { + type EntityName = Entity; + + fn def(&self) -> ColumnDef { + match self { + Self::Name => ColumnType::Text(None).def().unique().indexed().null(), + } + } +} +``` + +## Primary Key + +```rust +#[derive(Clone, Debug, PartialEq, DeriveEntityModel)] +pub struct Model { + #[sea_orm(primary_key)] + pub id: i32, + pub name: String, +} +``` + +This will be expanded into... + +```rust +#[derive(Copy, Clone, Debug, EnumIter, DerivePrimaryKey)] +pub enum PrimaryKey { + Id, +} + +impl PrimaryKeyTrait for PrimaryKey { + type ValueType = i32; + + fn auto_increment() -> bool { + true + } +} +``` + +### Auto Increment + +```rust +#[derive(Clone, Debug, PartialEq, DeriveEntityModel)] +pub struct Model { + #[sea_orm(primary_key, auto_increment = false)] + pub id: i32, +} +``` + +This will be expanded into... + +```rust +impl PrimaryKeyTrait for PrimaryKey { + type ValueType = i32; + + fn auto_increment() -> bool { + false + } +} +``` + +### Composite Key + +```rust +#[derive(Clone, Debug, PartialEq, DeriveEntityModel)] +pub struct Model { + #[sea_orm(primary_key)] + pub cake_id: i32, + #[sea_orm(primary_key)] + pub fruit_id: i32, +} +``` + +This will be expanded into... + +```rust +impl PrimaryKeyTrait for PrimaryKey { + type ValueType = (i32, i32); + + fn auto_increment() -> bool { + // For composite key auto_increment is false by default + false + } +} +``` + +## Active Model + +```rust +#[derive(Clone, Debug, PartialEq, DeriveEntityModel)] +pub struct Model { + #[sea_orm(primary_key)] + pub id: i32, + pub name: String, +} +``` + +This will be expanded into... + +```rust +#[derive(Clone, Debug, PartialEq)] +pub struct ActiveModel { + pub id: ActiveValue, + pub name: ActiveValue>, +} +``` + +### Ignore Attribute + +```rust +#[derive(Clone, Debug, PartialEq, DeriveEntityModel)] +pub struct Model { + #[sea_orm(primary_key)] + pub id: i32, + #[sea_orm(ignore)] + pub name: String, +} +``` + +This will be expanded into... + +```rust +#[derive(Clone, Debug, PartialEq)] +pub struct ActiveModel { + pub id: ActiveValue, +} +``` + +## Relation & Related + +These two sections are identical to those in expanded entity structure. +- [Relation](/docs/generate-entity/expanded-entity-structure#relation) +- [Related](/docs/generate-entity/expanded-entity-structure#related)