[SeaORM] Edit

Author: tyt2y3

SeaORM/docs/06-relation/01-one-to-one.md

@@ -76,22 +76,16 @@ pub struct Model {
     <summary>It's expanded to:</summary>
 
 ```rust
-#[derive(Copy, Clone, Debug, EnumIter)]
+#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
 pub enum Relation {
+    #[sea_orm(
+        belongs_to = "super::cake::Entity",
+        from = "Column::CakeId",
+        to = "super::cake::Column::Id"
+    )]
     Cake,
 }
 
-impl RelationTrait for Relation {
-    fn def(&self) -> RelationDef {
-        match self {
-            Self::Cake => Entity::belongs_to(super::cake::Entity)
-                .from(Column::CakeId)
-                .to(super::cake::Column::Id)
-                .into(),
-        }
-    }
-}
-
 impl Related<super::cake::Entity> for Entity {
     fn to() -> RelationDef {
         Relation::Cake.def()

SeaORM/docs/06-relation/02-one-to-many.md

@@ -38,7 +38,7 @@ impl Related<super::fruit::Entity> for Entity {
 
 ## Defining the Inverse Relation
 
-It is the same as defining the one-to-one inverse relation. The rule of thumb is, always define a `belongs_to` on the Entity with a foreign key `xxx_id`.
+It is the same as defining the one-to-one inverse relation, just without a unique key. The rule of thumb is, always define a `belongs_to` on the Entity with a foreign key `xxx_id`.
 
 ```rust {9,10} title="entity/fruit.rs"
 #[sea_orm::model]
@@ -58,22 +58,16 @@ pub struct Model {
     <summary>It's expanded to:</summary>
 
 ```rust
-#[derive(Copy, Clone, Debug, EnumIter)]
+#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
 pub enum Relation {
+    #[sea_orm(
+        belongs_to = "super::cake::Entity",
+        from = "Column::CakeId",
+        to = "super::cake::Column::Id"
+    )]
     Cake,
 }
 
-impl RelationTrait for Relation {
-    fn def(&self) -> RelationDef {
-        match self {
-            Self::Cake => Entity::belongs_to(super::cake::Entity)
-                .from(Column::CakeId)
-                .to(super::cake::Column::Id)
-                .into(),
-        }
-    }
-}
-
 impl Related<super::cake::Entity> for Entity {
     fn to() -> RelationDef {
         Relation::Cake.def()
@@ -86,32 +80,46 @@ impl Related<super::cake::Entity> for Entity {
 
 Composite foreign key is supported using a tuple syntax.
 
-```rust
-mod composite_a {
-    #[sea_orm::model]
-    #[sea_orm(table_name = "composite_a")]
-    pub struct Model {
-        #[sea_orm(primary_key)]
-        pub id: i32,
-        #[sea_orm(unique_key = "pair")]
-        pub left_id: i32,
-        #[sea_orm(unique_key = "pair")]
-        pub right_id: i32,
-        #[sea_orm(has_one)]
-        pub b: Option<super::composite_b::Entity>,
-    }
+```rust title="composite_a.rs"
+#[sea_orm::model]
+#[sea_orm(table_name = "composite_a")]
+pub struct Model {
+    #[sea_orm(primary_key)]
+    pub id: i32,
+    #[sea_orm(unique_key = "pair")]
+    pub left_id: i32,
+    #[sea_orm(unique_key = "pair")]
+    pub right_id: i32,
+    #[sea_orm(has_one)]
+    pub b: Option<super::composite_b::Entity>,
 }
+```
 
-mod composite_b {
-    #[sea_orm::model]
-    #[sea_orm(table_name = "composite_b")]
-    pub struct Model {
-        #[sea_orm(primary_key)]
-        pub id: i32,
-        pub left_id: i32,
-        pub right_id: i32,
-        #[sea_orm(belongs_to, from = "(left_id, right_id)", to = "(left_id, right_id)")]
-        pub a: Option<super::composite_a::Entity>,
-    }
+```rust title="composite_b.rs"
+#[sea_orm::model]
+#[sea_orm(table_name = "composite_b")]
+pub struct Model {
+    #[sea_orm(primary_key)]
+    pub id: i32,
+    pub left_id: i32,
+    pub right_id: i32,
+    #[sea_orm(belongs_to, from = "(left_id, right_id)", to = "(left_id, right_id)")]
+    pub a: Option<super::composite_a::Entity>,
+}
+```
+
+<details>
+    <summary>It's expanded to:</summary>
+
+```rust title="composite_b.rs"
+#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
+pub enum Relation {
+    #[sea_orm(
+        belongs_to = "super::composite_a::Entity",
+        from = "(Column::LeftId, Column::RightId)",
+        to = "(super::composite_a::Column::LeftId, super::composite_a::Column::RightId)",
+    )]
+    CakeFilling,
 }
-```
+```
+</details>

SeaORM/docs/06-relation/04-complex-relations.md

@@ -79,84 +79,158 @@ assert_eq!(
 
 ## Self Referencing Relations
 
-The `Link` trait can also define self referencing relations. The following example defines an Entity that references itself.
-
-```rust title="self_join.rs"
+```rust title="staff.rs"
 use sea_orm::entity::prelude::*;
 
 #[sea_orm::model]
-#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
-#[sea_orm(table_name = "self_join")]
+#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Eq)]
+#[sea_orm(table_name = "staff")]
 pub struct Model {
-    #[sea_orm(primary_key, auto_increment = false)]
-    pub uuid: Uuid,
-    pub uuid_ref: Option<Uuid>,
-    pub time: Option<Time>,
-    #[sea_orm(self_ref, relation_enum = "SelfRef", from = "uuid_ref", to = "uuid")]
-    pub other: HasOne<Entity>,
+    #[sea_orm(primary_key)]
+    pub id: i32,
+    pub name: String,
+    pub reports_to_id: Option<i32>,
+    #[sea_orm(
+        self_ref,
+        relation_enum = "ReportsTo",
+        from = "reports_to_id",
+        to = "id"
+    )]
+    pub reports_to: HasOne<Entity>,
 }
 
-pub struct SelfReferencingLink;
+impl ActiveModelBehavior for ActiveModel {}
+```
 
-impl Linked for SelfReferencingLink {
-    type FromEntity = Entity;
-    type ToEntity = Entity;
+### Entity Loader
 
-    fn link(&self) -> Vec<RelationDef> {
-        vec![Relation::SelfRef.def()] // <- use the relation here
-    }
-}
+```rust
+let staff = staff::Entity::load()
+    .with(staff::Relation::ReportsTo)
+    .all(db)
+    .await?;
 
-impl ActiveModelBehavior for ActiveModel {}
+assert_eq!(staff[0].name, "Alan");
+assert_eq!(staff[0].reports_to, None);
+
+assert_eq!(staff[1].name, "Ben");
+assert_eq!(staff[1].reports_to.as_ref().unwrap().name, "Alan");
+
+assert_eq!(staff[2].name, "Alice");
+assert_eq!(staff[2].reports_to.as_ref().unwrap().name, "Alan");
+
+assert_eq!(staff[3].name, "Elle");
+assert_eq!(staff[3].reports_to, None);
 ```
 
-### Querying model pairs
+### Model Loader
 
 ```rust
-let models: Vec<(self_join::Model, Option<self_join::Model>)> = self_join::Entity::find()
-    .find_also_linked(self_join::SelfReferencingLink)
-    .order_by_asc(self_join::Column::Time)
+let staff = staff::Entity::find()
+    .order_by_asc(staff::Column::Id)
     .all(db)
     .await?;
+
+let reports_to = staff
+    .load_self(staff::Entity, staff::Relation::ReportsTo, db)
+    .await?;
+
+assert_eq!(staff[0].name, "Alan");
+assert_eq!(reports_to[0], None);
+
+assert_eq!(staff[1].name, "Ben");
+assert_eq!(reports_to[1].unwrap().name, "Alan");
+
+assert_eq!(staff[2].name, "Alice");
+assert_eq!(reports_to[2].unwrap().name, "Alan");
+
+assert_eq!(staff[3].name, "Elle");
+assert_eq!(reports_to[3], None);
+```
+
+It can works in reverse too.
+
+```rust
+let manages = staff
+    .load_self_rev(
+        staff::Entity::find().order_by_asc(staff::Column::Id),
+        staff::Relation::ReportsTo,
+        db,
+    )
+    .await?;
+
+assert_eq!(staff[0].name, "Alan");
+assert_eq!(manages[0].len(), 2);
+assert_eq!(manages[0][0].name, "Ben");
+assert_eq!(manages[0][1].name, "Alice");
+
+assert_eq!(staff[1].name, "Ben");
+assert_eq!(manages[1].len(), 0);
+
+assert_eq!(staff[2].name, "Alice");
+assert_eq!(manages[2].len(), 0);
+
+assert_eq!(staff[3].name, "Elle");
+assert_eq!(manages[3].len(), 0);
 ```
 
 ## Diamond Relations
 
-Sometimes there exist multiple relations between a pair of entities. Here we take the simplest example, where `Cake` can have multiple `Fruit`.
+Sometimes there exist multiple relations between a pair of entities. Here we take the simplest example, where `Bakery` can have multiple `Worker`.
 
 ```rust
 #[sea_orm::model]
-#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
-#[sea_orm(table_name = "cake")]
+#[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
+#[sea_orm(table_name = "bakery")]
 pub struct Model {
     #[sea_orm(primary_key)]
     pub id: i32,
     pub name: String,
-    pub topping_id: i32,
-    pub filling_id: i32,
-    #[sea_orm(belongs_to, relation_enum = "Topping", from = "topping_id", to = "id")]
-    pub topping: HasOne<super::fruit::Entity>,
-    #[sea_orm(belongs_to, relation_enum = "Filling", from = "filling_id", to = "id")]
-    pub filling: HasOne<super::fruit::Entity>,
+    pub manager_id: i32,
+    pub cashier_id: i32,
+    #[sea_orm(belongs_to, relation_enum = "Manager", from = "manager_id", to = "id")]
+    pub manager: HasOne<super::worker::Entity>,
+    #[sea_orm(belongs_to, relation_enum = "Cashier", from = "cashier_id", to = "id")]
+    pub cashier: HasOne<super::worker::Entity>,
 }
 ```
 
-How can we define the `Fruit` Entity?
+How can we define the `Worker` Entity?
 By default, `has_many` invokes the `Related` trait to define the relation.
 As a consequence, we have to specify the `Relation` variant of the related entity manually with the `via_rel` attribute.
 
-```rust
+```rust title="worker.rs"
 #[sea_orm::model]
 #[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
-#[sea_orm(table_name = "fruit")]
+#[sea_orm(table_name = "worker")]
 pub struct Model {
     #[sea_orm(primary_key)]
     pub id: i32,
     pub name: String,
-    #[sea_orm(has_many, relation_enum = "ToppingOf", via_rel = "Topping")]
-    pub topping_of: HasMany<super::cake::Entity>,
-    #[sea_orm(has_many, relation_enum = "FillingOf", via_rel = "Filling")]
-    pub filling_of: HasMany<super::cake::Entity>,
+    #[sea_orm(has_many, relation_enum = "BakeryManager", via_rel = "Manager")]
+    pub manager_of: HasMany<super::bakery::Entity>,
+    #[sea_orm(has_many, relation_enum = "BakeryCashier", via_rel = "Cashier")]
+    pub cashier_of: HasMany<super::bakery::Entity>,
+}
+```
+
+For compact Entities, it looks like this:
+
+```rust title="worker.rs"
+#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel)]
+#[sea_orm(table_name = "worker")]
+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::bakery::Entity", via_rel = "Relation::Manager")]
+    BakeryManager,
+    #[sea_orm(has_many = "super::bakery::Entity", via_rel = "Relation::Cashier")]
+    BakeryCashier,
 }
 ```
 

SeaORM/docs/12-internal-design/04-diesel.md

@@ -165,8 +165,6 @@ assert_eq!(
 );
 ```
 
-Trust me, we'll implement automatic migration soon!
-
 (In Diesel it's not possible to go back from schema description to DDL)
 
 ## Nested select and other ergonomics