Deprecate inferred JOINs with includes + SQL snippets.

See the CHANGELOG for details.

Fixes #950.

23 files changed, 216 insertions, 66 deletions

diff --git a/activerecord/CHANGELOG.md b/activerecord/CHANGELOG.md
index bba6447bf9..7173f44df6 100644
--- a/activerecord/CHANGELOG.md
+++ b/activerecord/CHANGELOG.md
@@ -1,5 +1,35 @@
 ## Rails 4.0.0 (unreleased) ##
 
+*   In previous releases, the following would generate a single query with
+    an `OUTER JOIN comments`, rather than two separate queries:
+
+        Post.includes(:comments)
+            .where("comments.name = 'foo'")
+
+    This behaviour relies on matching SQL string, which is an inherently
+    flawed idea unless we write an SQL parser, which we do not wish to
+    do.
+
+    Therefore, you must explicitly state which tables you reference,
+    when using SQL snippets:
+
+        Post.includes(:comments)
+            .where("comments.name = 'foo'")
+            .references(:comments)
+
+    Note that you do not need to explicitly specify references in the
+    following cases, as they can be automatically inferred:
+
+        Post.where(comments: { name: 'foo' })
+        Post.where('comments.name' => 'foo')
+        Post.order('comments.name')
+
+    You also do not need to worry about this unless you are doing eager
+    loading. Basically, don't worry unless you see a deprecation warning
+    or (in future releases) an SQL error due to a missing JOIN.
+
+    [Jon Leighton]
+
 *   Support for the `schema_info` table has been dropped.  Please
     switch to `schema_migrations`.
 
diff --git a/activerecord/lib/active_record/associations/association_scope.rb b/activerecord/lib/active_record/associations/association_scope.rb
index 3759af26d6..0209ce36df 100644
--- a/activerecord/lib/active_record/associations/association_scope.rb
+++ b/activerecord/lib/active_record/associations/association_scope.rb
@@ -20,7 +20,7 @@ module ActiveRecord
         # It's okay to just apply all these like this. The options will only be present if the
         # association supports that option; this is enforced by the association builder.
         scope = scope.apply_finder_options(options.slice(
-          :readonly, :include, :order, :limit, :joins, :group, :having, :offset, :select))
+          :readonly, :include, :references, :order, :limit, :joins, :group, :having, :offset, :select))
 
         if options[:through] && !options[:include]
           scope = scope.includes(source_options[:include])
diff --git a/activerecord/lib/active_record/associations/builder/association.rb b/activerecord/lib/active_record/associations/builder/association.rb
index d4f59100e8..6e2e5f9de0 100644
--- a/activerecord/lib/active_record/associations/builder/association.rb
+++ b/activerecord/lib/active_record/associations/builder/association.rb
@@ -1,7 +1,7 @@
 module ActiveRecord::Associations::Builder
   class Association #:nodoc:
     class_attribute :valid_options
-    self.valid_options = [:class_name, :foreign_key, :select, :conditions, :include, :extend, :readonly, :validate]
+    self.valid_options = [:class_name, :foreign_key, :select, :conditions, :include, :extend, :readonly, :validate, :references]
 
     # Set by subclasses
     class_attribute :macro
diff --git a/activerecord/lib/active_record/relation.rb b/activerecord/lib/active_record/relation.rb
index 7838271e5c..01019db2cc 100644
--- a/activerecord/lib/active_record/relation.rb
+++ b/activerecord/lib/active_record/relation.rb
@@ -1,5 +1,6 @@
 # -*- coding: utf-8 -*-
 require 'active_support/core_ext/object/blank'
+require 'active_support/deprecation'
 
 module ActiveRecord
   # = Active Record Relation
@@ -520,9 +521,30 @@ module ActiveRecord
 
       # always convert table names to downcase as in Oracle quoted table names are in uppercase
       joined_tables = joined_tables.flatten.compact.map { |t| t.downcase }.uniq
-
-      (tables_in_string(to_sql) - joined_tables).any? ||
-      (references_values - joined_tables).any?
+      string_tables = tables_in_string(to_sql)
+
+      if (references_values - joined_tables).any?
+        true
+      elsif (string_tables - joined_tables).any?
+        ActiveSupport::Deprecation.warn(
+          "It looks like you are eager loading table(s) (one of: #{string_tables.join(', ')}) " \
+          "that are referenced in a string SQL snippet. For example: \n" \
+          "\n" \
+          "    Post.includes(:comments).where(\"comments.title = 'foo'\")\n" \
+          "\n" \
+          "Currently, Active Record recognises the table in the string, and knows to JOIN the " \
+          "comments table to the query, rather than loading comments in a separate query. " \
+          "However, doing this without writing a full-blown SQL parser is inherently flawed. " \
+          "Since we don't want to write an SQL parser, we are removing this functionality. " \
+          "From now on, you must explicitly tell Active Record when you are referencing a table " \
+          "from a string:\n" \
+          "\n" \
+          "    Post.includes(:comments).where(\"comments.title = 'foo'\").references(:comments)\n\n"
+        )
+        true
+      else
+        false
+      end
     end
 
     def tables_in_string(string)
diff --git a/activerecord/lib/active_record/relation/spawn_methods.rb b/activerecord/lib/active_record/relation/spawn_methods.rb
index c25570d758..7131aa29b6 100644
--- a/activerecord/lib/active_record/relation/spawn_methods.rb
+++ b/activerecord/lib/active_record/relation/spawn_methods.rb
@@ -122,7 +122,7 @@ module ActiveRecord
       result
     end
 
