Macro joinable

macro_rules! joinable {
    ($($child:ident)::* -> $($parent:ident)::* ($source:ident)) => { ... };
}

Allow two tables to be referenced in a join query without providing an explicit ON clause.

The generated ON clause will always join to the primary key of the parent table. This macro removes the need to call [.on] explicitly, you will still need to invoke allow_tables_to_appear_in_same_query! for these two tables to be able to use the resulting query, unless you are using diesel print-schema which will generate it for you.

If you are using diesel print-schema, an invocation of this macro will be generated for every foreign key in your database unless one of the following is true:

• The foreign key references something other than the primary key
• The foreign key is composite
• There is more than one foreign key connecting two tables
• The foreign key is self-referential

Example

use schema::*;

joinable!(posts -> users (user_id));
allow_tables_to_appear_in_same_query!(posts, users);

let implicit_on_clause = users::table.inner_join(posts::table);
let implicit_on_clause_sql = diesel::debug_query::<DB, _>(&implicit_on_clause).to_string();

let explicit_on_clause = users::table
    .inner_join(posts::table.on(posts::user_id.eq(users::id)));
let explicit_on_clause_sql = diesel::debug_query::<DB, _>(&explicit_on_clause).to_string();

assert_eq!(implicit_on_clause_sql, explicit_on_clause_sql);

In the example above, the line joinable!(posts -> users (user_id));

specifies the relation of the tables and the ON clause in the following way:

child_table -> parent_table (foreign_key)

• parent_table is the Table with the Primary key.

• child_table is the Table with the Foreign key.

So given the Table declaration from Associations docs

• The parent table would be User
• The child table would be Post
• and the Foreign key would be Post.user_id

For joins that do not explicitly use on clauses via JoinOnDsl the following on clause is generated implicitly:

post JOIN users ON posts.user_id = users.id