Allow (some) subselects to appear in an expression context

A subselect can be used as an expression by wrapping it in parenthesis
as long as the query returns exactly one column, and exactly zero or one
rows. The first constraint is trivial for us to enforce, but the only
way we can enforce the second is by automatically adding `LIMIT 1` to
the query when this method is called. We also need to make the SQL type
nullable, for the same reasons as max, min, avg, etc. They all return
null if the query returns zero rows.

If disjointness on associated types ever lands, I suspect we can just
implement `AsExpression` directly, and deprecate this method. That
said, given that the SQL type has to become nullable, it may be better
to keep the explicit method, so that we don't get questions on why
`id.eq(subselect)` isn't working.

Fixes diesel-rs#1308.

Author: sgrif

CHANGELOG.md

@@ -52,6 +52,11 @@ for Rust libraries in [RFC #1105](https://github.com/rust-lang/rfcs/blob/master/
   `Insertable` (meaning one field can map to more than one column). Add
   `#[diesel(embed)]` to the field to enable this behavior.
 
+* Queries that treat a subselect as a single value (e.g. `foo = (subselect)`)
+  are now supported by calling [`.single_value()`].
+
+[`.single_value()`]: http://docs.diesel.rs/diesel/query_dsl/trait.QueryDsl.html#method.single_value
+
 ### Changed
 
 * The bounds on `impl ToSql for Cow<'a, T>` have been loosened to no longer

diesel/src/lib.rs

@@ -255,6 +255,9 @@ pub mod helper_types {
     /// Represents the return type of `.distinct_on(expr)`
     #[cfg(feature = "postgres")]
     pub type DistinctOn<Source, Expr> = <Source as DistinctOnDsl<Expr>>::Output;
+
+    /// Represents the return type of `.single_value()`
+    pub type SingleValue<Source> = <Source as SingleValueDsl>::Output;
 }
 
 pub mod prelude {

diesel/src/query_dsl/mod.rs

@@ -37,6 +37,7 @@ pub mod select_dsl;
 #[doc(hidden)]
 pub mod filter_dsl;
 mod save_changes_dsl;
+mod single_value_dsl;
 mod offset_dsl;
 mod order_dsl;
 
@@ -65,6 +66,7 @@ pub mod methods {
     pub use super::offset_dsl::OffsetDsl;
     pub use super::order_dsl::{OrderDsl, ThenOrderDsl};
     pub use super::select_dsl::SelectDsl;
+    pub use super::single_value_dsl::SingleValueDsl;
 }
 
 /// Methods used to construct select statements.
@@ -867,6 +869,51 @@ pub trait QueryDsl: Sized {
     {
         methods::BoxedDsl::internal_into_boxed(self)
     }
+
+    /// Wraps this select statement in parenthesis, allowing it to be used
+    /// as an expression.
+    ///
+    /// SQL allows queries such as `foo = (SELECT ...)`, as long as the
+    /// subselect returns only a single column, and 0 or 1 rows. This method
+    /// indicates that you expect the query to only return a single value (this
+    /// will be enforced by adding `LIMIT 1`).
+    ///
+    /// The SQL type of this will always be `Nullable`, as the query returns
+    /// `NULL` if the table is empty or it otherwise returns 0 rows.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # #[macro_use] extern crate diesel;
+    /// # include!("../doctest_setup.rs");
+    /// #
+    /// # fn main() {
+    /// #     run_test();
+    /// # }
+    /// #
+    /// # fn run_test() -> QueryResult<()> {
+    /// #     use diesel::insert_into;
+    /// #     use schema::users::dsl::*;
+    /// #     use schema::posts;
+    /// #     let connection = establish_connection();
+    /// insert_into(posts::table)
+    ///     .values(posts::user_id.eq(1))
+    ///     .execute(&connection)?;
+    /// let last_post = posts::table
+    ///     .order(posts::id.desc());
+    /// let most_recently_active_user = users.select(name)
+    ///     .filter(id.nullable().eq(last_post.select(posts::user_id).single_value()))
+    ///     .first::<String>(&connection)?;
+    /// assert_eq!("Sean", most_recently_active_user);
+    /// #     Ok(())
+    /// # }
+    /// ```
+    fn single_value(self) -> SingleValue<Self>
+    where
+        Self: methods::SingleValueDsl,
+    {
+        methods::SingleValueDsl::single_value(self)
+    }
 }
 
 impl<T: Table> QueryDsl for T {}

diesel/src/query_dsl/single_value_dsl.rs

@@ -0,0 +1,34 @@
+use dsl::Limit;
+use expression::grouped::Grouped;
+use expression::subselect::Subselect;
+use query_builder::SelectQuery;
+use sql_types::{IntoNullable, SingleValue};
+use super::methods::LimitDsl;
+
+/// The `single_value` method
+///
+/// This trait should not be relied on directly by most apps. Its behavior is
+/// provided by [`QueryDsl`]. However, you may need a where clause on this trait
+/// to call `single_value` from generic code.
+///
+/// [`QueryDsl`]: ../trait.QueryDsl.html
+pub trait SingleValueDsl {
+    /// The type returned by `.single_value`.
+    type Output;
+
+    /// See the trait documentation.
+    fn single_value(self) -> Self::Output;
+}
+
+impl<T, ST> SingleValueDsl for T
+where
+    Self: SelectQuery<SqlType = ST> + LimitDsl,
+    ST: IntoNullable,
+    ST::Nullable: SingleValue,
+{
+    type Output = Grouped<Subselect<Limit<Self>, ST::Nullable>>;
+
+    fn single_value(self) -> Self::Output {
+        Grouped(Subselect::new(self.limit(1)))
+    }
+}