Repository: launchbadge/sqlx
File: sqlx-core/src/types/mod.rs (Rust)

Code before:
#[cfg_attr(docsrs, doc(cfg(feature = "ipnetwork")))]
pub mod ipnetwork {
    #[doc(no_inline)]
    pub use ipnetwork::{IpNetwork, Ipv4Network, Ipv6Network};
}

#[cfg(feature = "mac_address")]
#[cfg_attr(docsrs, doc(cfg(feature = "mac_address")))]
pub mod mac_address {
    #[doc(no_inline)]
    pub use mac_address::MacAddress;
}

#[cfg(feature = "json")]
pub use json::{Json, JsonRawValue, JsonValue};
pub use text::Text;

#[cfg(feature = "bstr")]
pub use bstr::{BStr, BString};

/// Indicates that a SQL type is supported for a database.
///
/// ## 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.
///
/// ```rust,ignore
/// struct MyUser { id: UserId, name: String }
///
/// // fetch all properties from user and override the type in Rust for `id`
/// let user = query_as!(MyUser, r#"SELECT users.*, id as "id: UserId" FROM users"#)
///     .fetch_one(&pool).await?;
/// ```
///
/// ## Derivable
///
/// This trait can be derived by SQLx to support Rust-only wrapper types, enumerations, and (for
/// postgres) structured records. Additionally, an implementation of [`Encode`](crate::encode::Encode) and [`Decode`](crate::decode::Decode) is
/// generated.
///
/// ### Transparent
///
/// Rust-only domain wrappers around SQL types. The generated implementations directly delegate
/// to the implementation of the inner type.
///
/// ```rust,ignore
/// #[derive(sqlx::Type)]
/// #[sqlx(transparent)]
/// struct UserId(i64);
/// ```

Review comment (suggestion):
If we're revising this statement, we might as well make it abundantly clear:

```suggestion
/// 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.
```

Code after:
#[cfg_attr(docsrs, doc(cfg(feature = "ipnetwork")))]
pub mod ipnetwork {
    #[doc(no_inline)]
    pub use ipnetwork::{IpNetwork, Ipv4Network, Ipv6Network};
}

#[cfg(feature = "mac_address")]
#[cfg_attr(docsrs, doc(cfg(feature = "mac_address")))]
pub mod mac_address {
    #[doc(no_inline)]
    pub use mac_address::MacAddress;
}

#[cfg(feature = "json")]
pub use json::{Json, JsonRawValue, JsonValue};
pub use text::Text;

#[cfg(feature = "bstr")]
pub use bstr::{BStr, BString};

/// Indicates that a SQL type is supported for a database.
///
/// ## Compile-time verification
///
/// Type definitions are *not* verified against the database at compile-time.
/// 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](macro.query.html#type-overrides-bind-parameters-postgres-only) is required.
///
/// ```rust,ignore
/// struct MyUser { id: UserId, name: String }
///
/// // fetch all properties from user and override the type in Rust for `id`
/// let user = query_as!(MyUser, r#"SELECT users.*, id as "id: UserId" FROM users"#)
///     .fetch_one(&pool).await?;
/// ```
///
/// ## Derivable
///
/// This trait can be derived by SQLx to support Rust-only wrapper types, enumerations, and (for
/// postgres) structured records. Additionally, an implementation of [`Encode`](crate::encode::Encode) and [`Decode`](crate::decode::Decode) is
/// generated.
///
/// ### Transparent
///
/// Rust-only domain wrappers around SQL types. The generated implementations directly delegate
/// to the implementation of the inner type.
///
/// ```rust,ignore
/// #[derive(sqlx::Type)]