activerecord 3.2.22.5 → 4.0.0.beta1

data/lib/active_record/relation/merger.rb

@@ -0,0 +1,133 @@
+require 'active_support/core_ext/hash/keys'
+require "set"
+
+module ActiveRecord
+  class Relation
+    class HashMerger # :nodoc:
+      attr_reader :relation, :hash
+
+      def initialize(relation, hash)
+        hash.assert_valid_keys(*Relation::VALUE_METHODS)
+
+        @relation = relation
+        @hash     = hash
+      end
+
+      def merge
+        Merger.new(relation, other).merge
+      end
+
+      # Applying values to a relation has some side effects. E.g.
+      # interpolation might take place for where values. So we should
+      # build a relation to merge in rather than directly merging
+      # the values.
+      def other
+        other = Relation.new(relation.klass, relation.table)
+        hash.each { |k, v|
+          if k == :joins
+            if Hash === v
+              other.joins!(v)
+            else
+              other.joins!(*v)
+            end
+          else
+            other.send("#{k}!", v)
+          end
+        }
+        other
+      end
+    end
+
+    class Merger # :nodoc:
+      attr_reader :relation, :values
+
+      def initialize(relation, other)
+        if other.default_scoped? && other.klass != relation.klass
+          other = other.with_default_scope
+        end
+
+        @relation = relation
+        @values   = other.values
+      end
+
+      NORMAL_VALUES = Relation::SINGLE_VALUE_METHODS +
+                      Relation::MULTI_VALUE_METHODS -
+                      [:where, :order, :bind, :reverse_order, :lock, :create_with, :reordering, :from] # :nodoc:
+
+      def normal_values
+        NORMAL_VALUES
+      end
+
+      def merge
+        normal_values.each do |name|
+          value = values[name]
+          relation.send("#{name}!", *value) unless value.blank?
+        end
+
+        merge_multi_values
+        merge_single_values
+
+        relation
+      end
+
+      private
+
+      def merge_multi_values
+        relation.where_values = merged_wheres
+        relation.bind_values  = merged_binds
+
+        if values[:reordering]
+          # override any order specified in the original relation
+          relation.reorder! values[:order]
+        elsif values[:order]
+          # merge in order_values from r
+          relation.order! values[:order]
+        end
+
+        relation.extend(*values[:extending]) unless values[:extending].blank?
+      end
+
+      def merge_single_values
+        relation.from_value          = values[:from] unless relation.from_value
+        relation.lock_value          = values[:lock] unless relation.lock_value
+        relation.reverse_order_value = values[:reverse_order]
+
+        unless values[:create_with].blank?
+          relation.create_with_value = (relation.create_with_value || {}).merge(values[:create_with])
+        end
+      end
+
+      def merged_binds
+        if values[:bind]
+          (relation.bind_values + values[:bind]).uniq(&:first)
+        else
+          relation.bind_values
+        end
+      end
+
+      def merged_wheres
+        values[:where] ||= []
+
+        if values[:where].empty? || relation.where_values.empty?
+          relation.where_values + values[:where]
+        else
+          # Remove equalities from the existing relation with a LHS which is
+          # present in the relation being merged in.
+
+          seen = Set.new
+          values[:where].each { |w|
+            if w.respond_to?(:operator) && w.operator == :==
+              seen << w.left
+            end
+          }
+
+          relation.where_values.reject { |w|
+            w.respond_to?(:operator) &&
+              w.operator == :== &&
+              seen.include?(w.left)
+          } + values[:where]
+        end
+      end
+    end
+  end
+end

data/lib/active_record/relation/predicate_builder.rb

@@ -1,63 +1,111 @@
 module ActiveRecord
   class PredicateBuilder # :nodoc:
-    def self.build_from_hash(engine, attributes, default_table, allow_table_name = true)
-      predicates = attributes.map do |column, value|
-        table = default_table
+    def self.build_from_hash(klass, attributes, default_table)
+      queries = []
 
-        if allow_table_name && value.is_a?(Hash)
-          table = Arel::Table.new(column, engine)
+      attributes.each do |column, value|
+        table = default_table
 
+        if value.is_a?(Hash)
           if value.empty?
-            '1 = 2'
+            queries << '1=0'
           else
-            build_from_hash(engine, value, table, false)
+            table       = Arel::Table.new(column, default_table.engine)
+            association = klass.reflect_on_association(column.to_sym)
+
+            value.each do |k, v|
+              queries.concat expand(association && association.klass, table, k, v)
+            end
           end
         else
           column = column.to_s
 
-          if allow_table_name && column.include?('.')
+          if column.include?('.')
             table_name, column = column.split('.', 2)
-            table = Arel::Table.new(table_name, engine)
+            table = Arel::Table.new(table_name, default_table.engine)
           end
 