-    VALID_FIND_OPTIONS = [ :conditions, :include, :joins, :limit, :offset, :extend,
+    VALID_FIND_OPTIONS = [ :conditions, :include, :joins, :limit, :offset, :extend, :references,
                            :order, :select, :readonly, :group, :having, :from, :lock ]
 
     def apply_finder_options(options)
@@ -133,7 +133,7 @@ module ActiveRecord
       finders = options.dup
       finders.delete_if { |key, value| value.nil? && key != :limit }
 
-      ([:joins, :select, :group, :order, :having, :limit, :offset, :from, :lock, :readonly] & finders.keys).each do |finder|
+      ((VALID_FIND_OPTIONS - [:conditions, :include, :extend]) & finders.keys).each do |finder|
         relation = relation.send(finder, finders[finder])
       end
 
diff --git a/activerecord/test/cases/associations/cascaded_eager_loading_test.rb b/activerecord/test/cases/associations/cascaded_eager_loading_test.rb
index ff376a68d8..6733f3e889 100644
--- a/activerecord/test/cases/associations/cascaded_eager_loading_test.rb
+++ b/activerecord/test/cases/associations/cascaded_eager_loading_test.rb
@@ -61,7 +61,7 @@ class CascadedEagerLoadingTest < ActiveRecord::TestCase
   end
 
   def test_cascaded_eager_association_loading_with_duplicated_includes
-    categories = Category.includes(:categorizations).includes(:categorizations => :author).where("categorizations.id is not null")
+    categories = Category.includes(:categorizations).includes(:categorizations => :author).where("categorizations.id is not null").references(:categorizations)
     assert_nothing_raised do
       assert_equal 3, categories.count
       assert_equal 3, categories.all.size
@@ -69,7 +69,7 @@ class CascadedEagerLoadingTest < ActiveRecord::TestCase
   end
 
   def test_cascaded_eager_association_loading_with_twice_includes_edge_cases
-    categories = Category.includes(:categorizations => :author).includes(:categorizations => :post).where("posts.id is not null")
+    categories = Category.includes(:categorizations => :author).includes(:categorizations => :post).where("posts.id is not null").references(:posts)
     assert_nothing_raised do
       assert_equal 3, categories.count
       assert_equal 3, categories.all.size
@@ -127,7 +127,7 @@ class CascadedEagerLoadingTest < ActiveRecord::TestCase
     silly.parent_id = 1
     assert silly.save
 
-    topics = Topic.find(:all, :include => :replies, :order => 'topics.id, replies_topics.id')
+    topics = Topic.find(:all, :include => :replies, :order => ['topics.id', 'replies_topics.id'])
     assert_no_queries do
       assert_equal 2, topics[0].replies.size
       assert_equal 0, topics[1].replies.size
diff --git a/activerecord/test/cases/associations/eager_test.rb b/activerecord/test/cases/associations/eager_test.rb
index 3d759e64f8..b79c69bbb5 100644
--- a/activerecord/test/cases/associations/eager_test.rb
+++ b/activerecord/test/cases/associations/eager_test.rb
@@ -61,7 +61,10 @@ class EagerAssociationTest < ActiveRecord::TestCase
   end
 
   def test_loading_conditions_with_or
-    posts = authors(:david).posts.find(:all, :include => :comments, :conditions => "comments.body like 'Normal%' OR comments.#{QUOTED_TYPE} = 'SpecialComment'")
+    posts = authors(:david).posts.find(
+      :all, :include => :comments, :references => :comments,
+      :conditions => "comments.body like 'Normal%' OR comments.#{QUOTED_TYPE} = 'SpecialComment'"
+    )
     assert_nil posts.detect { |p| p.author_id != authors(:david).id },
       "expected to find only david's posts"
   end
@@ -164,7 +167,7 @@ class EagerAssociationTest < ActiveRecord::TestCase
     car_post.categories << categories(:technology)
 
     comment = car_post.comments.create!(:body => "hmm")
-    categories = Category.find(:all, :conditions => ["posts.id=?", car_post.id],
+    categories = Category.find(:all, :conditions => { 'posts.id' => car_post.id },
                                  :include => {:posts => :comments})
     categories.each do |category|
       assert_equal [comment], category.posts[0].comments
@@ -273,17 +276,26 @@ class EagerAssociationTest < ActiveRecord::TestCase
   end
 
   def test_nested_loading_through_has_one_association_with_conditions
-    aa = AuthorAddress.find(author_addresses(:david_address).id, :include => {:author => :posts}, :conditions => "author_addresses.id > 0")
+    aa = AuthorAddress.find(
+      author_addresses(:david_address).id, :include => {:author => :posts},
+      :conditions => "author_addresses.id > 0", :references => :author_addresses
+    )
     assert_equal aa.author.posts.count, aa.author.posts.length
   end
 
   def test_nested_loading_through_has_one_association_with_conditions_on_association
-    aa = AuthorAddress.find(author_addresses(:david_address).id, :include => {:author => :posts}, :conditions => "authors.id > 0")
+    aa = AuthorAddress.find(
+      author_addresses(:david_address).id, :include => {:author => :posts},
+      :conditions => "authors.id > 0", :references => :authors
+    )
     assert_equal aa.author.posts.count, aa.author.posts.length
   end
 
   def test_nested_loading_through_has_one_association_with_conditions_on_nested_association
-    aa = AuthorAddress.find(author_addresses(:david_address).id, :include => {:author => :posts}, :conditions => "posts.id > 0")
+    aa = AuthorAddress.find(
+      author_addresses(:david_address).id, :include => {:author => :posts},
+      :conditions => "posts.id > 0", :references => :posts
+    )
     assert_equal aa.author.posts.count, aa.author.posts.length
   end
 
@@ -332,7 +344,9 @@ class EagerAssociationTest < ActiveRecord::TestCase
 
   def test_eager_association_loading_with_belongs_to_and_conditions_string_with_unquoted_table_name
     assert_nothing_raised do
-      Comment.find(:all, :include => :post, :conditions => ['posts.id = ?',4])
+      ActiveSupport::Deprecation.silence do
+        Comment.find(:all, :include => :post, :conditions => ['posts.id = ?',4])
+      end
     end
   end
 
@@ -351,7 +365,9 @@ class EagerAssociationTest < ActiveRecord::TestCase
   def test_eager_association_loading_with_belongs_to_and_conditions_string_with_quoted_table_name
     quoted_posts_id= Comment.connection.quote_table_name('posts') + '.' + Comment.connection.quote_column_name('id')
     assert_nothing_raised do
-      Comment.find(:all, :include => :post, :conditions => ["#{quoted_posts_id} = ?",4])
+      ActiveSupport::Deprecation.silence do
+        Comment.find(:all, :include => :post, :conditions => ["#{quoted_posts_id} = ?",4])
+      end
     end
   end
 
@@ -364,7 +380,9 @@ class EagerAssociationTest < ActiveRecord::TestCase
   def test_eager_association_loading_with_belongs_to_and_order_string_with_quoted_table_name
     quoted_posts_id= Comment.connection.quote_table_name('posts') + '.' + Comment.connection.quote_column_name('id')
     assert_nothing_raised do
-      Comment.find(:all, :include => :post, :order => quoted_posts_id)
+      ActiveSupport::Deprecation.silence do
+        Comment.find(:all, :include => :post, :order => quoted_posts_id)
+      end
     end
   end
 
@@ -528,22 +546,27 @@ class EagerAssociationTest < ActiveRecord::TestCase
   end
 
   def test_eager_with_has_many_and_limit_and_conditions_array_on_the_eagers
-    posts = Post.find(:all, :include => [ :author, :comments ], :limit => 2, :conditions => [ "authors.name = ?", 'David' ])
+    posts = ActiveSupport::Deprecation.silence do
+      Post.find(:all, :include => [ :author, :comments ], :limit => 2, :conditions => [ "authors.name = ?", 'David' ])
+    end
     assert_equal 2, posts.size
 
-    count = Post.count(:include => [ :author, :comments ], :limit => 2, :conditions => [ "authors.name = ?", 'David' ])
+    count = ActiveSupport::Deprecation.silence do
+      Post.count(:include => [ :author, :comments ], :limit => 2, :conditions => [ "authors.name = ?", 'David' ])
+    end
     assert_equal count, posts.size
   end
 
   def test_eager_with_has_many_and_limit_and_high_offset
-    posts = Post.find(:all, :include => [ :author, :comments ], :limit => 2, :offset => 10, :conditions => [ "authors.name = ?", 'David' ])
+    posts = Post.find(:all, :include => [ :author, :comments ], :limit => 2, :offset => 10, :conditions => { 'authors.name' => 'David' })
     assert_equal 0, posts.size
   end
 
   def test_eager_with_has_many_and_limit_and_high_offset_and_multiple_array_conditions
     assert_queries(1) do
       posts = Post.find(:all, :include => [ :author, :comments ], :limit => 2, :offset => 10,
-        :conditions => [ "authors.name = ? and comments.body = ?", 'David', 'go crazy' ])
+        :conditions => [ "authors.name = ? and comments.body = ?", 'David', 'go crazy' ],
+        :references => [:authors, :comments])
       assert_equal 0, posts.size
     end
   end
@@ -557,7 +580,7 @@ class EagerAssociationTest < ActiveRecord::TestCase
   end
 
   def test_count_eager_with_has_many_and_limit_and_high_offset
-    posts = Post.count(:all, :include => [ :author, :comments ], :limit => 2, :offset => 10, :conditions => [ "authors.name = ?", 'David' ])
+    posts = Post.count(:all, :include => [ :author, :comments ], :limit => 2, :offset => 10, :conditions => { 'authors.name' => 'David' })
     assert_equal 0, posts
   end
 
@@ -569,7 +592,7 @@ class EagerAssociationTest < ActiveRecord::TestCase
   def test_eager_count_performed_on_a_has_many_association_with_multi_table_conditional
     author = authors(:david)
     author_posts_without_comments = author.posts.select { |post| post.comments.blank? }
-    assert_equal author_posts_without_comments.size, author.posts.count(:all, :include => :comments, :conditions => 'comments.id is null')
+    assert_equal author_posts_without_comments.size, author.posts.count(:all, :include => :comments, :conditions => 'comments.id is null', :references => :comments)
   end
 
   def test_eager_count_performed_on_a_has_many_through_association_with_multi_table_conditional
@@ -608,6 +631,7 @@ class EagerAssociationTest < ActiveRecord::TestCase
     posts = authors(:david).posts.find(:all,
       :include    => :comments,
       :conditions => "comments.body like 'Normal%' OR comments.#{QUOTED_TYPE}= 'SpecialComment'",
+      :references => :comments,
       :limit      => 2
     )
     assert_equal 2, posts.size
@@ -615,6 +639,7 @@ class EagerAssociationTest < ActiveRecord::TestCase
     count = Post.count(
       :include    => [ :comments, :author ],
       :conditions => "authors.name = 'David' AND (comments.body like 'Normal%' OR comments.#{QUOTED_TYPE}= 'SpecialComment')",
+      :references => [:authors, :comments],
       :limit      => 2
     )
     assert_equal count, posts.size
@@ -624,7 +649,8 @@ class EagerAssociationTest < ActiveRecord::TestCase
     posts = nil
     Post.send(:with_scope, :find => {
       :include    => :comments,
-      :conditions => "comments.body like 'Normal%' OR comments.#{QUOTED_TYPE}= 'SpecialComment'"
+      :conditions => "comments.body like 'Normal%' OR comments.#{QUOTED_TYPE}= 'SpecialComment'",
+      :references => :comments
     }) do
       posts = authors(:david).posts.find(:all, :limit => 2)
       assert_equal 2, posts.size
@@ -632,7 +658,8 @@ class EagerAssociationTest < ActiveRecord::TestCase
 
     Post.send(:with_scope, :find => {
       :include    => [ :comments, :author ],
-      :conditions => "authors.name = 'David' AND (comments.body like 'Normal%' OR comments.#{QUOTED_TYPE}= 'SpecialComment')"
+      :conditions => "authors.name = 'David' AND (comments.body like 'Normal%' OR comments.#{QUOTED_TYPE}= 'SpecialComment')",
+      :references => [:authors, :comments]
     }) do
       count = Post.count(:limit => 2)
       assert_equal count, posts.size
@@ -644,6 +671,7 @@ class EagerAssociationTest < ActiveRecord::TestCase
       posts = authors(:david).posts.find(:all,
         :include    => :comments,
         :conditions => "comments.body like 'Normal%' OR comments.#{QUOTED_TYPE}= 'SpecialComment'",
+        :references => :comments,
         :limit      => 2
       )
       assert_equal 2, posts.size
@@ -651,6 +679,7 @@ class EagerAssociationTest < ActiveRecord::TestCase
       count = Post.count(
         :include    => [ :comments, :author ],
         :conditions => "authors.name = 'David' AND (comments.body like 'Normal%' OR comments.#{QUOTED_TYPE}= 'SpecialComment')",
+        :references => [:authors, :comments],
         :limit      => 2
       )
       assert_equal count, posts.size
@@ -658,9 +687,15 @@ class EagerAssociationTest < ActiveRecord::TestCase
   end
 
   def test_eager_with_scoped_order_using_association_limiting_without_explicit_scope
-    posts_with_explicit_order = Post.find(:all, :conditions => 'comments.id is not null', :include => :comments, :order => 'posts.id DESC', :limit => 2)
+    posts_with_explicit_order = Post.find(
+      :all, :conditions => 'comments.id is not null', :references => :comments,
+      :include => :comments, :order => 'posts.id DESC', :limit => 2
+    )
     posts_with_scoped_order = Post.send(:with_scope, :find => {:order => 'posts.id DESC'}) do
-      Post.find(:all, :conditions => 'comments.id is not null', :include => :comments, :limit => 2)
+      Post.find(
+        :all, :conditions => 'comments.id is not null',
+        :references => :comments, :include => :comments, :limit => 2
+      )
     end
     assert_equal posts_with_explicit_order, posts_with_scoped_order
   end
@@ -773,17 +808,49 @@ class EagerAssociationTest < ActiveRecord::TestCase
   end
 
   def test_limited_eager_with_order
-    assert_equal posts(:thinking, :sti_comments), Post.find(:all, :include => [:author, :comments], :conditions => "authors.name = 'David'", :order => 'UPPER(posts.title)', :limit => 2, :offset => 1)
-    assert_equal posts(:sti_post_and_comments, :sti_comments), Post.find(:all, :include => [:author, :comments], :conditions => "authors.name = 'David'", :order => 'UPPER(posts.title) DESC', :limit => 2, :offset => 1)
+    assert_equal(
+      posts(:thinking, :sti_comments),
+      Post.find(
+        :all, :include => [:author, :comments], :conditions => { 'authors.name' => 'David' },
+        :order => 'UPPER(posts.title)', :limit => 2, :offset => 1
+      )
+    )
+    assert_equal(
+      posts(:sti_post_and_comments, :sti_comments),
+      Post.find(
+        :all, :include => [:author, :comments], :conditions => { 'authors.name' => 'David' },
+        :order => 'UPPER(posts.title) DESC', :limit => 2, :offset => 1
+      )
+    )
   end
 
   def test_limited_eager_with_multiple_order_columns
-    assert_equal posts(:thinking, :sti_comments), Post.find(:all, :include => [:author, :comments], :conditions => "authors.name = 'David'", :order => ['UPPER(posts.title)', 'posts.id'], :limit => 2, :offset => 1)
-    assert_equal posts(:sti_post_and_comments, :sti_comments), Post.find(:all, :include => [:author, :comments], :conditions => "authors.name = 'David'", :order => ['UPPER(posts.title) DESC', 'posts.id'], :limit => 2, :offset => 1)
+    assert_equal(
+      posts(:thinking, :sti_comments),
+      Post.find(
+        :all, :include => [:author, :comments], :conditions => { 'authors.name' => 'David' },
+        :order => ['UPPER(posts.title)', 'posts.id'], :limit => 2, :offset => 1
+      )
+    )
+    assert_equal(
+      posts(:sti_post_and_comments, :sti_comments),
+      Post.find(
+        :all, :include => [:author, :comments], :conditions => { 'authors.name' => 'David' },
+        :order => ['UPPER(posts.title) DESC', 'posts.id'], :limit => 2, :offset => 1
+      )
+    )
   end
 
   def test_limited_eager_with_numeric_in_association
-    assert_equal people(:david, :susan), Person.find(:all, :include => [:readers, :primary_contact, :number1_fan], :conditions => "number1_fans_people.first_name like 'M%'", :order => 'people.id', :limit => 2, :offset => 0)
+    assert_equal(
+      people(:david, :susan),
+      Person.find(
+        :all, :include => [:readers, :primary_contact, :number1_fan],
+        :conditions => "number1_fans_people.first_name like 'M%'",
+        :references => :number1_fans_people,
+        :order => 'people.id', :limit => 2, :offset => 0
+      )
+    )
   end
 
   def test_preload_with_interpolation
@@ -898,11 +965,11 @@ class EagerAssociationTest < ActiveRecord::TestCase
 
   def test_count_with_include
     if current_adapter?(:SybaseAdapter)
-      assert_equal 3, authors(:david).posts_with_comments.count(:conditions => "len(comments.body) > 15")
+      assert_equal 3, authors(:david).posts_with_comments.count(:conditions => "len(comments.body) > 15", :references => :comments)
     elsif current_adapter?(:OpenBaseAdapter)
-      assert_equal 3, authors(:david).posts_with_comments.count(:conditions => "length(FETCHBLOB(comments.body)) > 15")
+      assert_equal 3, authors(:david).posts_with_comments.count(:conditions => "length(FETCHBLOB(comments.body)) > 15", :references => :comments)
     else
-      assert_equal 3, authors(:david).posts_with_comments.count(:conditions => "length(comments.body) > 15")
+      assert_equal 3, authors(:david).posts_with_comments.count(:conditions => "length(comments.body) > 15", :references => :comments)
     end
   end
 
@@ -913,7 +980,7 @@ class EagerAssociationTest < ActiveRecord::TestCase
   end
 
   def test_conditions_on_join_table_with_include_and_limit
-    assert_equal 3, Developer.find(:all, :include => 'projects', :conditions => 'developers_projects.access_level = 1', :limit => 5).size
+    assert_equal 3, Developer.find(:all, :include => 'projects', :conditions => { 'developers_projects.access_level' => 1 }, :limit => 5).size
   end
 
   def test_order_on_join_table_with_include_and_limit
diff --git a/activerecord/test/cases/associations/has_and_belongs_to_many_associations_test.rb b/activerecord/test/cases/associations/has_and_belongs_to_many_associations_test.rb
index 510411ecb2..f457dfb9b3 100644
--- a/activerecord/test/cases/associations/has_and_belongs_to_many_associations_test.rb
+++ b/activerecord/test/cases/associations/has_and_belongs_to_many_associations_test.rb
@@ -679,7 +679,13 @@ class HasAndBelongsToManyAssociationsTest < ActiveRecord::TestCase
   end
 
   def test_join_table_alias
-    assert_equal 3, Developer.find(:all, :include => {:projects => :developers}, :conditions => 'developers_projects_join.joined_on IS NOT NULL').size
+    assert_equal(
+      3,
+      Developer.find(
+        :all, :include => {:projects => :developers}, :references => :developers_projects_join,
+        :conditions => 'developers_projects_join.joined_on IS NOT NULL'
+      ).size
+    )
   end
 
   def test_join_with_group
@@ -689,7 +695,13 @@ class HasAndBelongsToManyAssociationsTest < ActiveRecord::TestCase
     end
     Project.columns.each { |c| group << "projects.#{c.name}" }
 
-    assert_equal 3, Developer.find(:all, :include => {:projects => :developers}, :conditions => 'developers_projects_join.joined_on IS NOT NULL', :group => group.join(",")).size
+    assert_equal(
+      3,
+      Developer.find(
+        :all, :include => {:projects => :developers}, :conditions => 'developers_projects_join.joined_on IS NOT NULL',
+        :references => :developers_projects_join, :group => group.join(",")
+      ).size
+    )
   end
 
   def test_find_grouped
diff --git a/activerecord/test/cases/associations/has_many_through_associations_test.rb b/activerecord/test/cases/associations/has_many_through_associations_test.rb
index c7bc275cf6..4612bc2618 100644
--- a/activerecord/test/cases/associations/has_many_through_associations_test.rb
+++ b/activerecord/test/cases/associations/has_many_through_associations_test.rb
@@ -847,7 +847,7 @@ class HasManyThroughAssociationsTest < ActiveRecord::TestCase
 
   def test_preloading_empty_through_association_via_joins
     person = Person.create!(:first_name => "Gaga")
-    person = Person.where(:id => person.id).where('readers.id = 1 or 1=1').includes(:posts).to_a.first
+    person = Person.where(:id => person.id).where('readers.id = 1 or 1=1').references(:readers).includes(:posts).to_a.first
 
     assert person.posts.loaded?, 'person.posts should be loaded'
     assert_equal [], person.posts
diff --git a/activerecord/test/cases/associations/join_model_test.rb b/activerecord/test/cases/associations/join_model_test.rb
index 995afef796..301755249c 100644
--- a/activerecord/test/cases/associations/join_model_test.rb
+++ b/activerecord/test/cases/associations/join_model_test.rb
@@ -362,7 +362,7 @@ class AssociationsJoinModelTest < ActiveRecord::TestCase
     end
 
     assert_raise ActiveRecord::EagerLoadPolymorphicError do
-      tags(:general).taggings.find(:all, :include => :taggable, :conditions => 'bogus_table.column = 1')
+      tags(:general).taggings.find(:all, :include => :taggable, :references => :bogus_table, :conditions => 'bogus_table.column = 1')
     end
   end
 
diff --git a/activerecord/test/cases/associations/nested_through_associations_test.rb b/activerecord/test/cases/associations/nested_through_associations_test.rb
index f920e09410..03d99d19f6 100644
--- a/activerecord/test/cases/associations/nested_through_associations_test.rb
+++ b/activerecord/test/cases/associations/nested_through_associations_test.rb
@@ -505,7 +505,7 @@ class NestedThroughAssociationsTest < ActiveRecord::TestCase
   def test_nested_has_many_through_with_conditions_on_through_associations_preload_via_joins
     # Pointless condition to force single-query loading
     assert_includes_and_joins_equal(
-      Author.where('tags.id = tags.id'),
+      Author.where('tags.id = tags.id').references(:tags),
       [authors(:bob)], :misc_post_first_blue_tags
     )
   end
@@ -526,7 +526,7 @@ class NestedThroughAssociationsTest < ActiveRecord::TestCase
   def test_nested_has_many_through_with_conditions_on_source_associations_preload_via_joins
     # Pointless condition to force single-query loading
     assert_includes_and_joins_equal(
-      Author.where('tags.id = tags.id'),
+      Author.where('tags.id = tags.id').references(:tags),
       [authors(:bob)], :misc_post_first_blue_tags_2
     )
   end
diff --git a/activerecord/test/cases/associations_test.rb b/activerecord/test/cases/associations_test.rb
index efe71d1771..017905e0ac 100644
--- a/activerecord/test/cases/associations_test.rb
+++ b/activerecord/test/cases/associations_test.rb
@@ -29,7 +29,7 @@ class AssociationsTest < ActiveRecord::TestCase
     molecule.electrons.create(:name => 'electron_1')
     molecule.electrons.create(:name => 'electron_2')
 
-    liquids = Liquid.includes(:molecules => :electrons).where('molecules.id is not null')
+    liquids = Liquid.includes(:molecules => :electrons).references(:molecules).where('molecules.id is not null')
     assert_equal 1, liquids[0].molecules.length
   end
 
@@ -129,6 +129,11 @@ class AssociationsTest < ActiveRecord::TestCase
     end
   end
 
+  def test_association_with_references
+    firm = companies(:first_firm)
+    assert_equal ['foo'], firm.association_with_references.scoped.references_values
+  end
+
 end
 
 class AssociationProxyTest < ActiveRecord::TestCase
diff --git a/activerecord/test/cases/calculations_test.rb b/activerecord/test/cases/calculations_test.rb
index 66c801ca75..7c9ebf528e 100644
--- a/activerecord/test/cases/calculations_test.rb
+++ b/activerecord/test/cases/calculations_test.rb
@@ -49,11 +49,11 @@ class CalculationsTest < ActiveRecord::TestCase
   end
 
   def test_should_get_maximum_of_field_with_include
-    assert_equal 55, Account.maximum(:credit_limit, :include => :firm, :conditions => "companies.name != 'Summit'")
+    assert_equal 55, Account.maximum(:credit_limit, :include => :firm, :references => :companies, :conditions => "companies.name != 'Summit'")
   end
 
   def test_should_get_maximum_of_field_with_scoped_include
-    Account.send :with_scope, :find => { :include => :firm, :conditions => "companies.name != 'Summit'" } do
+    Account.send :with_scope, :find => { :include => :firm, :references => :companies, :conditions => "companies.name != 'Summit'" } do
       assert_equal 55, Account.maximum(:credit_limit)
     end
   end
@@ -270,7 +270,7 @@ class CalculationsTest < ActiveRecord::TestCase
   end
 
   def test_should_not_modify_options_when_using_includes
-    options = {:conditions => 'companies.id > 1', :include => :firm}
+    options = {:conditions => 'companies.id > 1', :include => :firm, :references => :companies}
     options_copy = options.dup
 
     Account.count(:all, options)
diff --git a/activerecord/test/cases/finder_test.rb b/activerecord/test/cases/finder_test.rb
index 4514a26e57..7d80a56858 100644
--- a/activerecord/test/cases/finder_test.rb
+++ b/activerecord/test/cases/finder_test.rb
@@ -1119,10 +1119,10 @@ class FinderTest < ActiveRecord::TestCase
   end
 
   def test_find_with_order_on_included_associations_with_construct_finder_sql_for_association_limiting_and_is_distinct
-    assert_equal 2, Post.find(:all, :include => { :authors => :author_address }, :order => ' author_addresses.id DESC ', :limit => 2).size
+    assert_equal 2, Post.find(:all, :include => { :authors => :author_address }, :order => 'author_addresses.id DESC ', :limit => 2).size
 
     assert_equal 3, Post.find(:all, :include => { :author => :author_address, :authors => :author_address},
-                              :order => ' author_addresses_authors.id DESC ', :limit => 3).size
+                              :order => 'author_addresses_authors.id DESC ', :limit => 3).size
   end
 
   def test_find_with_nil_inside_set_passed_for_one_attribute
