Mirrors/sqlx
2
0
Fork 0
mirror of https://github.com/launchbadge/sqlx synced 2024-11-10 14:34:19 +00:00
Code Issues Projects Releases Packages Wiki Activity

add docs to explain the SQL <-> Rust mapping

Browse source
This commit is contained in:
Ryan Leckey 2020-03-24 02:56:52 -07:00
parent 43a72657f9
commit fa4138b25c
9 changed files with 190 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
Cargo.toml
View file

@ -36,6 +36,11 @@ default = [ "macros", "runtime-async-std" ]
macros = [ "sqlx-macros" ]
tls = [ "sqlx-core/tls" ]
# intended mainly for CI and docs
all = [ "tls", "all-database", "all-type" ]
all-database = [ "mysql", "sqlite", "postgres" ]
all-type = [ "bigdecimal", "json", "time", "chrono", "ipnetwork", "uuid" ]
# runtime
runtime-async-std = [ "sqlx-core/runtime-async-std", "sqlx-macros/runtime-async-std" ]
runtime-tokio = [ "sqlx-core/runtime-tokio", "sqlx-macros/runtime-tokio" ]

4
sqlx-core/Cargo.toml
View file

@ -15,6 +15,10 @@ authors = [
[features]
default = [ "runtime-async-std" ]
unstable = []
# intended mainly for CI and docs
all = ["all-database", "all-type"]
all-database = ["mysql", "sqlite", "postgres"]
all-type = ["bigdecimal", "json", "time", "chrono", "ipnetwork", "uuid"]
# we need a feature which activates `num-bigint` as well because
# `bigdecimal` uses types from it but does not reexport (tsk tsk)
bigdecimal = ["bigdecimal_", "num-bigint"]

2
sqlx-core/src/mysql/mod.rs
View file

@ -20,7 +20,7 @@ mod row;
mod rsa;
mod stream;
mod tls;
mod types;
pub mod types;
mod util;
/// An alias for [`crate::pool::Pool`], specialized for **MySQL**.

49
sqlx-core/src/mysql/types/mod.rs
View file

@ -1,3 +1,52 @@
//! Conversions between Rust and **MySQL** types.
//!
//! # Types
//!
//! | Rust type | MySQL type(s) |
//! |---------------------------------------|------------------------------------------------------|
//! | `bool` | TINYINT(1) |
//! | `i8` | TINYINT |
//! | `i16` | SMALLINT |
//! | `i32` | INT |
//! | `i64` | BIGINT |
//! | `u8` | TINYINT UNSIGNED |
//! | `u16` | SMALLINT UNSIGNED |
//! | `u32` | INT UNSIGNED |
//! | `u64` | BIGINT UNSIGNED |
//! | `f32` | FLOAT |
//! | `f64` | DOUBLE |
//! | `&str`, `String` | VARCHAR, CHAR, TEXT |
//! | `&[u8]`, `Vec<u8>` | VARBINARY, BINARY, BLOB |
//!
//! ### [`chrono`](https://crates.io/crates/chrono)
//!
//! Requires the `chrono` Cargo feature flag.
//!
//! | Rust type | MySQL type(s) |
//! |---------------------------------------|------------------------------------------------------|
//! | `chrono::DateTime<Utc>` | TIMESTAMP |
//! | `chrono::DateTime<Local>` | TIMETAMP |
//! | `chrono::NaiveDateTime` | DATETIME |
//! | `chrono::NaiveDate` | DATE |
//! | `chrono::NaiveTime` | TIME |
//!
//! ### [`time`](https://crates.io/crates/time)
//!
//! Requires the `time` Cargo feature flag.
//!
//! | Rust type | MySQL type(s) |
//! |---------------------------------------|------------------------------------------------------|
//! | `time::PrimitiveDateTime` | DATETIME |
//! | `time::OffsetDateTime` | TIMESTAMP |
//! | `time::Date` | DATE |
//! | `time::Time` | TIME |
//!
//! # Nullable
//!
//! In addition, `Option<T>` is supported where `T` implements `Type`. An `Option<T>` represents
//! a potentially `NULL` value from MySQL.
//!
mod bool;
mod bytes;
mod float;

102
sqlx-core/src/postgres/types/mod.rs
View file

@ -22,8 +22,19 @@
//! | `chrono::DateTime<Utc>` | TIMESTAMPTZ |
//! | `chrono::DateTime<Local>` | TIMESTAMPTZ |
//! | `chrono::NaiveDateTime` | TIMESTAMP |
//! | `chrono::NaiveTime` | DATE |
//! | `chrono::NaiveDate` | TIME |
//! | `chrono::NaiveDate` | DATE |
//! | `chrono::NaiveTime` | TIME |
//!
//! ### [`time`](https://crates.io/crates/time)
//!
//! Requires the `time` Cargo feature flag.
//!
//! | Rust type | Postgres type(s) |
//! |---------------------------------------|------------------------------------------------------|
//! | `time::PrimitiveDateTime` | TIMESTAMP |
//! | `time::OffsetDateTime` | TIMESTAMPTZ |
//! | `time::Date` | DATE |
//! | `time::Time` | TIME |
//!
//! ### [`uuid`](https://crates.io/crates/uuid)
//!
@ -41,13 +52,90 @@
//! |---------------------------------------|------------------------------------------------------|
//! | `ipnetwork::IpNetwork` | INET, CIDR |
//!
//! # Composite types
//! ### [`json`](https://crates.io/crates/serde_json)
//!
//! Anonymous composite types are represented as tuples.
//! Requires the `json` Cargo feature flag.
//!
//! | Rust type | Postgres type(s) |
//! |---------------------------------------|------------------------------------------------------|
//! | [`Json<T>`] | JSONB |
//! | [`PgJson<T>`] | JSON |
//! | [`PgJsonb<T>`] | JSONB |
//! | `serde_json::Value` | JSONB |
//! | `PgJson<serde_json::Value>` | JSON |
//! | `&serde_json::value::RawValue` | JSONB |
//! | `PgJson<&serde_json::value::RawValue>`| JSON |
//!
//! By default, Rust types are mapped to `JSONB`. They can be wrapped in [`PgJson<T>`] to use `JSON`
//! instead.
//!
//! `Value` and `RawValue` from `serde_json` can be used for unstructured JSON data with
//! Postgres.
//!
//! [`Json<T>`] can be used for structured JSON data with Postgres. [`Json<T>`] is an alias
//! for [`PgJsonb<T>`].
//!
//! [`Json<T>`]: crate::types::Json
//! [`PgJson<T>`]: crate::postgres::types::PgJson
//! [`PgJsonb<T>`]: crate::postgres::types::PgJsonb
//!
//! # [Composite types](https://www.postgresql.org/docs/current/rowtypes.html)
//!
//! User-defined composite types are supported through a derive for `Type`.
//!
//! ```text
//! CREATE TYPE inventory_item AS (
//! name text,
//! supplier_id integer,
//! price numeric
//! );
//! ```
//!
//! ```rust,ignore
//! #[derive(sqlx::Type)]
//! #[sqlx(rename = "inventory_item")]
//! struct InventoryItem {
//! name: String,
//! supplier_id: i32,
//! price: BigDecimal,
//! }
//! ```
//!
//! Anonymous composite types are represented as tuples. Note that anonymous composites may only
//! be returned and not sent to Postgres (this is a limitation of postgres).
//!
//! # Arrays
//!
//! One-dimensional arrays are supported as `Vec<T>` or `&[T]` where `T` implements `Type`.
//!
//! # [Enumerations](https://www.postgresql.org/docs/current/datatype-enum.html)
//!
//! User-defined enumerations are supported through a derive for `Type`.
//!
//! ```text
//! CREATE TYPE mood AS ENUM ('sad', 'ok', 'happy');
//! ```
//!
//! ```rust,ignore
//! #[derive(sqlx::Type)]
//! #[sqlx(rename = "mood", rename_all = "lowercase")]
//! enum Mood { Sad, Ok, Happy }
//! ```
//!
//! Rust enumerations may also be defined to be represented as an integer using `repr`.
//! The following type expects a SQL type of `INTEGER` or `INT4` and will convert to/from the
//! Rust enumeration.
//!
//! ```rust,ignore
//! #[derive(sqlx::Type)]
//! #[repr(i32)]
//! enum Mood { Sad = 0, Ok = 1, Happy = 2 }
//! ```
//!
//! # Nullable
//!
//! An `Option<T>` represents a potentially `NULL` value from Postgres.
//! In addition, `Option<T>` is supported where `T` implements `Type`. An `Option<T>` represents
//! a potentially `NULL` value from Postgres.
//!
use std::fmt::{self, Debug, Display};
@ -71,7 +159,7 @@ mod str;
#[doc(hidden)]
pub mod raw;
#[cfg(feature = "bigdecimal_bigint")]
#[cfg(feature = "bigdecimal")]
mod bigdecimal;
#[cfg(feature = "chrono")]
@ -84,7 +172,7 @@ mod time;
mod uuid;
#[cfg(feature = "json")]
pub mod json;
mod json;
#[cfg(feature = "ipnetwork")]
mod ipnetwork;

2
sqlx-core/src/runtime.rs
View file

@ -6,6 +6,7 @@ compile_error!("only one of 'runtime-async-std' or 'runtime-tokio' features must
#[cfg(feature = "runtime-async-std")]
pub(crate) use async_std::{
fs,
future::timeout,
io::prelude::ReadExt as AsyncReadExt,
io::{Read as AsyncRead, Write as AsyncWrite},
@ -16,6 +17,7 @@ pub(crate) use async_std::{
#[cfg(feature = "runtime-tokio")]
pub(crate) use tokio::{
fs,
io::{AsyncRead, AsyncReadExt, AsyncWrite},
net::TcpStream,
task::spawn,

2
sqlx-core/src/sqlite/mod.rs
View file

@ -8,7 +8,7 @@ mod error;
mod executor;
mod row;
mod statement;
mod types;
pub mod types;
mod value;
mod worker;

21
sqlx-core/src/sqlite/types/mod.rs
View file

@ -1,3 +1,24 @@
//! Conversions between Rust and **SQLite** types.
//!
//! # Types
//!
//! | Rust type | SQLite type(s) |
//! |---------------------------------------|------------------------------------------------------|
//! | `bool` | BOOLEAN |
//! | `i16` | INTEGER |
//! | `i32` | INTEGER |
//! | `i64` | INTEGER |
//! | `f32` | REAL |
//! | `f64` | REAL |
//! | `&str`, `String` | TEXT |
//! | `&[u8]`, `Vec<u8>` | BLOB |
//!
//! # Nullable
//!
//! In addition, `Option<T>` is supported where `T` implements `Type`. An `Option<T>` represents
//! a potentially `NULL` value from SQLite.
//!
use std::fmt::{self, Display};
use crate::decode::Decode;

13
sqlx-core/src/types.rs
View file

@ -1,4 +1,15 @@
//! Traits linking Rust types to SQL types.
//! Conversions between Rust and SQL types.
//!
//! To see how each SQL type maps to a Rust type, see the corresponding `types` module for each
//! database:
//!
//! * [PostgreSQL](crate::postgres::types)
//! * [MySQL](crate::mysql::types)
//! * [SQLite](crate::sqlite::types)
//!
//! Any external types that have had [`Type`] implemented for, are re-exported in this module
//! for convenience as downstream users need to use a compatible version of the external crate
//! to take advantage of the implementation.
use std::fmt::{Debug, Display};