Merge pull request diesel-rs#1976 from diesel-rs/sg-raw-value-gats

Restructure `Backend::RawValue` to allow non-references

Author: weiznich

CHANGELOG.md

@@ -6,11 +6,28 @@ for Rust libraries in [RFC #1105](https://github.com/rust-lang/rfcs/blob/master/
 
 ## Unreleased
 
+### Changed
+
+* The way [the `Backend` trait][backend-2-0-0] handles its `RawValue` type has
+  been changed to allow non-references. Users of this type (e.g. code written
+  `&DB::RawValue` or `&<DB as Backend>::RawValue>`) should use
+  [`backend::RawValue<DB>`][raw-value-2-0-0] instead. Implementors of `Backend`
+  should check the relevant section of [the migration guide][2-0-migration].
+
+[backend-2-0-0]: http://docs.diesel.rs/diesel/backend/trait.Backend.html
+[raw-value-2-0-0]: http://docs.diesel.rs/diesel/backend/type.RawValue.html
+
+
+
+
+[2-0-migration]: FIXME write a migration guide
+
 ## [1.4.1] - 2019-01-24
 
 ### Fixed
 
-* This release fixes a minor memory safety issue in SQLite. This bug would only occur in an error handling branch that should never occur in practice.
+* This release fixes a minor memory safety issue in SQLite. This bug would only
+  occur in an error handling branch that should never occur in practice.
 
 ## [1.4.0] - 2019-01-20
 

diesel/src/backend.rs

@@ -32,6 +32,7 @@ where
     Self: HasSqlType<sql_types::Date>,
     Self: HasSqlType<sql_types::Time>,
     Self: HasSqlType<sql_types::Timestamp>,
+    Self: for<'a> HasRawValue<'a>,
 {
     /// The concrete `QueryBuilder` implementation for this backend.
     type QueryBuilder: QueryBuilder<Self>;
@@ -41,17 +42,28 @@ where
     ///
     /// [`RawBytesBindCollector`]: ../query_builder/bind_collector/struct.RawBytesBindCollector.html
     type BindCollector: BindCollector<Self>;
-    /// The raw representation of a database value given to `FromSql`.
-    ///
-    /// Since most backends transmit data as opaque blobs of bytes, this type
-    /// is usually `[u8]`.
-    type RawValue: ?Sized;
     /// What byte order is used to transmit integers?
     ///
     /// This type is only used if `RawValue` is `[u8]`.
     type ByteOrder: ByteOrder;
 }
 
+/// The raw representation of a database value given to `FromSql`.
+///
+/// This trait is separate from `Backend` to imitate `type RawValue<'a>`. It
+/// should only be referenced directly by implementors. Users of this type
+/// should instead use the [`RawValue`](type.RawValue.html) helper type instead.
+pub trait HasRawValue<'a> {
+    /// The actual type given to `FromSql`, with lifetimes applied. This type
+    /// should not be used directly. Use the [`RawValue`](type.RawValue.html)
+    /// helper type instead.
+    type RawValue;
+}
+
+/// A helper type to get the raw representation of a database type given to
+/// `FromSql`. Equivalent to `<DB as Backend>::RawValue<'a>`.
+pub type RawValue<'a, DB> = <DB as HasRawValue<'a>>::RawValue;
+
 /// Does this backend support `RETURNING` clauses?
 pub trait SupportsReturningClause {}
 /// Does this backend support the bare `DEFAULT` keyword?

diesel/src/deserialize.rs

@@ -3,7 +3,7 @@
 use std::error::Error;
 use std::result;
 
-use backend::Backend;
+use backend::{self, Backend};
 use row::{NamedRow, Row};
 
 /// A specialized result type representing the result of deserializing
@@ -71,7 +71,7 @@ pub type Result<T> = result::Result<T, Box<Error + Send + Sync>>;
 /// # include!("doctest_setup.rs");
 /// #
 /// # use schema::users;
-/// # use diesel::backend::Backend;
+/// # use diesel::backend::{self, Backend};
 /// # use diesel::deserialize::Queryable;
 /// #
 /// struct LowercaseString(String);
@@ -241,7 +241,7 @@ where
 /// # include!("doctest_setup.rs");
 /// # use diesel::sql_query;
 /// # use schema::users;
-/// # use diesel::backend::Backend;
+/// # use diesel::backend::{self, Backend};
 /// # use diesel::deserialize::{self, FromSql};
 /// #
 /// struct LowercaseString(String);
@@ -257,7 +257,7 @@ where
 ///     DB: Backend,
 ///     String: FromSql<ST, DB>,
 /// {