@@ -1149,7 +1149,10 @@ class FinderTest < ActiveRecord::TestCase
   end
 
   def test_with_limiting_with_custom_select
-    posts = Post.find(:all, :include => :author, :select => ' posts.*, authors.id as "author_id"', :limit => 3, :order => 'posts.id')
+    posts = Post.find(
+      :all, :include => :author, :select => ' posts.*, authors.id as "author_id"',
+      :references => :authors, :limit => 3, :order => 'posts.id'
+    )
     assert_equal 3, posts.size
     assert_equal [0, 1, 1], posts.map(&:author_id).sort
   end
diff --git a/activerecord/test/cases/method_scoping_test.rb b/activerecord/test/cases/method_scoping_test.rb
index 0ab4f30363..ebf6e26385 100644
--- a/activerecord/test/cases/method_scoping_test.rb
+++ b/activerecord/test/cases/method_scoping_test.rb
@@ -104,7 +104,7 @@ class MethodScopingTest < ActiveRecord::TestCase
   def test_scoped_find_include
     # with the include, will retrieve only developers for the given project
     scoped_developers = Developer.send(:with_scope, :find => { :include => :projects }) do
-      Developer.find(:all, :conditions => 'projects.id = 2')
+      Developer.find(:all, :conditions => { 'projects.id' => 2 })
     end
     assert scoped_developers.include?(developers(:david))
     assert !scoped_developers.include?(developers(:jamis))
