Add first class support for newtypes in Queryable and QueryableByName

A consistent problem that's existed for us has been "what do we do about
library X when Diesel doesn't want to care about X, and X doesn't want
to care about Diesel?" Another permutation of this problem has been
folks wanting type conversions that we're never going to support (such
as `impl FromSql<Binary, Sqlite> for Uuid`).

Ultimately the answer for this has pretty much always come down to
newtypes. Whether you're doing it in your app, or having them provided
by a library, that's the only real solution to the orphan rule here.

This commit introduces a new API to all our relevant deserialization
derives: `#[deserialize_as]`. The API is pretty straightforward. You
give us the name of a type. That type has to satisfy whatever
constraints would exist if you used that type directly on your struct.
It also has to implement `Into` for whatever type is on your struct.

This is similar to, but slightly different than
`#[serde(deserialize_with)]`, in that it takes a type name rather than a
function. We cannot mirror serde's API here, as we use this in a
situation where we cannot infer the type you need based on the argument
to the function.

I intend to follow this PR with an equivalent `#[serialize_as]`
attribute for `Insertable` and `AsChangeset`.

Unresolved Questions
--------------------

I'm really not liking using `#[diesel(...)]` to avoid namespace issues.
The main problem with doing that is that we cannot communicate to the
compiler what is allowed inside of it. We also cannot use our normal
"warn if there's unrecognized options" strategy in this case, since
there can be multiple derives that use `#[diesel(...)]` on the same
attribute.

The result of this is that we silently ignore any abnormal options in a
`#[diesel]` attribute. While writing this, I wrote `deserialize_with`
instead of `deserialize_as` twice and couldn't figure out what went
wront. There's a few options here, but I'm not sure which is best.

One would be for us to maintain a global list of all options to
`#[diesel]` that all derives recognize, and warn if something doesn't
match that list. The main downsides to that implemenation is that it's
very brittle, and we won't warn if you use something only recognized by
`#[derive(QueryableByName)]` when that derive isn't present.

The other option is to deprecated `#[diesel(...)]`, and replace all
uses with `#[diesel_...]`. This is the option I'm currently leaning
towards (though I do not think it needs to be done in this PR), since
the only downside is that if you are passing more than one thing to
`#[diesel]`, it will need to be on multiple lines. I do not think we
currently have any cases where that is even reasonable.

Author: sgrif

diesel/src/deserialize.rs

@@ -15,18 +15,26 @@ pub type Result<T> = result::Result<T, Box<Error + Send + Sync>>;
 /// Types which implement `Queryable` represent the result of a SQL query. This
 /// does not necessarily mean they represent a single database table.
 ///
-/// This trait can be derived automatically using `#[derive(Queryable)]`. This
-/// trait can only be derived for structs, not enums.
-///
 /// Diesel represents the return type of a query as a tuple. The purpose of this
 /// trait is to convert from a tuple of Rust values that have been deserialized
 /// into your struct.
 ///
+/// # Deriving
+///
+/// This trait can be derived automatically using `#[derive(Queryable)]`. This
+/// trait can only be derived for structs, not enums.
+///
 /// When this trait is derived, it will assume that the order of fields on your
 /// struct match the order of the fields in the query. This means that field
 /// order is significant if you are using `#[derive(Queryable)]`. Field name has
 /// no effect.
 ///
+/// To provide custom deserialization behavior for a field, you can use
+/// `#[diesel(deserialize_as = "Type")]`. If this attribute is present, Diesel
+/// will deserialize into that type, rather than the type on your struct and
+/// call `.into` to convert it. This can be used to add custom behavior for a
+/// single field, or use types that are otherwise unsupported by Diesel.
+///
 /// # Examples
 ///
 /// If we just want to map a query to our struct, we can use `derive`.
@@ -55,8 +63,59 @@ pub type Result<T> = result::Result<T, Box<Error + Send + Sync>>;
 /// # }
 /// ```
 ///