-///     fn from_sql(bytes: Option<&DB::RawValue>) -> deserialize::Result<Self> {
+///     fn from_sql(bytes: Option<backend::RawValue<DB>>) -> deserialize::Result<Self> {
 ///         String::from_sql(bytes)
 ///             .map(|s| LowercaseString(s.to_lowercase()))
 ///     }
@@ -321,7 +321,7 @@ where
 /// implementation.
 ///
 /// ```rust
-/// # use diesel::backend::Backend;
+/// # use diesel::backend::{self, Backend};
 /// # use diesel::sql_types::*;
 /// # use diesel::deserialize::{self, FromSql};
 /// #
@@ -337,7 +337,7 @@ where
 ///     DB: Backend,
 ///     i32: FromSql<Integer, DB>,
 /// {
-///     fn from_sql(bytes: Option<&DB::RawValue>) -> deserialize::Result<Self> {
+///     fn from_sql(bytes: Option<backend::RawValue<DB>>) -> deserialize::Result<Self> {
 ///         match i32::from_sql(bytes)? {
 ///             1 => Ok(MyEnum::A),
 ///             2 => Ok(MyEnum::B),
@@ -348,7 +348,7 @@ where
 /// ```
 pub trait FromSql<A, DB: Backend>: Sized {
     /// See the trait documentation.
-    fn from_sql(bytes: Option<&DB::RawValue>) -> Result<Self>;
+    fn from_sql(bytes: Option<backend::RawValue<DB>>) -> Result<Self>;
 }
 
 /// Deserialize one or more fields.

diesel/src/mysql/backend.rs