@@ -204,7 +204,7 @@ class MethodScopingTest < ActiveRecord::TestCase
   def test_scoped_count_include
     # with the include, will retrieve only developers for the given project
     Developer.send(:with_scope, :find => { :include => :projects }) do
-      assert_equal 1, Developer.count(:conditions => 'projects.id = 2')
+      assert_equal 1, Developer.count(:conditions => { 'projects.id' => 2 })
     end
   end
 
@@ -339,7 +339,7 @@ class NestedScopingTest < ActiveRecord::TestCase
 
   def test_nested_scoped_find_include
     Developer.send(:with_scope, :find => { :include => :projects }) do
-      Developer.send(:with_scope, :find => { :conditions => "projects.id = 2" }) do
+      Developer.send(:with_scope, :find => { :conditions => { 'projects.id' => 2 } }) do
         assert_nothing_raised { Developer.find(1) }
         assert_equal('David', Developer.find(:first).name)
       end
@@ -348,7 +348,7 @@ class NestedScopingTest < ActiveRecord::TestCase
 
   def test_nested_scoped_find_merged_include
     # :include's remain unique and don't "double up" when merging
-    Developer.send(:with_scope, :find => { :include => :projects, :conditions => "projects.id = 2" }) do
+    Developer.send(:with_scope, :find => { :include => :projects, :conditions => { 'projects.id' => 2 } }) do
       Developer.send(:with_scope, :find => { :include => :projects }) do
         assert_equal 1, Developer.scoped.includes_values.uniq.length
         assert_equal 'David', Developer.find(:first).name