-          attribute = table[column]
-
-          case value
-          when ActiveRecord::Relation
-            value = value.select(value.klass.arel_table[value.klass.primary_key]) if value.select_values.empty?
-            attribute.in(value.arel.ast)
-          when Array, ActiveRecord::Associations::CollectionProxy
-            values = value.to_a.map {|x| x.is_a?(ActiveRecord::Base) ? x.id : x}
-            ranges, values = values.partition {|v| v.is_a?(Range) || v.is_a?(Arel::Relation)}
-
-            array_predicates = ranges.map {|range| attribute.in(range)}
-
-            if values.include?(nil)
-              values = values.compact
-              if values.empty?
-                array_predicates << attribute.eq(nil)
-              else
-                array_predicates << attribute.in(values.compact).or(attribute.eq(nil))
-              end
+          queries.concat expand(klass, table, column, value)
+        end
+      end
+
+      queries
+    end
+
+    def self.expand(klass, table, column, value)
+      queries = []
+
+      # Find the foreign key when using queries such as:
+      # Post.where(author: author)
+      #
+      # For polymorphic relationships, find the foreign key and type:
+      # PriceEstimate.where(estimate_of: treasure)
+      if klass && value.class < Base && reflection = klass.reflect_on_association(column.to_sym)
+        if reflection.polymorphic?
+          queries << build(table[reflection.foreign_type], value.class.base_class)
+        end
+
+        column = reflection.foreign_key
+      end
+
+      queries << build(table[column.to_sym], value)
+      queries
+    end
+
+    def self.references(attributes)
+      attributes.map do |key, value|
+        if value.is_a?(Hash)
+          key
+        else
+          key = key.to_s
+          key.split('.').first if key.include?('.')
+        end
+      end.compact
+    end
+
+    private
+      def self.build(attribute, value)
+        case value
+        when Array
+          values = value.to_a.map {|x| x.is_a?(Base) ? x.id : x}
+          ranges, values = values.partition {|v| v.is_a?(Range)}
+
+          values_predicate = if values.include?(nil)
+            values = values.compact
+
+            case values.length
+            when 0
+              attribute.eq(nil)
+            when 1
+              attribute.eq(values.first).or(attribute.eq(nil))
             else
-              array_predicates << attribute.in(values)
+              attribute.in(values).or(attribute.eq(nil))
             end
-
-            array_predicates.inject {|composite, predicate| composite.or(predicate)}
-          when Range, Arel::Relation
-            attribute.in(value)
-          when ActiveRecord::Base
-            attribute.eq(value.id)
-          when Class
-            # FIXME: I think we need to deprecate this behavior
-            attribute.eq(value.name)
           else
-            attribute.eq(value)
+            attribute.in(values)
           end
+
+          array_predicates = ranges.map { |range| attribute.in(range) }
+          array_predicates << values_predicate
+          array_predicates.inject { |composite, predicate| composite.or(predicate) }
+        when ActiveRecord::Relation
+          value = value.select(value.klass.arel_table[value.klass.primary_key]) if value.select_values.empty?
+          attribute.in(value.arel.ast)
+        when Range
+          attribute.in(value)
+        when ActiveRecord::Base
+          attribute.eq(value.id)
+        when Class
+          # FIXME: I think we need to deprecate this behavior
+          attribute.eq(value.name)
+        when Integer, ActiveSupport::Duration
+          # Arel treats integers as literals, but they should be quoted when compared with strings
+          table = attribute.relation
+          column = table.engine.connection.schema_cache.columns_hash(table.name)[attribute.name.to_s]
+          attribute.eq(Arel::Nodes::SqlLiteral.new(table.engine.connection.quote(value, column)))
+        else
+          attribute.eq(value)
         end
       end
-
-      predicates.flatten
-    end
   end
 end

data/lib/active_record/relation/query_methods.rb

@@ -1,48 +1,183 @@
 require 'active_support/core_ext/array/wrap'
-require 'active_support/core_ext/object/blank'
 
 module ActiveRecord
   module QueryMethods
     extend ActiveSupport::Concern
 
-    attr_accessor :includes_values, :eager_load_values, :preload_values,
-                  :select_values, :group_values, :order_values, :joins_values,
-                  :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
+    # WhereChain objects act as placeholder for queries in which #where does not have any parameter.
+    # In this case, #where must be chained with either #not, #like, or #not_like to return a new relation.
+    class WhereChain
+      def initialize(scope)
+        @scope = scope
+      end
 
