Introduce BelongsTo

CHANGELOG.md

@@ -34,6 +34,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### New Features
 
+* Split `belongs_to` from `has_one` with a new `BelongsTo` relation type https://github.com/SeaQL/sea-orm/pull/3118
+
+  A `belongs_to` relation can now be typed `BelongsTo<Entity>` (required) or
+  `BelongsTo<Option<Entity>>` (optional), encoding the foreign-key cardinality in the type,
+  paired with the write-side companion `ActiveBelongsTo`. `BelongsTo` is the recommended
+  type for `belongs_to`; the legacy `HasOne<Entity>` field type remains supported for
+  backward compatibility.
+
 * Role Based Access Control https://github.com/SeaQL/sea-orm/pull/2683
 
   1. a hierarchical RBAC engine that is table scoped

CLAUDE.md

@@ -51,7 +51,7 @@ pub posts: HasMany<super::post::Entity>,
 
 // Belongs-To (explicit foreign key mapping)
 #[sea_orm(belongs_to, from = "user_id", to = "id")]
-pub user: HasOne<super::user::Entity>,
+pub user: BelongsTo<super::user::Entity>,
 
 // Many-to-Many via junction table
 #[sea_orm(has_many, via = "post_tag")]
@@ -74,9 +74,9 @@ pub struct Model {
     #[sea_orm(primary_key, auto_increment = false)]
     pub tag_id: i32,
     #[sea_orm(belongs_to, from = "post_id", to = "id")]
-    pub post: Option<super::post::Entity>,
+    pub post: BelongsTo<super::post::Entity>,
     #[sea_orm(belongs_to, from = "tag_id", to = "id")]
-    pub tag: Option<super::tag::Entity>,
+    pub tag: BelongsTo<super::tag::Entity>,
 }
 ```
 

Cargo.toml

@@ -44,6 +44,7 @@ bigdecimal = { version = "0.4", default-features = false, features = [
     "std",
 ], optional = true }
 chrono = { version = "0.4.30", default-features = false, optional = true }
+derive-where = "1.6.1"
 derive_more = { version = "2", features = ["debug"] }
 futures-util = { version = "0.3", default-features = false, features = [
     "std",

README-zh.md

@@ -91,7 +91,7 @@ mod post {
         pub user_id: i32,
         pub title: String,
         #[sea_orm(belongs_to, from = "user_id", to = "id")]
-        pub author: HasOne<super::user::Entity>,
+        pub author: BelongsTo<super::user::Entity>,
         #[sea_orm(has_many, via = "post_tag")] // 多对多关系，使用中间表
         pub tags: HasMany<super::tag::Entity>,
     }
@@ -124,12 +124,9 @@ smart_user
         id: 42,
         name: "Bob".into(),
         email: "bob@sea-ql.org".into(),
-        profile: HasOne::Loaded(
-            profile::ModelEx {
-                picture: "image.jpg".into(),
-            }
-            .into(),
-        ),
+        profile: HasOne::loaded(Some(profile::ModelEx {
+            picture: "image.jpg".into(),
+        })),
         posts: HasMany::Loaded(vec![post::ModelEx {
             title: "Nice weather".into(),
             tags: HasMany::Loaded(vec![tag::ModelEx {

README.md

@@ -91,7 +91,7 @@ mod post {
         pub user_id: i32,
         pub title: String,
         #[sea_orm(belongs_to, from = "user_id", to = "id")]
-        pub author: HasOne<super::user::Entity>,
+        pub author: BelongsTo<super::user::Entity>,
         #[sea_orm(has_many, via = "post_tag")] // M-N relation with junction
         pub tags: HasMany<super::tag::Entity>,
     }
@@ -124,12 +124,9 @@ smart_user
         id: 42,
         name: "Bob".into(),
         email: "bob@sea-ql.org".into(),
-        profile: HasOne::Loaded(
-            profile::ModelEx {
-                picture: "image.jpg".into(),
-            }
-            .into(),
-        ),
+        profile: HasOne::loaded(Some(profile::ModelEx {
+            picture: "image.jpg".into(),
+        })),
         posts: HasMany::Loaded(vec![post::ModelEx {
             title: "Nice weather".into(),
             tags: HasMany::Loaded(vec![tag::ModelEx {

examples/basic/src/entity/cake_filling.rs

@@ -17,15 +17,15 @@ pub struct Model {
         on_update = "Cascade",
         on_delete = "Cascade"
     )]
-    pub cake: HasOne<super::cake::Entity>,
+    pub cake: BelongsTo<super::cake::Entity>,
     #[sea_orm(
         belongs_to,
         from = "filling_id",
         to = "id",
         on_update = "Cascade",
         on_delete = "Cascade"
     )]
-    pub filling: HasOne<super::filling::Entity>,
+    pub filling: BelongsTo<super::filling::Entity>,
 }
 
 impl ActiveModelBehavior for ActiveModel {}

examples/basic/src/entity/fruit.rs

@@ -11,7 +11,7 @@ pub struct Model {
     pub name: String,
     pub cake_id: Option<i32>,
     #[sea_orm(belongs_to, from = "cake_id", to = "id")]
-    pub cake: HasOne<super::cake::Entity>,
+    pub cake: BelongsTo<Option<super::cake::Entity>>,
 }
 
 impl ActiveModelBehavior for ActiveModel {}

examples/loco_seaography/src/models/_entities/files.rs

@@ -14,5 +14,5 @@ pub struct Model {
     pub notes_id: i32,
     pub file_path: String,
     #[sea_orm(belongs_to, from = "notes_id", to = "id")]
-    pub notes: HasOne<super::notes::Entity>,
+    pub notes: BelongsTo<super::notes::Entity>,
 }

examples/quickstart/src/main.rs

@@ -38,7 +38,7 @@ mod profile {
         #[sea_orm(unique)]
         pub user_id: i32,
         #[sea_orm(belongs_to, from = "user_id", to = "id")]
-        pub user: HasOne<super::user::Entity>,
+        pub user: BelongsTo<super::user::Entity>,
     }
 
     impl ActiveModelBehavior for ActiveModel {}
@@ -56,7 +56,7 @@ mod post {
         pub user_id: i32,
         pub title: String,
         #[sea_orm(belongs_to, from = "user_id", to = "id")]
-        pub author: HasOne<super::user::Entity>,
+        pub author: BelongsTo<super::user::Entity>,
         #[sea_orm(has_many)]
         pub comments: HasMany<super::comment::Entity>,
         #[sea_orm(has_many, via = "post_tag")]
@@ -79,9 +79,9 @@ mod comment {
         pub user_id: i32,
         pub post_id: i32,
         #[sea_orm(belongs_to, from = "user_id", to = "id")]
-        pub user: HasOne<super::user::Entity>,
+        pub user: BelongsTo<super::user::Entity>,
         #[sea_orm(belongs_to, from = "post_id", to = "id")]
-        pub post: HasOne<super::post::Entity>,
+        pub post: BelongsTo<super::post::Entity>,
     }
 
     impl ActiveModelBehavior for ActiveModel {}
@@ -117,9 +117,9 @@ mod post_tag {
         #[sea_orm(primary_key, auto_increment = false)]
         pub tag_id: i32,
         #[sea_orm(belongs_to, from = "post_id", to = "id")]
-        pub post: Option<super::post::Entity>,
+        pub post: BelongsTo<super::post::Entity>,
         #[sea_orm(belongs_to, from = "tag_id", to = "id")]
-        pub tag: Option<super::tag::Entity>,
+        pub tag: BelongsTo<super::tag::Entity>,
     }
 
     impl ActiveModelBehavior for ActiveModel {}
@@ -137,14 +137,14 @@ mod user_follower {
         #[sea_orm(primary_key)]
         pub follower_id: i32,
         #[sea_orm(belongs_to, from = "user_id", to = "id")]
-        pub user: Option<super::user::Entity>,
+        pub user: BelongsTo<super::user::Entity>,
         #[sea_orm(
             belongs_to,
             relation_enum = "Follower",
             from = "follower_id",
             to = "id"
         )]
-        pub follower: Option<super::user::Entity>,
+        pub follower: BelongsTo<super::user::Entity>,
     }
 
     impl ActiveModelBehavior for ActiveModel {}

examples/react_admin/backend/src/models/_entities/files.rs

@@ -14,5 +14,5 @@ pub struct Model {
     pub notes_id: i32,
     pub file_path: String,
     #[sea_orm(belongs_to, from = "notes_id", to = "id")]
-    pub notes: HasOne<super::notes::Entity>,
+    pub notes: BelongsTo<super::notes::Entity>,
 }

examples/seaography_example/graphql/src/entities/baker.rs

@@ -18,7 +18,7 @@ pub struct Model {
         on_update = "Cascade",
         on_delete = "Cascade"
     )]
-    pub bakery: HasOne<super::bakery::Entity>,
+    pub bakery: BelongsTo<Option<super::bakery::Entity>>,
     #[sea_orm(has_many, via = "cake_baker")]
     pub cakes: HasMany<super::cake::Entity>,
 }

examples/seaography_example/graphql/src/entities/cake.rs

@@ -20,7 +20,7 @@ pub struct Model {
         on_update = "Cascade",
         on_delete = "Cascade"
     )]
-    pub bakery: HasOne<super::bakery::Entity>,
+    pub bakery: BelongsTo<super::bakery::Entity>,
     #[sea_orm(has_many, via = "cake_baker")]
     pub bakers: HasMany<super::baker::Entity>,
 }

examples/seaography_example/graphql/src/entities/cake_baker.rs

@@ -17,15 +17,15 @@ pub struct Model {
         on_update = "Cascade",
         on_delete = "Cascade"
     )]
-    pub baker: HasOne<super::baker::Entity>,
+    pub baker: BelongsTo<super::baker::Entity>,
     #[sea_orm(
         belongs_to,
         from = "cake_id",
         to = "id",
         on_update = "Cascade",
         on_delete = "Cascade"
     )]
-    pub cake: HasOne<super::cake::Entity>,
+    pub cake: BelongsTo<super::cake::Entity>,
 }
 
 impl ActiveModelBehavior for ActiveModel {}