-/// If we want to do additional work during deserialization, we can implement
-/// the trait ourselves.
+/// If we want to do additional work during deserialization, we can use
+/// `deserialize_as` to use a different implementation.
+///
+/// ```rust
+/// # #[macro_use] extern crate diesel;
+/// # include!("doctest_setup.rs");
+/// #
+/// # use schema::users;
+/// # use diesel::backend::Backend;
+/// # use diesel::deserialize::Queryable;
+/// #
+/// struct LowercaseString(String);
+///
+/// impl Into<String> for LowercaseString {
+///     fn into(self) -> String {
+///         self.0
+///     }
+/// }
+///
+/// impl<DB, ST> Queryable<ST, DB> for LowercaseString
+/// where
+///     DB: Backend,
+///     String: Queryable<ST, DB>,
+/// {
+///     type Row = <String as Queryable<ST, DB>>::Row;
+///
+///     fn build(row: Self::Row) -> Self {
+///         LowercaseString(String::build(row).to_lowercase())
+///     }
+/// }
+///
+/// #[derive(Queryable, PartialEq, Debug)]
+/// struct User {
+///     id: i32,
+///     #[diesel(deserialize_as = "LowercaseString")]
+///     name: String,
+/// }
+///
+/// # fn main() {
+/// #     run_test();
+/// # }
+/// #
+/// # fn run_test() -> QueryResult<()> {
+/// #     use schema::users::dsl::*;
+/// #     let connection = establish_connection();
+/// let first_user = users.first(&connection)?;
+/// let expected = User { id: 1, name: "sean".into() };
+/// assert_eq!(expected, first_user);
+/// #     Ok(())
+/// # }
+/// ```
+///
+/// Alternatively, we can implement the trait for our struct manually.
 ///
 /// ```rust
 /// # #[macro_use] extern crate diesel;
@@ -98,6 +157,7 @@ pub type Result<T> = result::Result<T, Box<Error + Send + Sync>>;
 /// assert_eq!(expected, first_user);
 /// #     Ok(())
 /// # }
+/// ```
 pub trait Queryable<ST, DB>
 where
     DB: Backend,
@@ -133,7 +193,97 @@ where
 /// If a field is another struct which implements `QueryableByName`, instead of
 /// a column, you can annotate that struct with `#[diesel(embed)]`
 ///
+/// To provide custom deserialization behavior for a field, you can use
+/// `#[diesel(deserialize_as = "Type")]`. If this attribute is present, Diesel
+/// will deserialize into that type, rather than the type on your struct and
+/// call `.into` to convert it. This can be used to add custom behavior for a
+/// single field, or use types that are otherwise unsupported by Diesel.
+///
 /// [`sql_query`]: ../fn.sql_query.html
+///
+/// # Examples
+///
+///
+/// If we just want to map a query to our struct, we can use `derive`.
+///
+/// ```rust
+/// # #[macro_use] extern crate diesel;
+/// # include!("doctest_setup.rs");
+/// # use schema::users;
+/// # use diesel::sql_query;
+/// #
+/// #[derive(QueryableByName, PartialEq, Debug)]
+/// #[table_name = "users"]
+/// struct User {
+///     id: i32,
+///     name: String,
+/// }
+///
+/// # fn main() {
+/// #     run_test();
+/// # }
+/// #
+/// # fn run_test() -> QueryResult<()> {
+/// #     let connection = establish_connection();
+/// let first_user = sql_query("SELECT * FROM users ORDER BY id LIMIT 1")
+///     .get_result(&connection)?;
+/// let expected = User { id: 1, name: "Sean".into() };
+/// assert_eq!(expected, first_user);
+/// #     Ok(())
+/// # }
+/// ```
+///
+/// If we want to do additional work during deserialization, we can use
+/// `deserialize_as` to use a different implementation.
+///
+/// ```rust
+/// # #[macro_use] extern crate diesel;
+/// # include!("doctest_setup.rs");
+/// # use diesel::sql_query;
+/// # use schema::users;
+/// # use diesel::backend::Backend;
+/// # use diesel::deserialize::{self, FromSql};
+/// #
+/// struct LowercaseString(String);
+///
+/// impl Into<String> for LowercaseString {
+///     fn into(self) -> String {
+///         self.0
+///     }
+/// }
+///
+/// impl<DB, ST> FromSql<ST, DB> for LowercaseString
+/// where
+///     DB: Backend,
+///     String: FromSql<ST, DB>,
+/// {
+///     fn from_sql(bytes: Option<&DB::RawValue>) -> deserialize::Result<Self> {
+///         String::from_sql(bytes)
+///             .map(|s| LowercaseString(s.to_lowercase()))
+///     }
+/// }
+///
+/// #[derive(QueryableByName, PartialEq, Debug)]
+/// #[table_name = "users"]
+/// struct User {
+///     id: i32,
+///     #[diesel(deserialize_as = "LowercaseString")]
+///     name: String,
+/// }
+///
+/// # fn main() {
+/// #     run_test();
+/// # }
+/// #
+/// # fn run_test() -> QueryResult<()> {
+/// #     let connection = establish_connection();
+/// let first_user = sql_query("SELECT * FROM users ORDER BY id LIMIT 1")
+///     .get_result(&connection)?;
+/// let expected = User { id: 1, name: "sean".into() };
+/// assert_eq!(expected, first_user);
+/// #     Ok(())
+/// # }
+/// ```
 pub trait QueryableByName<DB>
 where
     Self: Sized,