+      # Returns a new relation expressing WHERE + NOT condition according to
+      # the conditions in the arguments.
+      #
+      # +not+ accepts conditions as a string, array, or hash. See #where for
+      # more details on each format.
+      #
+      #    User.where.not("name = 'Jon'")
+      #    # SELECT * FROM users WHERE NOT (name = 'Jon')
+      #
+      #    User.where.not(["name = ?", "Jon"])
+      #    # SELECT * FROM users WHERE NOT (name = 'Jon')
+      #
+      #    User.where.not(name: "Jon")
+      #    # SELECT * FROM users WHERE name != 'Jon'
+      #
+      #    User.where.not(name: nil)
+      #    # SELECT * FROM users WHERE name IS NOT NULL
+      #
+      #    User.where.not(name: %w(Ko1 Nobu))
+      #    # SELECT * FROM users WHERE name NOT IN ('Ko1', 'Nobu')
+      #
+      #    User.where.not(name: "Jon", role: "admin")
+      #    # SELECT * FROM users WHERE name != 'Jon' AND role != 'admin'
+      #
+      def not(opts, *rest)
+        where_value = @scope.send(:build_where, opts, rest).map do |rel|
+          case rel
+          when Arel::Nodes::In
+            Arel::Nodes::NotIn.new(rel.left, rel.right)
+          when Arel::Nodes::Equality
+            Arel::Nodes::NotEqual.new(rel.left, rel.right)
+          when String
+            Arel::Nodes::Not.new(Arel::Nodes::SqlLiteral.new(rel))
+          else
+            Arel::Nodes::Not.new(rel)
+          end
+        end
+        @scope.where_values += where_value
+        @scope
+      end
+    end
+
+    Relation::MULTI_VALUE_METHODS.each do |name|
+      class_eval <<-CODE, __FILE__, __LINE__ + 1
+        def #{name}_values                   # def select_values
+          @values[:#{name}] || []            #   @values[:select] || []
+        end                                  # end
+                                             #
+        def #{name}_values=(values)          # def select_values=(values)
+          raise ImmutableRelation if @loaded #   raise ImmutableRelation if @loaded
+          @values[:#{name}] = values         #   @values[:select] = values
+        end                                  # end
+      CODE
+    end
+
+    (Relation::SINGLE_VALUE_METHODS - [:create_with]).each do |name|
+      class_eval <<-CODE, __FILE__, __LINE__ + 1
+        def #{name}_value                    # def readonly_value
+          @values[:#{name}]                  #   @values[:readonly]
+        end                                  # end
+      CODE
+    end
+
+    Relation::SINGLE_VALUE_METHODS.each do |name|
+      class_eval <<-CODE, __FILE__, __LINE__ + 1
+        def #{name}_value=(value)            # def readonly_value=(value)
+          raise ImmutableRelation if @loaded #   raise ImmutableRelation if @loaded
+          @values[:#{name}] = value          #   @values[:readonly] = value
+        end                                  # end
+      CODE
+    end
+
+    def create_with_value # :nodoc:
+      @values[:create_with] || {}
+    end
+
+    alias extensions extending_values
+
+    # Specify relationships to be included in the result set. For
+    # example:
+    #
+    #   users = User.includes(:address)
+    #   users.each do |user|
+    #     user.address.city
+    #   end
+    #
+    # allows you to access the +address+ attribute of the +User+ model without
+    # firing an additional query. This will often result in a
+    # performance improvement over a simple +join+.
+    #
+    # === conditions
+    #
+    # If you want to add conditions to your included models you'll have
+    # to explicitly reference them. For example:
+    #
+    #   User.includes(:posts).where('posts.name = ?', 'example')
+    #
+    # Will throw an error, but this will work:
+    #
+    #   User.includes(:posts).where('posts.name = ?', 'example').references(:posts)
     def includes(*args)
-      args.reject! {|a| a.blank? }
+      check_if_method_has_arguments!("includes", args)
+      spawn.includes!(*args)
+    end
 
-      return self if args.empty?
+    def includes!(*args) # :nodoc:
+      args.reject! {|a| a.blank? }
 
-      relation = clone
-      relation.includes_values = (relation.includes_values + args).flatten.uniq
-      relation
+      self.includes_values = (includes_values + args).flatten.uniq
+      self
     end
 
+    # Forces eager loading by performing a LEFT OUTER JOIN on +args+:
+    #
+    #   User.eager_load(:posts)
+    #   => SELECT "users"."id" AS t0_r0, "users"."name" AS t0_r1, ...
+    #   FROM "users" LEFT OUTER JOIN "posts" ON "posts"."user_id" =
+    #   "users"."id"
     def eager_load(*args)
-      return self if args.blank?
+      check_if_method_has_arguments!("eager_load", args)
+      spawn.eager_load!(*args)
+    end
 
-      relation = clone
-      relation.eager_load_values += args
-      relation
+    def eager_load!(*args) # :nodoc:
+      self.eager_load_values += args
+      self
     end
 
+    # Allows preloading of +args+, in the same way that +includes+ does:
+    #
+    #   User.preload(:posts)
+    #   => SELECT "posts".* FROM "posts" WHERE "posts"."user_id" IN (1, 2, 3)
     def preload(*args)
-      return self if args.blank?
+      check_if_method_has_arguments!("preload", args)
+      spawn.preload!(*args)
+    end
+
+    def preload!(*args) # :nodoc:
+      self.preload_values += args
+      self
+    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.
+    #
+    #   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)
+      check_if_method_has_arguments!("references", args)
+      spawn.references!(*args)
+    end
+
+    def references!(*args) # :nodoc:
+      args.flatten!
 
-      relation = clone
-      relation.preload_values += args
-      relation
+      self.references_values = (references_values + args.map!(&:to_s)).uniq
+      self
     end
 
     # Works in two unique ways.
     #
     # First: takes a block so it can be used just like Array#select.
     #
-    #   Model.scoped.select { |m| m.field == value }
+    #   Model.all.select { |m| m.field == value }
     #
     # This will build an array of objects from the database for the scope,
     # converting them into an array and iterating through them using Array#select.
@@ -50,8 +185,8 @@ module ActiveRecord
     # Second: Modifies the SELECT statement for the query so that only certain
     # fields are retrieved:
     #
-    #   >> Model.select(:field)
-    #   => [#<Model field:value>]
+    #   Model.select(:field)
+    #   # => [#<Model field:value>]
     #
     # Although in the above example it looks as though this method returns an
     # array, it actually returns a relation object and can have other query
@@ -59,38 +194,99 @@ module ActiveRecord
     #
     # The argument to the method can also be an array of fields.
     #
-    #   >> Model.select([:field, :other_field, :and_one_more])
-    #   => [#<Model field: "value", other_field: "value", and_one_more: "value">]
+    #   Model.select(:field, :other_field, :and_one_more)
+    #   # => [#<Model field: "value", other_field: "value", and_one_more: "value">]
     #
-    # Any attributes that do not have fields retrieved by a select
-    # will raise a ActiveModel::MissingAttributeError when the getter method for that attribute is used:
+    # You can also use one or more strings, which will be used unchanged as SELECT fields.
     #
-    #   >> Model.select(:field).first.other_field
-    #   => ActiveModel::MissingAttributeError: missing attribute: other_field
-    def select(value = Proc.new)
+    #   Model.select('field AS field_one', 'other_field AS field_two')
+    #   # => [#<Model field: "value", other_field: "value">]
+    #
+    # If an alias was specified, it will be accessible from the resulting objects:
+    #
+    #   Model.select('field AS field_one').first.field_one
+    #   # => "value"
+    #
+    # Accessing attributes of an object that do not have fields retrieved by a select
+    # will throw <tt>ActiveModel::MissingAttributeError</tt>:
+    #
+    #   Model.select(:field).first.other_field
+    #   # => ActiveModel::MissingAttributeError: missing attribute: other_field
+    def select(*fields)
       if block_given?
-        to_a.select {|*block_args| value.call(*block_args) }
+        to_a.select { |*block_args| yield(*block_args) }
       else
-        relation = clone
-        relation.select_values += Array.wrap(value)
-        relation
+        raise ArgumentError, 'Call this with at least one field' if fields.empty?
+        spawn.select!(*fields)
       end
     end
 
+    def select!(*fields) # :nodoc:
+      self.select_values += fields.flatten
+      self
+    end
+
+    # Allows to specify a group attribute:
+    #
+    #   User.group(:name)
+    #   => SELECT "users".* FROM "users" GROUP BY name
+    #
+    # Returns an array with distinct records based on the +group+ attribute:
+    #
+    #   User.select([:id, :name])
+    #   => [#<User id: 1, name: "Oscar">, #<User id: 2, name: "Oscar">, #<User id: 3, name: "Foo">
+    #
+    #   User.group(:name)
+    #   => [#<User id: 3, name: "Foo", ...>, #<User id: 2, name: "Oscar", ...>]
+    #
+    #   User.group('name AS grouped_name, age')
+    #   => [#<User id: 3, name: "Foo", age: 21, ...>, #<User id: 2, name: "Oscar", age: 21, ...>, #<User id: 5, name: "Foo", age: 23, ...>]
     def group(*args)
-      return self if args.blank?
+      check_if_method_has_arguments!("group", args)
+      spawn.group!(*args)
+    end
 
-      relation = clone
-      relation.group_values += args.flatten
-      relation
+    def group!(*args) # :nodoc:
+      args.flatten!
+
+      self.group_values += args
+      self
     end
 
+    # Allows to specify an order attribute:
+    #
+    #   User.order('name')
+    #   => SELECT "users".* FROM "users" ORDER BY name
+    #
+    #   User.order('name DESC')
+    #   => SELECT "users".* FROM "users" ORDER BY name DESC
+    #
+    #   User.order('name DESC, email')
+    #   => SELECT "users".* FROM "users" ORDER BY name DESC, email
+    #
+    #   User.order(:name)
+    #   => SELECT "users".* FROM "users" ORDER BY "users"."name" ASC
+    #
+    #   User.order(email: :desc)
+    #   => SELECT "users".* FROM "users" ORDER BY "users"."email" DESC
+    #
+    #   User.order(:name, email: :desc)
+    #   => SELECT "users".* FROM "users" ORDER BY "users"."name" ASC, "users"."email" DESC
     def order(*args)
-      return self if args.blank?
+      check_if_method_has_arguments!("order", args)
+      spawn.order!(*args)
+    end
+
+    def order!(*args) # :nodoc:
+      args.flatten!
+      validate_order_args args
+
+      references = args.reject { |arg| Arel::Node === arg }
+      references.map! { |arg| arg =~ /^([a-zA-Z]\w*)\.(\w+)/ && $1 }.compact!
+      references!(references) if references.any?
 
-      relation = clone
-      relation.order_values += args.flatten
-      relation
+      self.order_values = args + self.order_values
+      self
     end
 
     # Replaces any existing order defined on the relation with the specified order.
@@ -101,91 +297,346 @@ module ActiveRecord
     #
     #   User.order('email DESC').reorder('id ASC').order('name ASC')
     #
-    # generates a query with 'ORDER BY id ASC, name ASC'.
-    #
+    # generates a query with 'ORDER BY name ASC, id ASC'.
     def reorder(*args)
-      return self if args.blank?
+      check_if_method_has_arguments!("reorder", args)
+      spawn.reorder!(*args)
+    end
+
+    def reorder!(*args) # :nodoc:
+      args.flatten!
+      validate_order_args args
 
-      relation = clone
-      relation.reordering_value = true
-      relation.order_values = args.flatten
-      relation
+      self.reordering_value = true
+      self.order_values = args
+      self
     end
 
+    # Performs a joins on +args+:
+    #
+    #   User.joins(:posts)
+    #   => SELECT "users".* FROM "users" INNER JOIN "posts" ON "posts"."user_id" = "users"."id"
+    #
+    # You can use strings in order to customize your joins:
+    #
+    #   User.joins("LEFT JOIN bookmarks ON bookmarks.bookmarkable_type = 'Post' AND bookmarks.user_id = users.id")
+    #   => SELECT "users".* FROM "users" LEFT JOIN bookmarks ON bookmarks.bookmarkable_type = 'Post' AND bookmarks.user_id = users.id
     def joins(*args)
-      return self if args.compact.blank?
+      check_if_method_has_arguments!("joins", args)
+      spawn.joins!(*args.compact.flatten)
+    end
 
-      relation = clone
+    def joins!(*args) # :nodoc:
+      self.joins_values += args
+      self
+    end
 
-      args.flatten!
-      relation.joins_values += args
+    def bind(value)
+      spawn.bind!(value)
+    end
 
-      relation
+    def bind!(value) # :nodoc:
+      self.bind_values += [value]
+      self
     end
 
-    def bind(value)
-      relation = clone
-      relation.bind_values += [value]
-      relation
+    # Returns a new relation, which is the result of filtering the current relation
+    # according to the conditions in the arguments.
+    #
+    # #where accepts conditions in one of several formats. In the examples below, the resulting
+    # SQL is given as an illustration; the actual query generated may be different depending
+    # on the database adapter.
+    #
+    # === string
+    #
+    # A single string, without additional arguments, is passed to the query
+    # constructor as a SQL fragment, and used in the where clause of the query.
+    #
+    #    Client.where("orders_count = '2'")
+    #    # SELECT * from clients where orders_count = '2';
+    #
+    # Note that building your own string from user input may expose your application
+    # to injection attacks if not done properly. As an alternative, it is recommended
+    # to use one of the following methods.
+    #
+    # === array
+    #
+    # If an array is passed, then the first element of the array is treated as a template, and
+    # the remaining elements are inserted into the template to generate the condition.
+    # Active Record takes care of building the query to avoid injection attacks, and will
+    # convert from the ruby type to the database type where needed. Elements are inserted
+    # into the string in the order in which they appear.
+    #
+    #   User.where(["name = ? and email = ?", "Joe", "joe@example.com"])
+    #   # SELECT * FROM users WHERE name = 'Joe' AND email = 'joe@example.com';
+    #
+    # Alternatively, you can use named placeholders in the template, and pass a hash as the
+    # second element of the array. The names in the template are replaced with the corresponding
+    # values from the hash.
+    #
+    #   User.where(["name = :name and email = :email", { name: "Joe", email: "joe@example.com" }])
+    #   # SELECT * FROM users WHERE name = 'Joe' AND email = 'joe@example.com';
+    #
+    # This can make for more readable code in complex queries.
+    #
+    # Lastly, you can use sprintf-style % escapes in the template. This works slightly differently
+    # than the previous methods; you are responsible for ensuring that the values in the template
+    # are properly quoted. The values are passed to the connector for quoting, but the caller
+    # is responsible for ensuring they are enclosed in quotes in the resulting SQL. After quoting,
+    # the values are inserted using the same escapes as the Ruby core method <tt>Kernel::sprintf</tt>.
+    #
+    #   User.where(["name = '%s' and email = '%s'", "Joe", "joe@example.com"])
+    #   # SELECT * FROM users WHERE name = 'Joe' AND email = 'joe@example.com';
+    #
+    # If #where is called with multiple arguments, these are treated as if they were passed as
+    # the elements of a single array.
+    #
+    #   User.where("name = :name and email = :email", { name: "Joe", email: "joe@example.com" })
+    #   # SELECT * FROM users WHERE name = 'Joe' AND email = 'joe@example.com';
+    #
+    # When using strings to specify conditions, you can use any operator available from
+    # the database. While this provides the most flexibility, you can also unintentionally introduce
+    # dependencies on the underlying database. If your code is intended for general consumption,
+    # test with multiple database backends.
+    #
+    # === hash
+    #
+    # #where will also accept a hash condition, in which the keys are fields and the values
+    # are values to be searched for.
+    #
+    # Fields can be symbols or strings. Values can be single values, arrays, or ranges.
+    #
+    #    User.where({ name: "Joe", email: "joe@example.com" })
+    #    # SELECT * FROM users WHERE name = 'Joe' AND email = 'joe@example.com'
+    #
+    #    User.where({ name: ["Alice", "Bob"]})
+    #    # SELECT * FROM users WHERE name IN ('Alice', 'Bob')
+    #
+    #    User.where({ created_at: (Time.now.midnight - 1.day)..Time.now.midnight })
+    #    # SELECT * FROM users WHERE (created_at BETWEEN '2012-06-09 07:00:00.000000' AND '2012-06-10 07:00:00.000000')
+    #
+    # In the case of a belongs_to relationship, an association key can be used
+    # to specify the model if an ActiveRecord object is used as the value.
+    #
+    #    author = Author.find(1)
+    #
+    #    # The following queries will be equivalent:
+    #    Post.where(author: author)
+    #    Post.where(author_id: author)
+    #
+    # This also works with polymorphic belongs_to relationships:
+    #
+    #    treasure = Treasure.create(name: 'gold coins')
+    #    treasure.price_estimates << PriceEstimate.create(price: 125)
+    #
+    #    # The following queries will be equivalent:
+    #    PriceEstimate.where(estimate_of: treasure)
+    #    PriceEstimate.where(estimate_of_type: 'Treasure', estimate_of_id: treasure)
+    #
+    # === Joins
+    #
+    # If the relation is the result of a join, you may create a condition which uses any of the
+    # tables in the join. For string and array conditions, use the table name in the condition.
+    #
+    #    User.joins(:posts).where("posts.created_at < ?", Time.now)
+    #
+    # For hash conditions, you can either use the table name in the key, or use a sub-hash.
+    #
+    #    User.joins(:posts).where({ "posts.published" => true })
+    #    User.joins(:posts).where({ posts: { published: true } })
+    #
+    # === no argument
+    #
+    # If no argument is passed, #where returns a new instance of WhereChain, that
+    # can be chained with #not to return a new relation that negates the where clause.
+    #
+    #    User.where.not(name: "Jon")
+    #    # SELECT * FROM users WHERE name != 'Jon'
+    #
+    # See WhereChain for more details on #not.
+    #
+    # === blank condition
+    #
+    # If the condition is any blank-ish object, then #where is a no-op and returns
+    # the current relation.
+    def where(opts = :chain, *rest)
+      if opts == :chain
+        WhereChain.new(spawn)
+      elsif opts.blank?
+        self
+      else
+        spawn.where!(opts, *rest)
+      end
     end
 
-    def where(opts, *rest)
-      return self if opts.blank?
+    def where!(opts = :chain, *rest) # :nodoc:
+      if opts == :chain
+        WhereChain.new(self)
+      else
+        references!(PredicateBuilder.references(opts)) if Hash === opts
 
-      relation = clone
-      relation.where_values += build_where(opts, rest)
-      relation
+        self.where_values += build_where(opts, rest)
+        self
+      end
     end
 
+    # Allows to specify a HAVING clause. Note that you can't use HAVING
+    # without also specifying a GROUP clause.
+    #
+    #   Order.having('SUM(price) > 30').group('user_id')
     def having(opts, *rest)
-      return self if opts.blank?
+      opts.blank? ? self : spawn.having!(opts, *rest)
+      spawn.having!(opts, *rest)
+    end
+
+    def having!(opts, *rest) # :nodoc:
+      references!(PredicateBuilder.references(opts)) if Hash === opts
 
-      relation = clone
-      relation.having_values += build_where(opts, rest)
-      relation
+      self.having_values += build_where(opts, rest)
+      self
     end
 
+    # Specifies a limit for the number of records to retrieve.
+    #
+    #   User.limit(10) # generated SQL has 'LIMIT 10'
+    #
+    #   User.limit(10).limit(20) # generated SQL has 'LIMIT 20'
     def limit(value)
-      relation = clone
-      relation.limit_value = value
-      relation
+      spawn.limit!(value)
+    end
+
+    def limit!(value) # :nodoc:
+      self.limit_value = value
+      self
     end
 
+    # Specifies the number of rows to skip before returning rows.
+    #
+    #   User.offset(10) # generated SQL has "OFFSET 10"
+    #
+    # Should be used with order.
+    #
+    #   User.offset(10).order("name ASC")
     def offset(value)
-      relation = clone
-      relation.offset_value = value
-      relation
+      spawn.offset!(value)
     end
 
+    def offset!(value) # :nodoc:
+      self.offset_value = value
+      self
+    end
+
+    # Specifies locking settings (default to +true+). For more information
+    # on locking, please see +ActiveRecord::Locking+.
     def lock(locks = true)
-      relation = clone
+      spawn.lock!(locks)
+    end
 
+    def lock!(locks = true) # :nodoc:
       case locks
       when String, TrueClass, NilClass
-        relation.lock_value = locks || true
+        self.lock_value = locks || true
       else
-        relation.lock_value = false
+        self.lock_value = false
       end
 
-      relation
+      self
     end
 
+    # Returns a chainable relation with zero records, specifically an
+    # instance of the <tt>ActiveRecord::NullRelation</tt> class.
+    #
+    # The returned <tt>ActiveRecord::NullRelation</tt> inherits from Relation and implements the
+    # Null Object pattern. It is an object with defined null behavior and always returns an empty
+    # array of records without quering the database.
+    #
+    # Any subsequent condition chained to the returned relation will continue
+    # generating an empty relation and will not fire any query to the database.
+    #
+    # Used in cases where a method or scope could return zero records but the
+    # result needs to be chainable.
+    #
+    # For example:
+    #
+    #   @posts = current_user.visible_posts.where(name: params[:name])
+    #   # => the visible_posts method is expected to return a chainable Relation
+    #
+    #   def visible_posts
+    #     case role
+    #     when 'Country Manager'
+    #       Post.where(country: country)
+    #     when 'Reviewer'
+    #       Post.published
+    #     when 'Bad User'
+    #       Post.none # => returning [] instead breaks the previous code
+    #     end
+    #   end
+    #
+    def none
+      extending(NullRelation)
+    end
+
+    def none! # :nodoc:
+      extending!(NullRelation)
+    end
+
+    # Sets readonly attributes for the returned relation. If value is
+    # true (default), attempting to update a record will result in an error.
+    #
+    #   users = User.readonly
+    #   users.first.save
+    #   => ActiveRecord::ReadOnlyRecord: ActiveRecord::ReadOnlyRecord
     def readonly(value = true)
-      relation = clone
-      relation.readonly_value = value
-      relation
+      spawn.readonly!(value)
+    end
+
+    def readonly!(value = true) # :nodoc:
+      self.readonly_value = value
+      self
     end
 
+    # Sets attributes to be used when creating new records from a
+    # relation object.
+    #
+    #   users = User.where(name: 'Oscar')
+    #   users.new.name # => 'Oscar'
+    #
+    #   users = users.create_with(name: 'DHH')
+    #   users.new.name # => 'DHH'
+    #
+    # You can pass +nil+ to +create_with+ to reset attributes:
+    #
+    #   users = users.create_with(nil)
+    #   users.new.name # => 'Oscar'
     def create_with(value)
-      relation = clone
-      relation.create_with_value = value ? create_with_value.merge(value) : {}
-      relation
+      spawn.create_with!(value)
     end
 
-    def from(value)
-      relation = clone
-      relation.from_value = value
-      relation
+    def create_with!(value) # :nodoc:
+      self.create_with_value = value ? create_with_value.merge(value) : {}
+      self
+    end
+
+    # Specifies table from which the records will be fetched. For example:
+    #
+    #   Topic.select('title').from('posts')
+    #   #=> SELECT title FROM posts
+    #
+    # Can accept other relation objects. For example:
+    #
+    #   Topic.select('title').from(Topic.approved)
+    #   # => SELECT title FROM (SELECT * FROM topics WHERE approved = 't') subquery
+    #
+    #   Topic.select('a.title').from(Topic.approved, :a)
+    #   # => SELECT a.title FROM (SELECT * FROM topics WHERE approved = 't') a
+    #
+    def from(value, subquery_name = nil)
+      spawn.from!(value, subquery_name)
+    end
+
+    def from!(value, subquery_name = nil) # :nodoc:
+      self.from_value = [value, subquery_name]
+      self
     end
 
     # Specifies whether the records should be unique or not. For example:
@@ -199,9 +650,13 @@ module ActiveRecord
     #   User.select(:name).uniq.uniq(false)
     #   # => You can also remove the uniqueness
     def uniq(value = true)
-      relation = clone
-      relation.uniq_value = value
-      relation
+      spawn.uniq!(value)
+    end
+
+    # Like #uniq, but modifies relation in place.
+    def uniq!(value = true) # :nodoc:
+      self.uniq_value = value
+      self
     end
 
     # Used to extend a scope with additional methods, either through
@@ -217,16 +672,16 @@ module ActiveRecord
     #     end
     #   end
     #
-    #   scope = Model.scoped.extending(Pagination)
+    #   scope = Model.all.extending(Pagination)
     #   scope.page(params[:page])
     #
     # You can also pass a list of modules:
     #
-    #   scope = Model.scoped.extending(Pagination, SomethingElse)
+    #   scope = Model.all.extending(Pagination, SomethingElse)
     #
     # === Using a block
     #
-    #   scope = Model.scoped.extending do
+    #   scope = Model.all.extending do
     #     def page(number)
     #       # pagination code goes here
     #     end
@@ -235,54 +690,67 @@ module ActiveRecord
     #
     # You can also use a block and a module list:
     #
-    #   scope = Model.scoped.extending(Pagination) do
+    #   scope = Model.all.extending(Pagination) do
     #     def per_page(number)
     #       # pagination code goes here
     #     end
     #   end
-    def extending(*modules)
-      modules << Module.new(&Proc.new) if block_given?
+    def extending(*modules, &block)
+      if modules.any? || block
+        spawn.extending!(*modules, &block)
+      else
+        self
+      end
+    end
+
+    def extending!(*modules, &block) # :nodoc:
+      modules << Module.new(&block) if block_given?
 
-      return self if modules.empty?
+      self.extending_values += modules.flatten
+      extend(*extending_values) if extending_values.any?
 
-      relation = clone
-      relation.send(:apply_modules, modules.flatten)
-      relation
+      self
     end
 
+    # Reverse the existing order clause on the relation.
+    #
+    #   User.order('name ASC').reverse_order # generated SQL has 'ORDER BY name DESC'
     def reverse_order
-      relation = clone
-      relation.reverse_order_value = !relation.reverse_order_value
-      relation
+      spawn.reverse_order!
+    end
+
+    def reverse_order! # :nodoc:
+      self.reverse_order_value = !reverse_order_value
+      self
     end
 
+    # Returns the Arel object associated with the relation.
     def arel
       @arel ||= with_default_scope.build_arel
     end
 
+    # Like #arel, but ignores the default scope of the model.
     def build_arel
-      arel = table.from table
+      arel = Arel::SelectManager.new(table.engine, table)
 
-      build_joins(arel, @joins_values) unless @joins_values.empty?
+      build_joins(arel, joins_values) unless joins_values.empty?
 
-      collapse_wheres(arel, (@where_values - ['']).uniq)
+      collapse_wheres(arel, (where_values - ['']).uniq)
 
-      arel.having(*@having_values.uniq.reject{|h| h.blank?}) unless @having_values.empty?
+      arel.having(*having_values.uniq.reject{|h| h.blank?}) unless having_values.empty?
 
-      arel.take(connection.sanitize_limit(@limit_value)) if @limit_value
-      arel.skip(@offset_value.to_i) if @offset_value
+      arel.take(connection.sanitize_limit(limit_value)) if limit_value
+      arel.skip(offset_value.to_i) if offset_value
 
-      arel.group(*@group_values.uniq.reject{|g| g.blank?}) unless @group_values.empty?
+      arel.group(*group_values.uniq.reject{|g| g.blank?}) unless group_values.empty?
 
-      order = @order_values
-      order = reverse_sql_order(order) if @reverse_order_value
-      arel.order(*order.uniq.reject{|o| o.blank?}) unless order.empty?
+      build_order(arel)
 
-      build_select(arel, @select_values.uniq)
+      build_select(arel, select_values.uniq)
 
-      arel.distinct(@uniq_value)
-      arel.from(@from_value) if @from_value
-      arel.lock(@lock_value) if @lock_value
+      arel.distinct(uniq_value)
+      arel.from(build_from) if from_value
+      arel.lock(lock_value) if lock_value
 
       arel
     end
@@ -324,32 +792,48 @@ module ActiveRecord
         [@klass.send(:sanitize_sql, other.empty? ? opts : ([opts] + other))]
       when Hash
         attributes = @klass.send(:expand_hash_conditions_for_aggregates, opts)
-        PredicateBuilder.build_from_hash(table.engine, attributes, table)
+
+        attributes.values.grep(ActiveRecord::Relation) do |rel|
+          self.bind_values += rel.bind_values
+        end
+
+        PredicateBuilder.build_from_hash(klass, attributes, table)
       else
         [opts]
       end
     end
 
+    def build_from
+      opts, name = from_value
+      case opts
+      when Relation
+        name ||= 'subquery'
+        opts.arel.as(name.to_s)
+      else
+        opts
+      end
+    end
+
     def build_joins(manager, joins)
       buckets = joins.group_by do |join|
         case join
         when String
-          'string_join'
+          :string_join
         when Hash, Symbol, Array
-          'association_join'
+          :association_join
         when ActiveRecord::Associations::JoinDependency::JoinAssociation
-          'stashed_join'
+          :stashed_join
         when Arel::Nodes::Join
-          'join_node'
+          :join_node
         else
           raise 'unknown class: %s' % join.class.name
         end
       end
 
-      association_joins         = buckets['association_join'] || []
-      stashed_association_joins = buckets['stashed_join'] || []
-      join_nodes                = (buckets['join_node'] || []).uniq
-      string_joins              = (buckets['string_join'] || []).map { |x|
+      association_joins         = buckets[:association_join] || []
+      stashed_association_joins = buckets[:stashed_join] || []
+      join_nodes                = (buckets[:join_node] || []).uniq
+      string_joins              = (buckets[:string_join] || []).map { |x|
         x.strip
       }.uniq
 
@@ -384,34 +868,80 @@ module ActiveRecord
       end
     end
 
-    def apply_modules(modules)
-      unless modules.empty?
-        @extensions += modules
-        modules.each {|extension| extend(extension) }
-      end
-    end
-
     def reverse_sql_order(order_query)
       order_query = ["#{quoted_table_name}.#{quoted_primary_key} ASC"] if order_query.empty?
 
-      order_query.map do |o|
+      order_query.flat_map do |o|
         case o
         when Arel::Nodes::Ordering
           o.reverse
-        when String, Symbol
+        when String
           o.to_s.split(',').collect do |s|
             s.strip!
             s.gsub!(/\sasc\Z/i, ' DESC') || s.gsub!(/\sdesc\Z/i, ' ASC') || s.concat(' DESC')
           end
+        when Symbol
+          { o => :desc }
+        when Hash
+          o.each_with_object({}) do |(field, dir), memo|
+            memo[field] = (dir == :asc ? :desc : :asc )
+          end
         else
           o
         end
-      end.flatten
+      end
     end
 
     def array_of_strings?(o)
       o.is_a?(Array) && o.all?{|obj| obj.is_a?(String)}
     end
 
+    def build_order(arel)
+      orders = order_values
+      orders = reverse_sql_order(orders) if reverse_order_value
+
+      orders = orders.uniq.reject(&:blank?).flat_map do |order|
+        case order
+        when Symbol
+          table[order].asc
+        when Hash
+          order.map { |field, dir| table[field].send(dir) }
+        else
+          order
+        end
+      end
+
+      arel.order(*orders) unless orders.empty?
+    end
+
+    def validate_order_args(args)
+      args.select { |a| Hash === a  }.each do |h|
+        unless (h.values - [:asc, :desc]).empty?
+          raise ArgumentError, 'Direction should be :asc or :desc'
+        end
+      end
+    end
+
+    # Checks to make sure that the arguments are not blank. Note that if some
+    # blank-like object were initially passed into the query method, then this
+    # method will not raise an error.
+    #
+    # Example:
+    #
+    #    Post.references()   # => raises an error
+    #    Post.references([]) # => does not raise an error
+    #
+    # This particular method should be called with a method_name and the args
+    # passed into that method as an input. For example:
+    #
+    # def references(*args)
+    #   check_if_method_has_arguments!("references", args)
+    #   ...
+    # end
+    def check_if_method_has_arguments!(method_name, args)
+      if args.blank?
+        raise ArgumentError, "The method .#{method_name}() must contain arguments."
+      end
+    end
   end
 end