From 0ef310efc04dcbec6b1a856c5e486de6393bbdd0 Mon Sep 17 00:00:00 2001 From: Thibault Date: Thu, 2 Jul 2026 09:50:01 +0200 Subject: [PATCH 1/2] docs: native enum rs_type = "Enum" breaking change in 2.0 --- .../docs/04-generate-entity/04-enumeration.md | 39 ++++++++++++++++++- .../09-schema-statement/02-create-enum.md | 8 +++- 2 files changed, 43 insertions(+), 4 deletions(-) diff --git a/SeaORM/docs/04-generate-entity/04-enumeration.md b/SeaORM/docs/04-generate-entity/04-enumeration.md index 359f73e8407..cfc27c6d84a 100644 --- a/SeaORM/docs/04-generate-entity/04-enumeration.md +++ b/SeaORM/docs/04-generate-entity/04-enumeration.md @@ -88,7 +88,7 @@ pub enum Color { ```rust #[derive(EnumIter, DeriveActiveEnum)] -#[sea_orm(rs_type = "String", db_type = "Enum", enum_name = "tea")] +#[sea_orm(rs_type = "Enum", db_type = "Enum", enum_name = "tea")] pub enum Tea { #[sea_orm(string_value = "EverydayTea")] EverydayTea, @@ -97,6 +97,41 @@ pub enum Tea { } ``` +:::tip Since `2.0.0` +Native database enums now use `rs_type = "Enum"` (previously `rs_type = "String"`). This is a breaking change from SeaORM 1.x. + +The associated `ActiveEnum::Value` type is [`sea_query::Enum`](https://docs.rs/sea-query/1/sea_query/struct.Enum.html) instead of `String`, so that the value can carry the enum's type name as metadata. As a result, [`to_value`](https://docs.rs/sea-orm/2/sea_orm/entity/trait.ActiveEnum.html#tymethod.to_value) returns a `sea_query::Enum`, and [`try_from_value`](https://docs.rs/sea-orm/2/sea_orm/entity/trait.ActiveEnum.html#tymethod.try_from_value) expects a `&sea_query::Enum`. + +The `sea_query::Enum` struct is: + +```rust +pub struct Enum { + pub type_name: EnumTypeName, // RcOrArc + pub value: Cow<'static, str>, +} +``` + +To convert a native enum variant **to** a `String`, read the `value` field: + +```rust +let s: String = tea.to_value().value.into(); +``` + +To convert a `String` **into** a native enum variant, construct a `sea_query::Enum` first: + +```rust +use sea_orm::sea_query; + +let value = sea_query::Enum { + type_name: Tea::name().inner().into(), + value: input_string.into(), +}; +let tea = Tea::try_from_value(&value)?; +``` + +String-backed (`rs_type = "String"`) and integer-backed (`rs_type = "i32"`) enums are unaffected: their `Value` type remains `String` / `i32`. +::: + ### MySQL MySQL enum is just part of the column definition, and cannot be reused for different tables. @@ -142,7 +177,7 @@ manager ```rust #[derive(EnumIter, DeriveActiveEnum)] -#[sea_orm(rs_type = "String", db_type = "Enum", enum_name = "tea")] +#[sea_orm(rs_type = "Enum", db_type = "Enum", enum_name = "tea")] pub enum Tea { #[sea_orm(string_value = "EverydayTea")] EverydayTea, diff --git a/SeaORM/docs/09-schema-statement/02-create-enum.md b/SeaORM/docs/09-schema-statement/02-create-enum.md index 7e4e8d08d4e..680408d8e30 100644 --- a/SeaORM/docs/09-schema-statement/02-create-enum.md +++ b/SeaORM/docs/09-schema-statement/02-create-enum.md @@ -112,7 +112,7 @@ pub struct Model { } #[derive(Debug, Clone, PartialEq, Eq, EnumIter, DeriveActiveEnum)] -#[sea_orm(rs_type = "String", db_type = "Enum", enum_name = "tea")] +#[sea_orm(rs_type = "Enum", db_type = "Enum", enum_name = "tea")] pub enum Tea { #[sea_orm(string_value = "EverydayTea")] EverydayTea, @@ -121,7 +121,11 @@ pub enum Tea { } ``` -Note the `db_type` and extra `enum_name` attributes. +Note the `rs_type = "Enum"`, `db_type = "Enum"` and extra `enum_name` attributes. + +:::tip Since `2.0.0` +Native database enums use `rs_type = "Enum"` (previously `rs_type = "String"`). See [ActiveEnum → Native Database Enum](../04-generate-entity/04-enumeration.md#native-database-enum) for details on the new `sea_query::Enum` value type. +::: ### PostgreSQL From bdeba00bdcdaa57e4c7d1ddb887a6180b6bd4d87 Mon Sep 17 00:00:00 2001 From: Thibault Date: Mon, 19 Oct 2026 12:25:57 +0200 Subject: [PATCH 2/2] chore: handle feedbacks --- Blog/blog/2026-01-12-sea-orm-2.0.md | 45 +++++++++++++++++++ .../docs/04-generate-entity/04-enumeration.md | 35 +++------------ .../09-schema-statement/02-create-enum.md | 6 +-- 3 files changed, 52 insertions(+), 34 deletions(-) diff --git a/Blog/blog/2026-01-12-sea-orm-2.0.md b/Blog/blog/2026-01-12-sea-orm-2.0.md index f438efad173..2bb40707348 100644 --- a/Blog/blog/2026-01-12-sea-orm-2.0.md +++ b/Blog/blog/2026-01-12-sea-orm-2.0.md @@ -164,6 +164,51 @@ pub struct MyInteger(pub i32); // only for i8 | i16 | i32 | i64 | u8 | u16 | u32 | u64 ``` +### Native enum value is now `sea_query::Enum` + +[#3043](https://github.com/SeaQL/sea-orm/pull/3043) Native database enums now use `rs_type = "Enum"`, which is also the default when `rs_type` is omitted and what `sea-orm-cli` generates. `ActiveEnum::Value` becomes `sea_query::Enum` instead of `String`, so the value carries the enum type name. + +```rust +// old +#[sea_orm(rs_type = "String", db_type = "Enum", enum_name = "tea")] + +// new +#[sea_orm(rs_type = "Enum", db_type = "Enum", enum_name = "tea")] +``` + +`to_value` now returns a `sea_query::Enum`, and `try_from_value` expects a `&sea_query::Enum`. Use `TryFrom<&str>` to convert from a string: + +```rust +// old +let tea = Tea::try_from_value(&string)?; +let s: String = tea.to_value(); + +// new +let tea = Tea::try_from(string.as_str())?; +let s: String = tea.to_value().value.into_owned(); +``` + +`rs_type = "String"` is still supported if you prefer to keep `String` values. + +#### Possible compile errors + +```rust +error[E0308]: mismatched types + | +> | Tea::try_from_value(&string) + | ------------------- ^^^^^^^ expected `&Enum`, found `&String` + | + = note: expected reference `&sea_orm::sea_query::Enum` + found reference `&std::string::String` +``` + +```rust +error[E0308]: mismatched types + | +> | let s: String = tea.to_value(); + | ^^^^^^^^^^^^^^ expected `String`, found `Enum` +``` + ### `execute` -> `execute_raw` [#2657](https://github.com/SeaQL/sea-orm/pull/2657) Overhauled `ConnectionTrait` API: `execute`, `query_one`, `query_all`, `stream` now takes in SeaQuery statement instead of raw SQL statement, and methods accepting `Statement` has been moved to `*_raw`. diff --git a/SeaORM/docs/04-generate-entity/04-enumeration.md b/SeaORM/docs/04-generate-entity/04-enumeration.md index cfc27c6d84a..a4c3ba1d0c7 100644 --- a/SeaORM/docs/04-generate-entity/04-enumeration.md +++ b/SeaORM/docs/04-generate-entity/04-enumeration.md @@ -97,40 +97,17 @@ pub enum Tea { } ``` -:::tip Since `2.0.0` -Native database enums now use `rs_type = "Enum"` (previously `rs_type = "String"`). This is a breaking change from SeaORM 1.x. - -The associated `ActiveEnum::Value` type is [`sea_query::Enum`](https://docs.rs/sea-query/1/sea_query/struct.Enum.html) instead of `String`, so that the value can carry the enum's type name as metadata. As a result, [`to_value`](https://docs.rs/sea-orm/2/sea_orm/entity/trait.ActiveEnum.html#tymethod.to_value) returns a `sea_query::Enum`, and [`try_from_value`](https://docs.rs/sea-orm/2/sea_orm/entity/trait.ActiveEnum.html#tymethod.try_from_value) expects a `&sea_query::Enum`. - -The `sea_query::Enum` struct is: - -```rust -pub struct Enum { - pub type_name: EnumTypeName, // RcOrArc - pub value: Cow<'static, str>, -} -``` - -To convert a native enum variant **to** a `String`, read the `value` field: - -```rust -let s: String = tea.to_value().value.into(); -``` - -To convert a `String` **into** a native enum variant, construct a `sea_query::Enum` first: +With `rs_type = "Enum"` (the default when `rs_type` is omitted, and what `sea-orm-cli` generates), `ActiveEnum::Value` is [`sea_query::Enum`](https://docs.rs/sea-query/1/sea_query/value/struct.Enum.html), which carries the enum type name along with the string value. To convert from and to a string: ```rust -use sea_orm::sea_query; +// &str -> Tea +let tea = Tea::try_from("EverydayTea")?; -let value = sea_query::Enum { - type_name: Tea::name().inner().into(), - value: input_string.into(), -}; -let tea = Tea::try_from_value(&value)?; +// Tea -> String +let s: String = tea.to_value().value.into_owned(); ``` -String-backed (`rs_type = "String"`) and integer-backed (`rs_type = "i32"`) enums are unaffected: their `Value` type remains `String` / `i32`. -::: +`rs_type = "String"` is also supported, in which case `ActiveEnum::Value` is `String`. ### MySQL diff --git a/SeaORM/docs/09-schema-statement/02-create-enum.md b/SeaORM/docs/09-schema-statement/02-create-enum.md index 680408d8e30..3c67583712e 100644 --- a/SeaORM/docs/09-schema-statement/02-create-enum.md +++ b/SeaORM/docs/09-schema-statement/02-create-enum.md @@ -121,11 +121,7 @@ pub enum Tea { } ``` -Note the `rs_type = "Enum"`, `db_type = "Enum"` and extra `enum_name` attributes. - -:::tip Since `2.0.0` -Native database enums use `rs_type = "Enum"` (previously `rs_type = "String"`). See [ActiveEnum → Native Database Enum](../04-generate-entity/04-enumeration.md#native-database-enum) for details on the new `sea_query::Enum` value type. -::: +Note the `rs_type`, `db_type` and extra `enum_name` attributes. ### PostgreSQL