From 437851ea02983e7f039de1a09a69ee32f7681134 Mon Sep 17 00:00:00 2001
From: Jon Leighton <j@jonathanleighton.com>
Date: Wed, 1 Aug 2012 21:42:38 +0100
Subject: Add `Relation#load`

This method explicitly loads the records and then returns `self`.

Rather than deciding between "do I want an array or a relation?",
most people are actually asking themselves "do I want to eager load
or lazy load?" Therefore, this method provides a way to explicitly
eager-load without having to switch from a `Relation` to an array.

Example:

    @posts = Post.where(published: true).load
---
 activerecord/CHANGELOG.md                  | 15 +++++++++++++++
 activerecord/lib/active_record/relation.rb | 14 ++++++++++++--
 activerecord/test/cases/relations_test.rb  |  8 ++++++++
 3 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/activerecord/CHANGELOG.md b/activerecord/CHANGELOG.md
index a58e761bd4..3d23e88256 100644
--- a/activerecord/CHANGELOG.md
+++ b/activerecord/CHANGELOG.md
@@ -1,5 +1,20 @@
 ## Rails 4.0.0 (unreleased) ##
 
+*   Add `Relation#load`
+
+    This method explicitly loads the records and then returns `self`.
+
+    Rather than deciding between "do I want an array or a relation?",
+    most people are actually asking themselves "do I want to eager load
+    or lazy load?" Therefore, this method provides a way to explicitly
+    eager-load without having to switch from a `Relation` to an array.
+
+    Example:
+
+        @posts = Post.where(published: true).load
+
+    *Jon Leighton*
+
 *   `:finder_sql` and `:counter_sql` options on collection associations
     are deprecated. Please transition to using scopes.
 
diff --git a/activerecord/lib/active_record/relation.rb b/activerecord/lib/active_record/relation.rb
index 3821c6122a..a8170dc489 100644
--- a/activerecord/lib/active_record/relation.rb
+++ b/activerecord/lib/active_record/relation.rb
@@ -466,11 +466,21 @@ module ActiveRecord
       where(primary_key => id_or_array).delete_all
     end
 
+    # Causes the records to be loaded from the database if they have not
+    # been loaded already. You can use this if for some reason you need
+    # to explicitly load some records before actually using them. The
+    # return value is the relation itself, not the records.
+    #
+    #   Post.where(published: true).load # => #<ActiveRecord::Relation>
+    def load
+      to_a # force reload
+      self
+    end
+
     # Forces reloading of relation.
     def reload
       reset
-      to_a # force reload
-      self
+      load
     end
 
     def reset
diff --git a/activerecord/test/cases/relations_test.rb b/activerecord/test/cases/relations_test.rb
index 4aa1977cf9..1fbd76bc03 100644
--- a/activerecord/test/cases/relations_test.rb
+++ b/activerecord/test/cases/relations_test.rb
@@ -1342,4 +1342,12 @@ class RelationTest < ActiveRecord::TestCase
     node = relation.arel.constraints.first.grep(Arel::Attributes::Attribute).first
     assert_equal table_alias, node.relation
   end
+
+  test '#load' do
+    relation = Post.all
+    assert_queries(1) do
+      assert_equal relation, relation.load
+    end
+    assert_no_queries { relation.to_a }
+  end
 end
-- 
cgit v1.2.3