diff --git a/sqlx-mysql/src/types.rs b/sqlx-mysql/src/types.rs index a8812297..7b5ca8a4 100644 --- a/sqlx-mysql/src/types.rs +++ b/sqlx-mysql/src/types.rs @@ -1,35 +1,129 @@ -//! Conversions between Rust and MySQL types. +//! Conversions between Rust and [MySQL types](https://dev.mysql.com/doc/refman/8.0/en/data-types.html). //! //! Strict type checking is implemented according to the following tables when using -//! the type-checked query macros. +//! the type-checked query macros. The inferred type of an expression when using the strict +//! compile-time type-checking should be the first Rust type that appears below that matches +//! the SQL type. //! //! Note that type conversions are not strict when used directly. As an example, //! reading an `u8` from a `BIGINT` column will work (as long as the actual value //! fits within `u8`, otherwise it would raise a decoding error). //! -//! ## Types +//! Any required [crate features](https://doc.rust-lang.org/cargo/reference/features.html) +//! are shown next to the type. +//! +//! ## Integer Types //! //! | Rust type | MySQL type(s) | //! |---------------------------------------|------------------------------------------------------| -//! | `bool` | `TINYINT(1)`, `BIT(1)`, `BOOLEAN` | -//! | `i8` | `TINYINT` | -//! | `i16` | `SMALLINT` | -//! | `i32` | `INT`, `MEDIUMINT` | -//! | `i64` | `BIGINT` | -//! | `u8` | `TINYINT UNSIGNED` | -//! | `u16` | `SMALLINT UNSIGNED` | -//! | `u32` | `INT UNSIGNED` | -//! | `u64` | `BIGINT UNSIGNED` | -//! | `f32` | `FLOAT` | -//! | `f64` | `DOUBLE` | -//! | `String` | `TEXT`, `VARCHAR`, `CHAR` | -//! | `Vec` | `BLOB`, `VARBINARY`, `BINARY` | +//! | [`bool`][std::primitive::bool] | `TINYINT(1)`[[1]](#1), `BOOLEAN` | +//! | [`i8`] | `TINYINT` | +//! | [`i16`] | `SMALLINT` | +//! | [`i32`] | `INT`, `MEDIUMINT` | +//! | [`i64`] | `BIGINT` | +//! | [`u8`] | `TINYINT UNSIGNED` | +//! | [`u16`] | `SMALLINT UNSIGNED` | +//! | [`u32`] | `INT UNSIGNED`, `MEDIUMINT UNSIGNED` | +//! | [`u64`] | `BIGINT UNSIGNED` | +//! +//! 1. The `BOOLEAN` type is an alias to `TINYINT(1)`. SQLx will recognize both and +//! infer the type to be `bool`. +//! +//! ## Fixed-Point Types +//! +//! | Rust type | MySQL type(s) | Crate feature | +//! |----------------------------|-----------------------------------|-----------------------------| +//! | [`num_bigint::BigInt`] | `DECIMAL(N, 0)`, `NUMERIC(N, 0)` | `bigint` | +//! | [`bigdecimal::BigDecimal`] | `DECIMAL`, `NUMERIC` | `bigdecimal` | +//! | [`rust_decimal::Decimal`] | `DECIMAL`, `NUMERIC` | `decimal` | +//! +//! ## Floating-Point Types +//! +//! | Rust type | MySQL type(s) | +//! |---------------------------------------|------------------------------------------------------| +//! | [`f32`] | `FLOAT` | +//! | [`f64`] | `DOUBLE`, `REAL` | +//! +//! ## Bit-Value Type - `BIT` +//! +//! | Rust type | MySQL type(s) | Crate feature | +//! |---------------------------------------|-----------------------|------------------------------| +//! | [`bool`] | `BIT(1)` | | +//! | [`bitvec::BitVec`] | `BIT` | `bitvec` | +//! | [`u64`] | `BIT` | | +//! +//! ## String Types +//! +//! | Rust type | MySQL type(s) | +//! |------------------------------------------------|---------------------------------------------| +//! | [`String`], [`&'r str`][&str] | `TEXT`, `VARCHAR`, `CHAR` | +//! | [`bytestring::ByteString`][[2]](#2) | `TEXT`, `VARCHAR`, `CHAR` | +//! +//! ## Binary String Types +//! +//! | Rust type | MySQL type(s) | +//! |---------------------------------------|------------------------------------------------------| +//! | [`Vec`], [`&'r [u8]`][slice] | `BLOB`, `VARBINARY`, `BINARY` | +//! | [`bytes::Bytes`][[2]](#2) | `BLOB`, `VARBINARY`, `BINARY` | +//! +//! 2. The `Bytes` and `ByteString` types can be used as zero-copy containers to +//! read binary and textual data from the connection. +//! +//! ## Date and Time Types +//! +//! | Rust type | MySQL type(s) | Crate feature | +//! |---------------------------------------|-----------------------|------------------------------| +//! | [`u16`] | `YEAR` | | +//! | [`time::Date`] | `DATE` | `time` | +//! | [`time::Time`] | `TIME` | `time` | +//! | [`time::PrimitiveDateTime`] | `DATETIME` | `time` | +//! | [`time::OffsetDateTime`] | `TIMESTAMP` | `time` | +//! | [`chrono::NaiveDate`] | `DATE` | `chrono` | +//! | [`chrono::NaiveTime`] | `TIME` | `chrono` | +//! | [`chrono::NaiveDateTime`] | `DATETIME` | `chrono` | +//! | [`chrono::DateTime`] | `TIMESTAMP` | `chrono` | +//! | [`chrono::DateTime`] | `TIMESTAMP` | `chrono` | +//! | [`chrono::DateTime`] | `TIMESTAMP` | `chrono` | +//! +//! ## JSON Type - `JSON` +//! +//! | Rust type | MySQL type(s) | Crate feature | +//! |---------------------------------------|------------------------------------|-----------------| +//! | [`serde_json::Value`] | `JSON`[[3]](#3), `TEXT` | `json` | +//! | [`&'r serde_json::value::RawValue`] | `JSON`[[3]](#3), `TEXT` | `json` | +//! | [`sqlx::types::Json`] | `JSON`[[3]](#3), `TEXT` | `json` | +//! +//! 3. The `JSON` SQL type is supported by MySQL 8+ **only** (not in MariaDB). To +//! use `JSON` in MariaDB or older MySQL versions, SQLx also supports any +//! string type (eg., `TEXT`). +//! +//! ## UUID Type +//! +//! | Rust type | MySQL type(s) | Crate feature | +//! |-------------------------------|--------------------------|---------------| +//! | [`uuid::Uuid`] | `BINARY(16)`, `CHAR(32)` | `uuid` | +//! | [`uuid::adapter::Hyphenated`] | `CHAR(36)` | `uuid` | +//! +//! ## Nullable Type +//! +//! | Rust type | MySQL type(s) | +//! |------------------------------------------------|-------------------------| +//! | [`Option`][[4]](#4) | (any) | +//! | [`sqlx::types::Null`][[5]](#5) | (any) | +//! +//! 4. The `Option` type represents a potentially `NULL` +//! value. Use this anywhere that you _might_ receive a `NULL`. The compile-time +//! type-checking will enforce using this where necessary. +//! +//! 5. The `Null` type represents a value that is _always_ `NULL`. This +//! can be useful when you wish to pass a `NULL` as a parameter without knowing (or +//! caring about the actual type of the parameter). //! mod bool; +mod bytes; mod str; mod uint; -mod bytes; // TODO: mod decimal; // TODO: mod int;