@@ -356,7 +356,7 @@ class NestedScopingTest < ActiveRecord::TestCase
     end
 
     # the nested scope doesn't remove the first :include
-    Developer.send(:with_scope, :find => { :include => :projects, :conditions => "projects.id = 2" }) do
+    Developer.send(:with_scope, :find => { :include => :projects, :conditions => { 'projects.id' => 2 } }) do
       Developer.send(:with_scope, :find => { :include => [] }) do
         assert_equal 1, Developer.scoped.includes_values.uniq.length
         assert_equal('David', Developer.find(:first).name)
@@ -364,7 +364,7 @@ class NestedScopingTest < ActiveRecord::TestCase
     end
 
     # mixing array and symbol include's will merge correctly
-    Developer.send(:with_scope, :find => { :include => [:projects], :conditions => "projects.id = 2" }) do
+    Developer.send(:with_scope, :find => { :include => [:projects], :conditions => { 'projects.id' => 2 } }) do
       Developer.send(:with_scope, :find => { :include => :projects }) do
         assert_equal 1, Developer.scoped.includes_values.uniq.length
         assert_equal('David', Developer.find(:first).name)
diff --git a/activerecord/test/cases/modules_test.rb b/activerecord/test/cases/modules_test.rb
index a2041af16a..f7a5d05582 100644
--- a/activerecord/test/cases/modules_test.rb
+++ b/activerecord/test/cases/modules_test.rb
@@ -72,7 +72,7 @@ class ModulesTest < ActiveRecord::TestCase
     clients = []
 
     assert_nothing_raised NameError, "Should be able to resolve all class constants via reflection" do