@@ -49,10 +49,13 @@ pub enum MysqlType {
 impl Backend for Mysql {
     type QueryBuilder = MysqlQueryBuilder;
     type BindCollector = MysqlBindCollector;
-    type RawValue = [u8];
     type ByteOrder = NativeEndian;
 }
 
+impl<'a> HasRawValue<'a> for Mysql {
+    type RawValue = &'a [u8];
+}
+
 impl TypeMetadata for Mysql {
     type TypeMetadata = MysqlType;
     type MetadataLookup = ();

diesel/src/mysql/types/numeric.rs

@@ -5,7 +5,7 @@ pub mod bigdecimal {
     use self::bigdecimal::BigDecimal;
     use std::io::prelude::*;
 
-    use backend::Backend;
+    use backend;
     use deserialize::{self, FromSql};
     use mysql::Mysql;
     use serialize::{self, IsNull, Output, ToSql};
@@ -20,7 +20,7 @@ pub mod bigdecimal {
     }
 
     impl FromSql<Numeric, Mysql> for BigDecimal {
-        fn from_sql(bytes: Option<&<Mysql as Backend>::RawValue>) -> deserialize::Result<Self> {
+        fn from_sql(bytes: Option<backend::RawValue<Mysql>>) -> deserialize::Result<Self> {
             let bytes_ptr = <*const [u8] as FromSql<Binary, Mysql>>::from_sql(bytes)?;
             let bytes = unsafe { &*bytes_ptr };
             BigDecimal::parse_bytes(bytes, 10)

diesel/src/pg/backend.rs

@@ -39,10 +39,13 @@ impl Queryable<(Oid, Oid), Pg> for PgTypeMetadata {
 impl Backend for Pg {
     type QueryBuilder = PgQueryBuilder;
     type BindCollector = RawBytesBindCollector<Pg>;
-    type RawValue = [u8];
     type ByteOrder = NetworkEndian;
 }
 
+impl<'a> HasRawValue<'a> for Pg {
+    type RawValue = &'a [u8];
+}
+
 impl TypeMetadata for Pg {
     type TypeMetadata = PgTypeMetadata;
     type MetadataLookup = PgMetadataLookup;

diesel/src/row.rs

@@ -1,6 +1,6 @@
 //! Contains the `Row` trait
 
-use backend::Backend;
+use backend::{self, Backend};
 use deserialize::{self, FromSql};
 
 /// Represents a single database row.
@@ -11,7 +11,7 @@ use deserialize::{self, FromSql};
 /// [`FromSqlRow`]: ../deserialize/trait.FromSqlRow.html
 pub trait Row<DB: Backend> {
     /// Returns the value of the next column in the row.
-    fn take(&mut self) -> Option<&DB::RawValue>;
+    fn take(&mut self) -> Option<backend::RawValue<DB>>;
 
     /// Returns whether the next `count` columns are all `NULL`.
     ///
@@ -62,5 +62,5 @@ pub trait NamedRow<DB: Backend> {
     #[doc(hidden)]
     fn index_of(&self, column_name: &str) -> Option<usize>;
     #[doc(hidden)]
-    fn get_raw_value(&self, index: usize) -> Option<&DB::RawValue>;
+    fn get_raw_value(&self, index: usize) -> Option<backend::RawValue<DB>>;
 }

diesel/src/sqlite/backend.rs

@@ -41,10 +41,13 @@ pub enum SqliteType {
 impl Backend for Sqlite {
     type QueryBuilder = SqliteQueryBuilder;
     type BindCollector = RawBytesBindCollector<Sqlite>;
-    type RawValue = SqliteValue;
     type ByteOrder = NativeEndian;
 }
 
+impl<'a> HasRawValue<'a> for Sqlite {
+    type RawValue = &'a SqliteValue;
+}
+
 impl TypeMetadata for Sqlite {
     type TypeMetadata = SqliteType;
     type MetadataLookup = ();

diesel/src/sqlite/types/date_and_time/chrono.rs

@@ -3,7 +3,7 @@ extern crate chrono;
 use self::chrono::{NaiveDate, NaiveDateTime, NaiveTime};
 use std::io::Write;
 
-use backend::Backend;
+use backend;
 use deserialize::{self, FromSql};
 use serialize::{self, Output, ToSql};
 use sql_types::{Date, Text, Time, Timestamp};
@@ -12,7 +12,7 @@ use sqlite::Sqlite;
 const SQLITE_DATE_FORMAT: &str = "%F";
 
 impl FromSql<Date, Sqlite> for NaiveDate {
-    fn from_sql(value: Option<&<Sqlite as Backend>::RawValue>) -> deserialize::Result<Self> {
+    fn from_sql(value: Option<backend::RawValue<Sqlite>>) -> deserialize::Result<Self> {
         let text_ptr = <*const str as FromSql<Date, Sqlite>>::from_sql(value)?;
         let text = unsafe { &*text_ptr };
         Self::parse_from_str(text, SQLITE_DATE_FORMAT).map_err(Into::into)
@@ -27,7 +27,7 @@ impl ToSql<Date, Sqlite> for NaiveDate {
 }
 
 impl FromSql<Time, Sqlite> for NaiveTime {
-    fn from_sql(value: Option<&<Sqlite as Backend>::RawValue>) -> deserialize::Result<Self> {
+    fn from_sql(value: Option<backend::RawValue<Sqlite>>) -> deserialize::Result<Self> {
         let text_ptr = <*const str as FromSql<Date, Sqlite>>::from_sql(value)?;
         let text = unsafe { &*text_ptr };
         let valid_time_formats = &[
@@ -54,7 +54,7 @@ impl ToSql<Time, Sqlite> for NaiveTime {
 }
 
 impl FromSql<Timestamp, Sqlite> for NaiveDateTime {
-    fn from_sql(value: Option<&<Sqlite as Backend>::RawValue>) -> deserialize::Result<Self> {
+    fn from_sql(value: Option<backend::RawValue<Sqlite>>) -> deserialize::Result<Self> {
         let text_ptr = <*const str as FromSql<Date, Sqlite>>::from_sql(value)?;
         let text = unsafe { &*text_ptr };
 

diesel/src/type_impls/floats.rs

@@ -2,12 +2,15 @@ use byteorder::{ReadBytesExt, WriteBytesExt};
 use std::error::Error;
 use std::io::prelude::*;
 
-use backend::Backend;
+use backend::{Backend, HasRawValue};
 use deserialize::{self, FromSql};
 use serialize::{self, IsNull, Output, ToSql};
 use sql_types;
 
-impl<DB: Backend<RawValue = [u8]>> FromSql<sql_types::Float, DB> for f32 {
+impl<DB> FromSql<sql_types::Float, DB> for f32
+where
+    DB: Backend + for<'a> HasRawValue<'a, RawValue = &'a [u8]>,
+{
     fn from_sql(bytes: Option<&[u8]>) -> deserialize::Result<Self> {
         let mut bytes = not_none!(bytes);
         debug_assert!(
@@ -29,7 +32,10 @@ impl<DB: Backend> ToSql<sql_types::Float, DB> for f32 {
     }
 }
 
-impl<DB: Backend<RawValue = [u8]>> FromSql<sql_types::Double, DB> for f64 {
+impl<DB> FromSql<sql_types::Double, DB> for f64
+where
+    DB: Backend + for<'a> HasRawValue<'a, RawValue = &'a [u8]>,
+{
     fn from_sql(bytes: Option<&[u8]>) -> deserialize::Result<Self> {
         let mut bytes = not_none!(bytes);
         debug_assert!(