Merge pull request diesel-rs#1026 from diesel-rs/sg-join-on

Allow the `ON` clause of a join to be manually specified

Author: sgrif

CHANGELOG.md

@@ -10,6 +10,11 @@ for Rust libraries in [RFC #1105](https://github.com/rust-lang/rfcs/blob/master/
 
 * Added support for the PG `IS DISTINCT FROM` operator
 
+* The `ON` clause of a join can now be manually specified. See [the
+  docs][join-on-dsl-1.0.0] for details.
+
+[join-on-dsl-1.0.0]: http://docs.diesel.rs/diesel/prelude/trait.JoinOnDsl.html#method.on
+
 ### Changed
 
 * Diesel will now automatically invoke `numeric_expr!` for your columns in the

diesel/src/query_dsl/join_dsl.rs

@@ -1,5 +1,6 @@
 use query_builder::AsQuery;
-use query_source::{joins, Table, JoinTo};
+use query_source::{Table, JoinTo, QuerySource};
+use query_source::joins::{self, OnClauseWrapper};
 
 #[doc(hidden)]
 /// `JoinDsl` support trait to emulate associated type constructors
@@ -106,3 +107,52 @@ pub trait JoinDsl: Sized {
 
 impl<T: AsQuery> JoinDsl for T {
 }
+
+pub trait JoinOnDsl: Sized {
+    /// Specify the `ON` clause for a join statement. This will override
+    /// any implicit `ON` clause that would come from `#[belongs_to]`
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # #[macro_use] extern crate diesel;
+    /// # include!("src/doctest_setup.rs");
+    /// #
+    /// # table! {
+    /// #     users {
+    /// #         id -> Integer,
+    /// #         name -> VarChar,
+    /// #     }
+    /// # }
+    /// #
+    /// # table! {
+    /// #     posts {
+    /// #         id -> Integer,
+    /// #         user_id -> Integer,
+    /// #         title -> Text,
+    /// #     }
+    /// # }
+    /// #
+    /// # enable_multi_table_joins!(users, posts);
+    /// #
+    /// # fn main() {
+    /// #     let connection = establish_connection();
+    /// let data = users::table
+    ///     .left_join(posts::table.on(
+    ///         users::id.eq(posts::user_id).and(
+    ///             posts::title.eq("My first post"))
+    ///     ))
+    ///     .select((users::name, posts::title.nullable()))
+    ///     .load(&connection);
+    /// let expected = vec![
+    ///     ("Sean".to_string(), Some("My first post".to_string())),
+    ///     ("Tess".to_string(), None),
+    /// ];
+    /// assert_eq!(Ok(expected), data);
+    /// # }
+    fn on<On>(self, on: On) -> OnClauseWrapper<Self, On> {
+        OnClauseWrapper::new(self, on)
+    }
+}
+
+impl<T: QuerySource> JoinOnDsl for T {}

diesel/src/query_dsl/mod.rs

@@ -24,7 +24,7 @@ pub use self::distinct_dsl::DistinctDsl;
 pub use self::filter_dsl::{FilterDsl, FindDsl};
 #[doc(hidden)]
 pub use self::group_by_dsl::GroupByDsl;
-pub use self::join_dsl::{InternalJoinDsl, JoinDsl};
+pub use self::join_dsl::{InternalJoinDsl, JoinDsl, JoinOnDsl};
 pub use self::limit_dsl::LimitDsl;
 pub use self::load_dsl::{LoadDsl, ExecuteDsl, FirstDsl, LoadQuery};
 pub use self::offset_dsl::OffsetDsl;

diesel/src/query_source/joins.rs

@@ -5,6 +5,7 @@ use prelude::*;
 use query_builder::*;
 use result::QueryResult;
 use super::QuerySource;
+use types::Bool;
 use util::TupleAppend;
 
 #[derive(Debug, Clone, Copy)]
@@ -47,7 +48,7 @@ impl_query_id!(Join<Left, Right, Kind>);
 impl_query_id!(JoinOn<Join, On>);
 
 impl<Left, Right> QuerySource for Join<Left, Right, Inner> where
-    Left: QuerySource + JoinTo<Right> + AppendSelection<Right::DefaultSelection>,
+    Left: QuerySource + AppendSelection<Right::DefaultSelection>,
     Right: QuerySource,
     Left::Output: SelectableExpression<Self>,
     Self: Clone,
@@ -65,7 +66,7 @@ impl<Left, Right> QuerySource for Join<Left, Right, Inner> where
 }
 
 impl<Left, Right> QuerySource for Join<Left, Right, LeftOuter> where
-    Left: QuerySource + JoinTo<Right> + AppendSelection<Nullable<Right::DefaultSelection>>,
+    Left: QuerySource + AppendSelection<Nullable<Right::DefaultSelection>>,
     Right: QuerySource,
     Left::Output: SelectableExpression<Self>,
     Self: Clone,
@@ -84,7 +85,7 @@ impl<Left, Right> QuerySource for Join<Left, Right, LeftOuter> where
 
 impl<Join, On> QuerySource for JoinOn<Join, On> where
     Join: QuerySource,
-    On: AppearsOnTable<Join::FromClause> + Clone,
+    On: AppearsOnTable<Join::FromClause, SqlType=Bool> + Clone,
     Join::DefaultSelection: SelectableExpression<Self>,
 {
     type FromClause = Grouped<nodes::InfixNode<'static, Join::FromClause, On>>;
@@ -294,3 +295,27 @@ impl<T, U> Plus<T> for Succ<U> where
 impl<T> Plus<T> for Never {
     type Output = T;
 }
+
+#[doc(hidden)]
+#[derive(Debug, Clone, Copy)]
+pub struct OnClauseWrapper<Source, On> {
+    source: Source,
+    on: On,
+}
+
+impl<Source, On> OnClauseWrapper<Source, On> {
+    pub fn new(source: Source, on: On) -> Self {
+        OnClauseWrapper { source, on }
+    }
+}
+
+impl<Lhs, Rhs, On> JoinTo<OnClauseWrapper<Rhs, On>> for Lhs where
+    Lhs: Table,
+{
+    type FromClause = Rhs;
+    type OnClause = On;
+
+    fn join_target(rhs: OnClauseWrapper<Rhs, On>) -> (Self::FromClause, Self::OnClause) {
+        (rhs.source, rhs.on)
+    }
+}

diesel_compile_tests/tests/compile-fail/join_with_explicit_on_requires_valid_boolean_expression.rs

@@ -0,0 +1,36 @@
+#[macro_use] extern crate diesel;
+
+use diesel::prelude::*;
+
+table! {
+    users {
+        id -> Integer,
+    }
+}
+
+table! {
+    posts {
+        id -> Integer,
+    }
+}
+
+table! {
+    comments {
+        id -> Integer,
+    }
+}
+
+enable_multi_table_joins!(users, posts);
+enable_multi_table_joins!(users, comments);
+enable_multi_table_joins!(posts, comments);
+
+fn main() {
+    // Sanity check, make sure valid joins compile
+    let _ = users::table.inner_join(posts::table.on(users::id.eq(posts::id)));
+    // Invalid, references column that isn't being queried
+    let _ = users::table.inner_join(posts::table.on(users::id.eq(comments::id)));
+    //~^ ERROR E0271
+    // Invalid, type is not boolean
+    let _ = users::table.inner_join(posts::table.on(users::id));
+    //~^ ERROR E0271
+}

diesel_tests/tests/joins.rs

@@ -298,6 +298,31 @@ fn selecting_complex_expression_from_both_sides_of_outer_join() {
     assert_eq!(Ok(expected_data), titles);
 }
 
+#[test]
+fn join_with_explicit_on_clause() {
+    let connection = connection_with_sean_and_tess_in_users_table();
+    let new_posts = vec![
+        NewPost::new(1, "Post One", None),
+        NewPost::new(1, "Post Two", None),
+    ];
+    insert(&new_posts).into(posts::table).execute(&connection).unwrap();
+
+    let sean = find_user_by_name("Sean", &connection);
+    let tess = find_user_by_name("Tess", &connection);
+    let post_one = posts::table.filter(posts::title.eq("Post One"))
+        .first::<Post>(&connection)
+        .unwrap();
+    let expected_data = vec![
+        (sean, post_one.clone()),
+        (tess, post_one),
+    ];
+
+    let data = users::table.inner_join(posts::table.on(posts::title.eq("Post One")))
+        .load(&connection);
+
+    assert_eq!(Ok(expected_data), data);
+}
+
 #[test]
 fn selecting_parent_child_grandchild() {
     let (connection, test_data) = connection_with_fixture_data_for_multitable_joins();