-      clients << MyApplication::Business::Client.find(3, :include => {:firm => :account}, :conditions => 'accounts.id IS NOT NULL')
+      clients << MyApplication::Business::Client.find(3, :include => {:firm => :account}, :conditions => 'accounts.id IS NOT NULL', :references => :accounts)
       clients << MyApplication::Business::Client.find(3, :include => {:firm => :account})
     end
 
diff --git a/activerecord/test/cases/reflection_test.rb b/activerecord/test/cases/reflection_test.rb
index 7fd15027eb..297fb56570 100644
--- a/activerecord/test/cases/reflection_test.rb
+++ b/activerecord/test/cases/reflection_test.rb
@@ -189,8 +189,8 @@ class ReflectionTest < ActiveRecord::TestCase
 
   def test_reflection_of_all_associations
     # FIXME these assertions bust a lot
-    assert_equal 37, Firm.reflect_on_all_associations.size
-    assert_equal 27, Firm.reflect_on_all_associations(:has_many).size
+    assert_equal 38, Firm.reflect_on_all_associations.size
+    assert_equal 28, Firm.reflect_on_all_associations(:has_many).size
     assert_equal 10, Firm.reflect_on_all_associations(:has_one).size
     assert_equal 0, Firm.reflect_on_all_associations(:belongs_to).size
   end
