Add ActiveRecord::Relation#references (#950)

1 files changed, 19 insertions, 1 deletions

diff --git a/activerecord/lib/active_record/relation/query_methods.rb b/activerecord/lib/active_record/relation/query_methods.rb
index 44ff8f7b22..7b340c1b64 100644
--- a/activerecord/lib/active_record/relation/query_methods.rb
+++ b/activerecord/lib/active_record/relation/query_methods.rb
@@ -10,7 +10,7 @@ module ActiveRecord
                   :where_values, :having_values, :bind_values,
                   :limit_value, :offset_value, :lock_value, :readonly_value, :create_with_value,
                   :from_value, :reordering_value, :reverse_order_value,
-                  :uniq_value
+                  :uniq_value, :references_values
 
     def includes(*args)
       args.reject! {|a| a.blank? }
@@ -38,6 +38,24 @@ module ActiveRecord
       relation
     end
 
+    # Used to indicate that an association is referenced by an SQL string, and should
+    # therefore be JOINed in any query rather than loaded separately.
+    #
+    # For example:
+    #
+    #   User.includes(:posts).where("posts.name = 'foo'")
+    #   # => Doesn't JOIN the posts table, resulting in an error.
+    #
+    #   User.includes(:posts).where("posts.name = 'foo'").references(:posts)
+    #   # => Query now knows the string references posts, so adds a JOIN
+    def references(*args)
+      return self if args.blank?
+
+      relation = clone
+      relation.references_values = (references_values + args).uniq
+      relation
+    end
+
     # Works in two unique ways.
     #
     # First: takes a block so it can be used just like Array#select.