Compact entity format (SeaQL/sea-orm#105, SeaQL/sea-orm#159)

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
 

SeaORM/docs/03-generate-entity/02-entity-structure.md → 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
 

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<T> with custom `column_type` you must also specify `nullable`
+    #[sea_orm(column_type = "Text", unique, indexed, nullable)]
+    pub name: Option<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().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<i32>,
+    pub name: ActiveValue<Option<String>>,
+}
+```
+
+### 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<i32>,
+}
+```
+
+## 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)