diff --git a/activerecord/test/cases/relation_scoping_test.rb b/activerecord/test/cases/relation_scoping_test.rb
index 227b846c53..edf38cb7a3 100644
--- a/activerecord/test/cases/relation_scoping_test.rb
+++ b/activerecord/test/cases/relation_scoping_test.rb
@@ -106,7 +106,7 @@ class RelationScopingTest < ActiveRecord::TestCase
   def test_scoped_find_include
     # with the include, will retrieve only developers for the given project
     scoped_developers = Developer.includes(:projects).scoping do
-      Developer.where('projects.id = 2').all
+      Developer.where('projects.id' => 2).all
     end
     assert scoped_developers.include?(developers(:david))
     assert !scoped_developers.include?(developers(:jamis))
diff --git a/activerecord/test/cases/relation_test.rb b/activerecord/test/cases/relation_test.rb
index b93a719687..ac6dee3c6a 100644
--- a/activerecord/test/cases/relation_test.rb
+++ b/activerecord/test/cases/relation_test.rb
@@ -148,5 +148,11 @@ module ActiveRecord
       relation = relation.references(:foo).references(:foo)
       assert_equal ['foo'], relation.references_values
     end
+
+    def test_apply_finder_options_takes_references
+      relation = Relation.new :a, :b
+      relation = relation.apply_finder_options(:references => :foo)
+      assert_equal ['foo'], relation.references_values
+    end
   end
 end
