From 614df7fb66dfbc84dd4af253ef446b8d43c4f3c4 Mon Sep 17 00:00:00 2001 From: Ryan Leckey Date: Tue, 20 Aug 2019 22:10:16 -0700 Subject: [PATCH] Add various bits of documentation --- src/pg/protocol/mod.rs | 3 +++ src/pg/types/boolean.rs | 3 ++- src/pg/types/character.rs | 3 ++- src/pg/types/mod.rs | 40 +++++++++++++++++++++++++++++++++++++++ src/pg/types/numeric.rs | 7 ++++++- src/query.rs | 1 + src/serialize.rs | 12 ++++++++++++ 7 files changed, 66 insertions(+), 3 deletions(-) diff --git a/src/pg/protocol/mod.rs b/src/pg/protocol/mod.rs index f5f4dfa0..a4e1ffd2 100644 --- a/src/pg/protocol/mod.rs +++ b/src/pg/protocol/mod.rs @@ -1,3 +1,6 @@ +//! Low level PostgreSQL protocol. Defines the encoding and decoding of the messages communicated +//! to and from the database server. + mod bind; mod cancel_request; mod close; diff --git a/src/pg/types/boolean.rs b/src/pg/types/boolean.rs index e268e2f9..8935250e 100644 --- a/src/pg/types/boolean.rs +++ b/src/pg/types/boolean.rs @@ -1,4 +1,4 @@ -use super::{Pg, PgTypeMetadata}; +use super::{Pg, PgTypeMetadata, PgTypeFormat}; use crate::{ deserialize::FromSql, serialize::{IsNull, ToSql}, @@ -8,6 +8,7 @@ use crate::{ impl HasSqlType for Pg { fn metadata() -> PgTypeMetadata { PgTypeMetadata { + format: PgTypeFormat::Binary, oid: 16, array_oid: 1000, } diff --git a/src/pg/types/character.rs b/src/pg/types/character.rs index 77ec56ba..60afbd18 100644 --- a/src/pg/types/character.rs +++ b/src/pg/types/character.rs @@ -1,4 +1,4 @@ -use super::{Pg, PgTypeMetadata}; +use super::{Pg, PgTypeMetadata, PgTypeFormat}; use crate::{ deserialize::FromSql, serialize::{IsNull, ToSql}, @@ -10,6 +10,7 @@ impl HasSqlType<&'_ str> for Pg { #[inline] fn metadata() -> PgTypeMetadata { PgTypeMetadata { + format: PgTypeFormat::Binary, oid: 25, array_oid: 1009, } diff --git a/src/pg/types/mod.rs b/src/pg/types/mod.rs index aa67f246..e7a11121 100644 --- a/src/pg/types/mod.rs +++ b/src/pg/types/mod.rs @@ -1,3 +1,32 @@ +//! PostgreSQL types. +//! +//! The following types are supported by this crate, +//! along with the corresponding Postgres types: +//! +//! ### Standard +//! +//! | Rust type | Postgres type(s) | +//! |-----------------------------------|--------------------------------------| +//! | `i16` | SMALLINT, SMALLSERIAL | +//! | `i32` | INT, SERIAL | +//! | `i64` | BIGINT, BIGSERIAL | +//! | `f32` | REAL | +//! | `f64` | DOUBLE PRECISION | +//! | `&str`/`String` | VARCHAR, CHAR(n), TEXT, CITEXT, NAME | +//! | `&[u8]`/`Vec` | BYTEA | +//! +//! ### PostgreSQL specific +//! +//! | Rust type | Postgres type(s) | +//! |-----------------------------------|--------------------------------------| +//! | `bool` | BOOL | +//! | `i8` | "char" | +//! | `u32` | OID | +//! | `&[u8]`/`Vec` | BYTEA | +//! | `HashMap>` | HSTORE | +//! | `IpAddr` | INET | +//! + use super::Pg; use crate::types::TypeMetadata; @@ -5,7 +34,18 @@ mod boolean; mod character; mod numeric; +pub enum PgTypeFormat { + Text = 0, + Binary = 1, +} + +/// Provides the OIDs for a SQL type and the expected format to be used for +/// transmission between Rust and PostgreSQL. +/// +/// While the BINARY format is preferred in most cases, there are scenarios +/// where only the TEXT format may be available for a type. pub struct PgTypeMetadata { + pub format: PgTypeFormat, pub oid: u32, pub array_oid: u32, } diff --git a/src/pg/types/numeric.rs b/src/pg/types/numeric.rs index 483b7114..7c289b22 100644 --- a/src/pg/types/numeric.rs +++ b/src/pg/types/numeric.rs @@ -1,4 +1,4 @@ -use super::{Pg, PgTypeMetadata}; +use super::{Pg, PgTypeMetadata, PgTypeFormat}; use crate::{ deserialize::FromSql, serialize::{IsNull, ToSql}, @@ -10,6 +10,7 @@ impl HasSqlType for Pg { #[inline] fn metadata() -> PgTypeMetadata { PgTypeMetadata { + format: PgTypeFormat::Binary, oid: 21, array_oid: 1005, } @@ -36,6 +37,7 @@ impl HasSqlType for Pg { #[inline] fn metadata() -> PgTypeMetadata { PgTypeMetadata { + format: PgTypeFormat::Binary, oid: 23, array_oid: 1007, } @@ -62,6 +64,7 @@ impl HasSqlType for Pg { #[inline] fn metadata() -> PgTypeMetadata { PgTypeMetadata { + format: PgTypeFormat::Binary, oid: 20, array_oid: 1016, } @@ -88,6 +91,7 @@ impl HasSqlType for Pg { #[inline] fn metadata() -> PgTypeMetadata { PgTypeMetadata { + format: PgTypeFormat::Binary, oid: 700, array_oid: 1021, } @@ -112,6 +116,7 @@ impl HasSqlType for Pg { #[inline] fn metadata() -> PgTypeMetadata { PgTypeMetadata { + format: PgTypeFormat::Binary, oid: 701, array_oid: 1022, } diff --git a/src/query.rs b/src/query.rs index 3a831c66..a44a86eb 100644 --- a/src/query.rs +++ b/src/query.rs @@ -81,6 +81,7 @@ where } } +/// Construct a full SQL query using raw SQL. #[inline] pub fn query<'q, DB>(query: &'q str) -> SqlQuery<'q, DB> where diff --git a/src/serialize.rs b/src/serialize.rs index 99dd0dd7..b3740818 100644 --- a/src/serialize.rs +++ b/src/serialize.rs @@ -1,3 +1,4 @@ +//! Types and traits related to serializing values for the database. use crate::{backend::Backend, types::HasSqlType}; /// Annotates the result of [ToSql] to differentiate between an empty value and a null value. @@ -12,10 +13,21 @@ pub enum IsNull { } /// Serializes a single value to be sent to the database. +/// +/// The data must be written to the buffer in the expected format for the given backend. +/// +/// When possible, implementations of this trait should prefer using an existing implementation, +/// rather than writing to `out` directly. pub trait ToSql { + /// Writes the value of `self` into `buf` as the expected format for the given backend. + /// + /// The return value indicates if this value should be represented as `NULL`. + /// If this is the case, implementations **must not** write anything to `out`. fn to_sql(self, buf: &mut Vec) -> IsNull; } +/// [ToSql] is implemented for `Option` where `T` implements `ToSql`. An `Option` +/// represents a nullable SQL value. impl ToSql for Option where DB: Backend + HasSqlType,