From 3fc11451b3b063708c88c2a93e1f1629521f0217 Mon Sep 17 00:00:00 2001 From: Josh Date: Fri, 16 May 2025 19:43:06 -0600 Subject: [PATCH 1/4] chore(doc): clarify compile-time verification and case conversion behavior --- sqlx-core/src/from_row.rs | 3 +++ sqlx-core/src/types/mod.rs | 4 ++-- src/macros/mod.rs | 2 +- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/sqlx-core/src/from_row.rs b/sqlx-core/src/from_row.rs index 5b3904011e..5a6de5a264 100644 --- a/sqlx-core/src/from_row.rs +++ b/sqlx-core/src/from_row.rs @@ -65,6 +65,9 @@ use crate::{error::Error, row::Row}; /// reason), `lowercase`, `UPPERCASE`, `camelCase`, `PascalCase`, `SCREAMING_SNAKE_CASE` and `kebab-case`. /// The styling of each option is intended to be an example of its behavior. /// +/// Case conversion word boundaries are defined in the +/// [`heck` docs](https://docs.rs/heck/0.5.0/heck/#definition-of-a-word-boundary). +/// /// #### `default` /// /// When your struct contains a field that is not present in your query, diff --git a/sqlx-core/src/types/mod.rs b/sqlx-core/src/types/mod.rs index b00427daae..f99127db17 100644 --- a/sqlx-core/src/types/mod.rs +++ b/sqlx-core/src/types/mod.rs @@ -99,8 +99,8 @@ pub use bstr::{BStr, BString}; /// /// ## Compile-time verification /// -/// With compile-time verification, the use of type overrides is currently required to make -/// use of any user-defined types. +/// The use of type overrides is currently required to make use of any user-defined types, +/// so they cannot be compile-time verified. /// /// ```rust,ignore /// struct MyUser { id: UserId, name: String } diff --git a/src/macros/mod.rs b/src/macros/mod.rs index 7f8ff747f9..a6ea411769 100644 --- a/src/macros/mod.rs +++ b/src/macros/mod.rs @@ -249,7 +249,7 @@ /// /// ##### Force a Different/Custom Type /// Selecting a column `foo as "foo: T"` (Postgres / SQLite) or `` foo as `foo: T` `` (MySQL) -/// overrides the inferred type which is useful when selecting user-defined custom types +/// overrides the inferred type which is useful when selecting user-defined [`custom types`][crate::Type#compile-time-verification] /// (dynamic type checking is still done so if the types are incompatible this will be an error /// at runtime instead of compile-time). Note that this syntax alone doesn't override inferred nullability, /// but it is compatible with the forced not-null and forced nullable annotations: From 7d67be93ffbf7e40df921a703793ff09f596a24e Mon Sep 17 00:00:00 2001 From: Josh <59372145+duhby@users.noreply.github.com> Date: Sat, 17 May 2025 17:12:35 -0600 Subject: [PATCH 2/4] apply review suggestions Co-authored-by: Austin Bonander --- sqlx-core/src/from_row.rs | 9 +++++++-- sqlx-core/src/types/mod.rs | 7 +++++-- src/macros/mod.rs | 2 +- 3 files changed, 13 insertions(+), 5 deletions(-) diff --git a/sqlx-core/src/from_row.rs b/sqlx-core/src/from_row.rs index 5a6de5a264..69327583e1 100644 --- a/sqlx-core/src/from_row.rs +++ b/sqlx-core/src/from_row.rs @@ -65,8 +65,13 @@ use crate::{error::Error, row::Row}; /// reason), `lowercase`, `UPPERCASE`, `camelCase`, `PascalCase`, `SCREAMING_SNAKE_CASE` and `kebab-case`. /// The styling of each option is intended to be an example of its behavior. /// -/// Case conversion word boundaries are defined in the -/// [`heck` docs](https://docs.rs/heck/0.5.0/heck/#definition-of-a-word-boundary). +/// Case conversion is handled by the `heck` crate. +/// See [its documentation][https://docs.rs/heck/0.5.0/heck/#definition-of-a-word-boundary] +/// for details. +/// +/// Note that numbers are *not* considered separate words. +/// For example, `Foo1` to snake case would be `foo1`, *not* `foo_1`. +/// See [this issue](https://github.com/launchbadge/sqlx/issues/3864) for discussion. /// /// #### `default` /// diff --git a/sqlx-core/src/types/mod.rs b/sqlx-core/src/types/mod.rs index f99127db17..525e53766f 100644 --- a/sqlx-core/src/types/mod.rs +++ b/sqlx-core/src/types/mod.rs @@ -99,8 +99,11 @@ pub use bstr::{BStr, BString}; /// /// ## Compile-time verification /// -/// The use of type overrides is currently required to make use of any user-defined types, -/// so they cannot be compile-time verified. +/// Type definitions are *not* verified against the database at compile-time. +/// The [`query!()`][sqlx::query!] macros have no implicit knowledge of user-defined types. +/// +/// When using custom types in query parameters or output columns with `query!()`, +/// the use of [type overrides][sqlx::query!#type-overrides-bind-parameters-postgres-only] is required. /// /// ```rust,ignore /// struct MyUser { id: UserId, name: String } diff --git a/src/macros/mod.rs b/src/macros/mod.rs index a6ea411769..9e81935876 100644 --- a/src/macros/mod.rs +++ b/src/macros/mod.rs @@ -249,7 +249,7 @@ /// /// ##### Force a Different/Custom Type /// Selecting a column `foo as "foo: T"` (Postgres / SQLite) or `` foo as `foo: T` `` (MySQL) -/// overrides the inferred type which is useful when selecting user-defined [`custom types`][crate::Type#compile-time-verification] +/// overrides the inferred type which is useful when selecting user-defined [custom types][crate::Type#compile-time-verification] /// (dynamic type checking is still done so if the types are incompatible this will be an error /// at runtime instead of compile-time). Note that this syntax alone doesn't override inferred nullability, /// but it is compatible with the forced not-null and forced nullable annotations: From 6ce5681ff4408b6e7e16af528253f3449f8e329b Mon Sep 17 00:00:00 2001 From: Josh Date: Sat, 17 May 2025 17:15:37 -0600 Subject: [PATCH 3/4] fix(fmt): remove trailing spaces --- sqlx-core/src/from_row.rs | 4 ++-- sqlx-core/src/types/mod.rs | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/sqlx-core/src/from_row.rs b/sqlx-core/src/from_row.rs index 69327583e1..0916a84e1b 100644 --- a/sqlx-core/src/from_row.rs +++ b/sqlx-core/src/from_row.rs @@ -65,11 +65,11 @@ use crate::{error::Error, row::Row}; /// reason), `lowercase`, `UPPERCASE`, `camelCase`, `PascalCase`, `SCREAMING_SNAKE_CASE` and `kebab-case`. /// The styling of each option is intended to be an example of its behavior. /// -/// Case conversion is handled by the `heck` crate. +/// Case conversion is handled by the `heck` crate. /// See [its documentation][https://docs.rs/heck/0.5.0/heck/#definition-of-a-word-boundary] /// for details. /// -/// Note that numbers are *not* considered separate words. +/// Note that numbers are *not* considered separate words. /// For example, `Foo1` to snake case would be `foo1`, *not* `foo_1`. /// See [this issue](https://github.com/launchbadge/sqlx/issues/3864) for discussion. /// diff --git a/sqlx-core/src/types/mod.rs b/sqlx-core/src/types/mod.rs index 525e53766f..19e4072292 100644 --- a/sqlx-core/src/types/mod.rs +++ b/sqlx-core/src/types/mod.rs @@ -102,7 +102,7 @@ pub use bstr::{BStr, BString}; /// Type definitions are *not* verified against the database at compile-time. /// The [`query!()`][sqlx::query!] macros have no implicit knowledge of user-defined types. /// -/// When using custom types in query parameters or output columns with `query!()`, +/// When using custom types in query parameters or output columns with `query!()`, /// the use of [type overrides][sqlx::query!#type-overrides-bind-parameters-postgres-only] is required. /// /// ```rust,ignore From 1f44545043c40f4d9e026898526a7435aee10ac8 Mon Sep 17 00:00:00 2001 From: Josh Date: Sat, 17 May 2025 17:54:08 -0600 Subject: [PATCH 4/4] fix(doc): links --- sqlx-core/src/from_row.rs | 2 +- sqlx-core/src/types/mod.rs | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/sqlx-core/src/from_row.rs b/sqlx-core/src/from_row.rs index 0916a84e1b..b96801cb65 100644 --- a/sqlx-core/src/from_row.rs +++ b/sqlx-core/src/from_row.rs @@ -66,7 +66,7 @@ use crate::{error::Error, row::Row}; /// The styling of each option is intended to be an example of its behavior. /// /// Case conversion is handled by the `heck` crate. -/// See [its documentation][https://docs.rs/heck/0.5.0/heck/#definition-of-a-word-boundary] +/// See [its documentation](https://docs.rs/heck/0.5.0/heck/#definition-of-a-word-boundary) /// for details. /// /// Note that numbers are *not* considered separate words. diff --git a/sqlx-core/src/types/mod.rs b/sqlx-core/src/types/mod.rs index 19e4072292..b45fa2fa85 100644 --- a/sqlx-core/src/types/mod.rs +++ b/sqlx-core/src/types/mod.rs @@ -100,10 +100,10 @@ pub use bstr::{BStr, BString}; /// ## Compile-time verification /// /// Type definitions are *not* verified against the database at compile-time. -/// The [`query!()`][sqlx::query!] macros have no implicit knowledge of user-defined types. +/// The [`query!()`](macro.query.html) macros have no implicit knowledge of user-defined types. /// /// When using custom types in query parameters or output columns with `query!()`, -/// the use of [type overrides][sqlx::query!#type-overrides-bind-parameters-postgres-only] is required. +/// the use of [type overrides](macro.query.html#type-overrides-bind-parameters-postgres-only) is required. /// /// ```rust,ignore /// struct MyUser { id: UserId, name: String }