diesel_derives/src/field.rs

@@ -1,5 +1,6 @@
 use proc_macro2::{self, Ident, Span};
 use quote::ToTokens;
+use std::borrow::Cow;
 use syn;
 use syn::spanned::Spanned;
 
@@ -67,6 +68,14 @@ impl Field {
     pub fn has_flag(&self, flag: &str) -> bool {
         self.flags.has_flag(flag)
     }
+
+    pub fn ty_for_deserialize(&self) -> Result<Cow<syn::Type>, Diagnostic> {
+        if let Some(meta) = self.flags.nested_item("deserialize_as")? {
+            meta.ty_value().map(Cow::Owned)
+        } else {
+            Ok(Cow::Borrowed(&self.ty))
+        }
+    }
 }
 
 pub enum FieldName {

diesel_derives/src/lib.rs

@@ -85,7 +85,7 @@ pub fn derive_query_id(input: TokenStream) -> TokenStream {
     expand_derive(input, query_id::derive)
 }
 
-#[proc_macro_derive(Queryable, attributes(column_name))]
+#[proc_macro_derive(Queryable, attributes(column_name, diesel))]
 pub fn derive_queryable(input: TokenStream) -> TokenStream {
     expand_derive(input, queryable::derive)
 }

diesel_derives/src/meta.rs

@@ -130,7 +130,12 @@ impl MetaItem {
 
     pub fn has_flag(&self, flag: &str) -> bool {
         self.nested()
-            .map(|mut n| n.any(|m| m.expect_word() == flag))
+            .map(|mut n| {
+                n.any(|m| match m.word() {
+                    Ok(word) => word == flag,
+                    Err(_) => false,
+                })
+            })
             .unwrap_or_else(|e| {
                 e.emit();
                 false

diesel_derives/src/queryable.rs

@@ -8,11 +8,15 @@ pub fn derive(item: syn::DeriveInput) -> Result<proc_macro2::TokenStream, Diagno
     let model = Model::from_item(&item)?;
 
     let struct_name = &item.ident;
-    let field_ty = model.fields().iter().map(|f| &f.ty).collect::<Vec<_>>();
+    let field_ty = model
+        .fields()
+        .iter()
+        .map(|f| f.ty_for_deserialize())
+        .collect::<Result<Vec<_>, _>>()?;
     let field_ty = &field_ty;
     let build_expr = model.fields().iter().enumerate().map(|(i, f)| {
         let i = syn::Index::from(i);
-        f.name.assign(parse_quote!(row.#i))
+        f.name.assign(parse_quote!(row.#i.into()))
     });
 
     let (_, ty_generics, _) = item.generics.split_for_impl();

diesel_derives/src/queryable_by_name.rs

@@ -9,7 +9,11 @@ pub fn derive(item: syn::DeriveInput) -> Result<proc_macro2::TokenStream, Diagno
     let model = Model::from_item(&item)?;
 
     let struct_name = &item.ident;
-    let field_expr = model.fields().iter().map(|f| field_expr(f, &model));
+    let field_expr = model
+        .fields()
+        .iter()
+        .map(|f| field_expr(f, &model))
+        .collect::<Result<Vec<_>, _>>()?;
 
     let (_, ty_generics, ..) = item.generics.split_for_impl();
     let mut generics = item.generics.clone();
@@ -19,7 +23,7 @@ pub fn derive(item: syn::DeriveInput) -> Result<proc_macro2::TokenStream, Diagno
 
     for field in model.fields() {
         let where_clause = generics.where_clause.get_or_insert(parse_quote!(where));
-        let field_ty = &field.ty;
+        let field_ty = field.ty_for_deserialize()?;
         if field.has_flag("embed") {
             where_clause
                 .predicates
@@ -54,17 +58,18 @@ pub fn derive(item: syn::DeriveInput) -> Result<proc_macro2::TokenStream, Diagno
     ))
 }
 
-fn field_expr(field: &Field, model: &Model) -> syn::FieldValue {
+fn field_expr(field: &Field, model: &Model) -> Result<syn::FieldValue, Diagnostic> {
     if field.has_flag("embed") {
-        field
+        Ok(field
             .name
-            .assign(parse_quote!(QueryableByName::build(row)?))
+            .assign(parse_quote!(QueryableByName::build(row)?)))
     } else {
         let column_name = field.column_name();
+        let ty = field.ty_for_deserialize()?;
         let st = sql_type(field, model);
-        field
+        Ok(field
             .name
-            .assign(parse_quote!(row.get::<#st, _>(stringify!(#column_name))?))
+            .assign(parse_quote!(row.get::<#st, #ty>(stringify!(#column_name))?.into())))
     }
 }