diff --git a/activerecord/test/cases/relations_test.rb b/activerecord/test/cases/relations_test.rb
index 6d75f31f35..5e19465253 100644
--- a/activerecord/test/cases/relations_test.rb
+++ b/activerecord/test/cases/relations_test.rb
@@ -184,12 +184,12 @@ class RelationTest < ActiveRecord::TestCase
   end
 
   def test_finding_with_complex_order_and_limit
-    tags = Tag.includes(:taggings).order("REPLACE('abc', taggings.taggable_type, taggings.taggable_type)").limit(1).to_a
+    tags = Tag.includes(:taggings).references(:taggings).order("REPLACE('abc', taggings.taggable_type, taggings.taggable_type)").limit(1).to_a
     assert_equal 1, tags.length
   end
 
   def test_finding_with_complex_order
-    tags = Tag.includes(:taggings).order("REPLACE('abc', taggings.taggable_type, taggings.taggable_type)").to_a
+    tags = Tag.includes(:taggings).references(:taggings).order("REPLACE('abc', taggings.taggable_type, taggings.taggable_type)").to_a
     assert_equal 3, tags.length
   end
 
@@ -1104,7 +1104,9 @@ class RelationTest < ActiveRecord::TestCase
       )
     )
 
-    assert scope.eager_loading?
+    assert_deprecated do
+      assert scope.eager_loading?
+    end
   end
 
   def test_ordering_with_extra_spaces
diff --git a/activerecord/test/models/author.rb b/activerecord/test/models/author.rb
index bfadfd9d75..d50e11d6c9 100644
--- a/activerecord/test/models/author.rb
+++ b/activerecord/test/models/author.rb
@@ -49,12 +49,12 @@ class Author < ActiveRecord::Base
   has_many :sti_post_comments, :through => :sti_posts, :source => :comments
 
   has_many :special_nonexistant_posts, :class_name => "SpecialPost", :conditions => "posts.body = 'nonexistant'"
-  has_many :special_nonexistant_post_comments, :through => :special_nonexistant_posts, :source => :comments, :conditions => "comments.post_id = 0"
+  has_many :special_nonexistant_post_comments, :through => :special_nonexistant_posts, :source => :comments, :conditions => { 'comments.post_id' => 0 }
   has_many :nonexistant_comments, :through => :posts
 
   has_many :hello_posts, :class_name => "Post", :conditions => "posts.body = 'hello'"
   has_many :hello_post_comments, :through => :hello_posts, :source => :comments
-  has_many :posts_with_no_comments, :class_name => 'Post', :conditions => 'comments.id is null', :include => :comments
+  has_many :posts_with_no_comments, :class_name => 'Post', :conditions => { 'comments.id' => nil }, :include => :comments
 
   has_many :hello_posts_with_hash_conditions, :class_name => "Post",
 :conditions => {:body => 'hello'}
diff --git a/activerecord/test/models/company.rb b/activerecord/test/models/company.rb
index fe9c465c81..d1a8a82786 100644
--- a/activerecord/test/models/company.rb
+++ b/activerecord/test/models/company.rb
@@ -88,6 +88,8 @@ class Firm < Company
   has_many :accounts
   has_many :unautosaved_accounts, :foreign_key => "firm_id", :class_name => 'Account', :autosave => false
 
+  has_many :association_with_references, :class_name => 'Client', :references => :foo
+
   def log
     @log ||= []
   end
diff --git a/activerecord/test/models/person.rb b/activerecord/test/models/person.rb
index 36eb08d02f..d2a0c6b40c 100644
--- a/activerecord/test/models/person.rb
+++ b/activerecord/test/models/person.rb
@@ -3,7 +3,8 @@ class Person < ActiveRecord::Base
   has_one  :reader
 
   has_many :posts, :through => :readers
-  has_many :posts_with_no_comments, :through => :readers, :source => :post, :include => :comments, :conditions => 'comments.id is null'
+  has_many :posts_with_no_comments, :through => :readers, :source => :post, :include => :comments,
+                                    :conditions => 'comments.id is null', :references => :comments
 
   has_many :references
   has_many :bad_references