activerecord 5.0.7.2 → 6.0.3.4

data/lib/active_record/relation/predicate_builder/array_handler.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/array/extract"
+
 module ActiveRecord
   class PredicateBuilder
     class ArrayHandler # :nodoc:
@@ -6,18 +10,21 @@ module ActiveRecord
       end
 
       def call(attribute, value)
-        values = value.map { |x| x.is_a?(Base) ? x.id : x }
-        nils, values = values.partition(&:nil?)
-
-        return attribute.in([]) if values.empty? && nils.empty?
+        return attribute.in([]) if value.empty?
 
-        ranges, values = values.partition { |v| v.is_a?(Range) }
+        values = value.map { |x| x.is_a?(Base) ? x.id : x }
+        nils = values.extract!(&:nil?)
+        ranges = values.extract! { |v| v.is_a?(Range) }
 
         values_predicate =
           case values.length
           when 0 then NullPredicate
           when 1 then predicate_builder.build(attribute, values.first)
-          else attribute.in(values)
+          else
+            values.map! do |v|
+              predicate_builder.build_bind_attribute(attribute.name, v)
+            end
+            values.empty? ? NullPredicate : attribute.in(values)
           end
 
         unless nils.empty?
@@ -26,18 +33,17 @@ module ActiveRecord
 
         array_predicates = ranges.map { |range| predicate_builder.build(attribute, range) }
         array_predicates.unshift(values_predicate)
-        array_predicates.inject { |composite, predicate| composite.or(predicate) }
+        array_predicates.inject(&:or)
       end
 
-      protected
-
-      attr_reader :predicate_builder
+      private
+        attr_reader :predicate_builder
 
-      module NullPredicate # :nodoc:
-        def self.or(other)
-          other
+        module NullPredicate # :nodoc:
+          def self.or(other)
+            other
+          end
         end
-      end
     end
   end
 end

data/lib/active_record/relation/predicate_builder/association_query_value.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  class PredicateBuilder
+    class AssociationQueryValue # :nodoc:
+      def initialize(associated_table, value)
+        @associated_table = associated_table
+        @value = value
+      end
+
+      def queries
+        [associated_table.association_join_foreign_key.to_s => ids]
+      end
+
+      private
+        attr_reader :associated_table, :value
+
+        def ids
+          case value
+          when Relation
+            value.select_values.empty? ? value.select(primary_key) : value
+          when Array
+            value.map { |v| convert_to_id(v) }
+          else
+            convert_to_id(value)
+          end
+        end
+
+        def primary_key
+          associated_table.association_join_primary_key
+        end
+
+        def convert_to_id(value)
+          case value
+          when Base
+            value._read_attribute(primary_key)
+          else
+            value
+          end
+        end
+    end
+  end
+end

data/lib/active_record/relation/predicate_builder/base_handler.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ActiveRecord
   class PredicateBuilder
     class BaseHandler # :nodoc:
@@ -9,9 +11,8 @@ module ActiveRecord
         predicate_builder.build(attribute, value.id)
       end
 
-      protected
-
-      attr_reader :predicate_builder
+      private
+        attr_reader :predicate_builder
     end
   end
 end

data/lib/active_record/relation/predicate_builder/basic_object_handler.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ActiveRecord
   class PredicateBuilder
     class BasicObjectHandler # :nodoc:
@@ -6,12 +8,12 @@ module ActiveRecord
       end
 
       def call(attribute, value)
-        attribute.eq(value)
+        bind = predicate_builder.build_bind_attribute(attribute.name, value)
+        attribute.eq(bind)
       end
 
-      protected
-
-      attr_reader :predicate_builder
+      private
+        attr_reader :predicate_builder
     end
   end
 end

data/lib/active_record/relation/predicate_builder/polymorphic_array_value.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  class PredicateBuilder
+    class PolymorphicArrayValue # :nodoc:
+      def initialize(associated_table, values)
+        @associated_table = associated_table
+        @values = values
+      end
+
+      def queries
+        type_to_ids_mapping.map do |type, ids|
+          {
+            associated_table.association_foreign_type.to_s => type,
+            associated_table.association_foreign_key.to_s => ids
+          }
+        end
+      end
+
+      private
+        attr_reader :associated_table, :values
+
+        def type_to_ids_mapping
+          default_hash = Hash.new { |hsh, key| hsh[key] = [] }
+          values.each_with_object(default_hash) do |value, hash|
+            hash[klass(value).polymorphic_name] << convert_to_id(value)
+          end
+        end
+
+        def primary_key(value)
+          associated_table.association_join_primary_key(klass(value))
+        end
+
+        def klass(value)
+          case value
+          when Base
+            value.class
+          when Relation
+            value.klass
+          end
+        end
+
+        def convert_to_id(value)
+          case value
+          when Base
+            value._read_attribute(primary_key(value))
+          when Relation
+            value.select(primary_key(value))
+          end
+        end
+    end
+  end
+end

data/lib/active_record/relation/predicate_builder/range_handler.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ActiveRecord
   class PredicateBuilder
     class RangeHandler # :nodoc:
@@ -8,26 +10,13 @@ module ActiveRecord
       end
 
       def call(attribute, value)
-        if value.begin.respond_to?(:infinite?) && value.begin.infinite?
-          if value.end.respond_to?(:infinite?) && value.end.infinite?
-            attribute.not_in([])
-          elsif value.exclude_end?
-            attribute.lt(value.end)
-          else
-            attribute.lteq(value.end)
-          end
-        elsif value.end.respond_to?(:infinite?) && value.end.infinite?
-          attribute.gteq(value.begin)
-        elsif value.exclude_end?
-          attribute.gteq(value.begin).and(attribute.lt(value.end))
-        else
-          attribute.between(value)
-        end
+        begin_bind = predicate_builder.build_bind_attribute(attribute.name, value.begin)
+        end_bind = predicate_builder.build_bind_attribute(attribute.name, value.end)
+        attribute.between(RangeWithBinds.new(begin_bind, end_bind, value.exclude_end?))
       end
 
-      protected
-
-      attr_reader :predicate_builder
+      private
+        attr_reader :predicate_builder
     end
   end
 end

data/lib/active_record/relation/predicate_builder/relation_handler.rb

@@ -1,7 +1,13 @@
+# frozen_string_literal: true
+
 module ActiveRecord
   class PredicateBuilder
     class RelationHandler # :nodoc:
       def call(attribute, value)
+        if value.eager_loading?
+          value = value.send(:apply_join_dependency)
+        end
+
         if value.select_values.empty?
           value = value.select(value.arel_attribute(value.klass.primary_key))
         end

data/lib/active_record/relation/query_attribute.rb

@@ -1,8 +1,10 @@
-require 'active_record/attribute'
+# frozen_string_literal: true
+
+require "active_model/attribute"
 
 module ActiveRecord
   class Relation
-    class QueryAttribute < Attribute # :nodoc:
+    class QueryAttribute < ActiveModel::Attribute # :nodoc:
       def type_cast(value)
         value
       end
@@ -14,6 +16,35 @@ module ActiveRecord
       def with_cast_value(value)
         QueryAttribute.new(name, value, type)
       end
+
+      def nil?
+        unless value_before_type_cast.is_a?(StatementCache::Substitute)
+          value_before_type_cast.nil? ||
+            type.respond_to?(:subtype, true) && value_for_database.nil?
+        end
+      rescue ::RangeError
+      end
+
+      def infinite?
+        infinity?(value_before_type_cast) || infinity?(value_for_database)
+      rescue ::RangeError
+      end
+
+      def unboundable?
+        if defined?(@_unboundable)
+          @_unboundable
+        else
+          value_for_database unless value_before_type_cast.is_a?(StatementCache::Substitute)
+          @_unboundable = nil
+        end
+      rescue ::RangeError
+        @_unboundable = type.cast(value_before_type_cast) <=> 0
+      end
+
+      private
+        def infinity?(value)
+          value.respond_to?(:infinite?) && value.infinite?
+        end
     end
   end
 end

data/lib/active_record/relation/query_methods.rb

@@ -1,9 +1,10 @@
+# frozen_string_literal: true
+
 require "active_record/relation/from_clause"
 require "active_record/relation/query_attribute"
 require "active_record/relation/where_clause"
 require "active_record/relation/where_clause_factory"
-require 'active_model/forbidden_attributes_protection'
-require 'active_support/core_ext/string/filters'
+require "active_model/forbidden_attributes_protection"
 
 module ActiveRecord
   module QueryMethods
@@ -40,94 +41,67 @@ module ActiveRecord
       #
       #    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)
         opts = sanitize_forbidden_attributes(opts)
 
         where_clause = @scope.send(:where_clause_factory).build(opts, rest)
 
         @scope.references!(PredicateBuilder.references(opts)) if Hash === opts
-        @scope.where_clause += where_clause.invert
+
+        if not_behaves_as_nor?(opts)
+          ActiveSupport::Deprecation.warn(<<~MSG.squish)
+            NOT conditions will no longer behave as NOR in Rails 6.1.
+            To continue using NOR conditions, NOT each condition individually
+            (`#{
+              opts.flat_map { |key, value|
+                if value.is_a?(Hash) && value.size > 1
+                  value.map { |k, v| ".where.not(#{key.inspect} => { #{k.inspect} => ... })" }
+                else
+                  ".where.not(#{key.inspect} => ...)"
+                end
+              }.join
+            }`).
+          MSG
+          @scope.where_clause += where_clause.invert(:nor)
+        else
+          @scope.where_clause += where_clause.invert
+        end
+
         @scope
       end
-    end
 
-    FROZEN_EMPTY_ARRAY = [].freeze
-    Relation::MULTI_VALUE_METHODS.each do |name|
-      class_eval <<-CODE, __FILE__, __LINE__ + 1
-        def #{name}_values
-          @values[:#{name}] || FROZEN_EMPTY_ARRAY
-        end
+      private
+        def not_behaves_as_nor?(opts)
+          return false unless opts.is_a?(Hash)
 
-        def #{name}_values=(values)
-          assert_mutability!
-          @values[:#{name}] = values
+          opts.any? { |k, v| v.is_a?(Hash) && v.size > 1 } ||
+            opts.size > 1
         end
-      CODE
     end
 
-    (Relation::SINGLE_VALUE_METHODS - [:create_with]).each do |name|
+    FROZEN_EMPTY_ARRAY = [].freeze
+    FROZEN_EMPTY_HASH = {}.freeze
+
+    Relation::VALUE_METHODS.each do |name|
+      method_name = \
+        case name
+        when *Relation::MULTI_VALUE_METHODS then "#{name}_values"
+        when *Relation::SINGLE_VALUE_METHODS then "#{name}_value"
+        when *Relation::CLAUSE_METHODS then "#{name}_clause"
+        end
       class_eval <<-CODE, __FILE__, __LINE__ + 1
-        def #{name}_value                    # def readonly_value
-          @values[:#{name}]                  #   @values[:readonly]
+        def #{method_name}                   # def includes_values
+          default = DEFAULT_VALUES[:#{name}] #   default = DEFAULT_VALUES[:includes]
+          @values.fetch(:#{name}, default)   #   @values.fetch(:includes, default)
         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)
+        def #{method_name}=(value)           # def includes_values=(value)
           assert_mutability!                 #   assert_mutability!
-          @values[:#{name}] = value          #   @values[:readonly] = value
+          @values[:#{name}] = value          #   @values[:includes] = value
         end                                  # end
       CODE
     end
 
-    Relation::CLAUSE_METHODS.each do |name|
-      class_eval <<-CODE, __FILE__, __LINE__ + 1
-        def #{name}_clause                           # def where_clause
-          @values[:#{name}] || new_#{name}_clause    #   @values[:where] || new_where_clause
-        end                                          # end
-                                                     #
-        def #{name}_clause=(value)                   # def where_clause=(value)
-          assert_mutability!                         #   assert_mutability!
-          @values[:#{name}] = value                  #   @values[:where] = value
-        end                                          # end
-      CODE
-    end
-
-    def bound_attributes
-      if limit_value && !string_containing_comma?(limit_value)
-        limit_bind = Attribute.with_cast_value(
-          "LIMIT".freeze,
-          connection.sanitize_limit(limit_value),
-          Type::Value.new,
-        )
-      end
-      if offset_value
-        offset_bind = Attribute.with_cast_value(
-          "OFFSET".freeze,
-          offset_value.to_i,
-          Type::Value.new,
-        )
-      end
-      connection.combine_bind_parameters(
-        from_clause: from_clause.binds,
-        join_clause: arel.bind_values,
-        where_clause: where_clause.binds,
-        having_clause: having_clause.binds,
-        limit: limit_bind,
-        offset: offset_bind,
-      )
-    end
-
-    FROZEN_EMPTY_HASH = {}.freeze
-    def create_with_value # :nodoc:
-      @values[:create_with] || FROZEN_EMPTY_HASH
-    end
-
     alias extensions extending_values
 
     # Specify relationships to be included in the result set. For
@@ -152,7 +126,7 @@ module ActiveRecord
     #
     # === conditions
     #
-    # If you want to add conditions to your included models you'll have
+    # If you want to add string conditions to your included models, you'll have
     # to explicitly reference them. For example:
     #
     #   User.includes(:posts).where('posts.name = ?', 'example')
@@ -163,6 +137,12 @@ module ActiveRecord
     #
     # Note that #includes works with association names while #references needs
     # the actual table name.
+    #
+    # If you pass the conditions via hash, you don't need to call #references
+    # explicitly, as #where references the tables for you. For example, this
+    # will work correctly:
+    #
+    #   User.includes(:posts).where(posts: { name: 'example' })
     def includes(*args)
       check_if_method_has_arguments!(:includes, args)
       spawn.includes!(*args)
@@ -188,7 +168,7 @@ module ActiveRecord
     end
 
     def eager_load!(*args) # :nodoc:
-      self.eager_load_values += args
+      self.eager_load_values |= args
       self
     end
 
@@ -202,10 +182,23 @@ module ActiveRecord
     end
 
     def preload!(*args) # :nodoc:
-      self.preload_values += args
+      self.preload_values |= args
       self
     end
 
+    # Extracts a named +association+ from the relation. The named association is first preloaded,
+    # then the individual association records are collected from the relation. Like so:
+    #
+    #   account.memberships.extract_associated(:user)
+    #   # => Returns collection of User records
+    #
+    # This is short-hand for:
+    #
+    #   account.memberships.preload(:user).collect(&:user)
+    def extract_associated(association)
+      preload(association).collect(&association)
+    end
+
     # Use to indicate that the given +table_names+ are referenced by an SQL string,
     # and should therefore be JOINed in any query rather than loaded separately.
     # This method only works in conjunction with #includes.
@@ -231,12 +224,13 @@ module ActiveRecord
 
     # Works in two unique ways.
     #
-    # First: takes a block so it can be used just like +Array#select+.
+    # First: takes a block so it can be used just like <tt>Array#select</tt>.
     #
     #   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+.
+    # converting them into an array and iterating through them using
+    # <tt>Array#select</tt>.
     #
     # Second: Modifies the SELECT statement for the query so that only certain
     # fields are retrieved:
@@ -269,20 +263,46 @@ module ActiveRecord
     #   Model.select(:field).first.other_field
     #   # => ActiveModel::MissingAttributeError: missing attribute: other_field
     def select(*fields)
-      return super if block_given?
-      raise ArgumentError, 'Call this with at least one field' if fields.empty?
+      if block_given?
+        if fields.any?
+          raise ArgumentError, "`select' with block doesn't take arguments."
+        end
+
+        return super()
+      end
+
+      raise ArgumentError, "Call `select' with at least one field" if fields.empty?
       spawn._select!(*fields)
     end
 
     def _select!(*fields) # :nodoc:
+      fields.reject!(&:blank?)
       fields.flatten!
-      fields.map! do |field|
-        klass.attribute_alias?(field) ? klass.attribute_alias(field).to_sym : field
-      end
       self.select_values += fields
       self
     end
 
+    # Allows you to change a previously set select statement.
+    #
+    #   Post.select(:title, :body)
+    #   # SELECT `posts`.`title`, `posts`.`body` FROM `posts`
+    #
+    #   Post.select(:title, :body).reselect(:created_at)
+    #   # SELECT `posts`.`created_at` FROM `posts`
+    #
+    # This is short-hand for <tt>unscope(:select).select(fields)</tt>.
+    # Note that we're unscoping the entire select statement.
+    def reselect(*args)
+      check_if_method_has_arguments!(:reselect, args)
+      spawn.reselect!(*args)
+    end
+
+    # Same as #reselect but operates on relation in-place instead of copying.
+    def reselect!(*args) # :nodoc:
+      self.select_values = args
+      self
+    end
+
     # Allows to specify a group attribute:
     #
     #   User.group(:name)
@@ -311,7 +331,7 @@ module ActiveRecord
     def group!(*args) # :nodoc:
       args.flatten!
 
-      self.group_values += args
+      self.group_values |= args
       self
     end
 
@@ -339,6 +359,7 @@ module ActiveRecord
       spawn.order!(*args)
     end
 
+    # Same as #order but operates on relation in-place instead of copying.
     def order!(*args) # :nodoc:
       preprocess_order_args(args)
 
@@ -360,8 +381,9 @@ module ActiveRecord
       spawn.reorder!(*args)
     end
 
+    # Same as #reorder but operates on relation in-place instead of copying.
     def reorder!(*args) # :nodoc:
-      preprocess_order_args(args)
+      preprocess_order_args(args) unless args.all?(&:blank?)
 
       self.reordering_value = true
       self.order_values = args
@@ -369,8 +391,8 @@ module ActiveRecord
     end
 
     VALID_UNSCOPING_VALUES = Set.new([:where, :select, :group, :order, :lock,
-                                     :limit, :offset, :joins, :includes, :from,
-                                     :readonly, :having])
+                                     :limit, :offset, :joins, :left_outer_joins, :annotate,
+                                     :includes, :from, :readonly, :having, :optimizer_hints])
 
     # Removes an unwanted relation that is already defined on a chain of relations.
     # This is useful when passing around chains of relations and would like to
@@ -417,7 +439,12 @@ module ActiveRecord
       args.each do |scope|
         case scope
         when Symbol
-          symbol_unscoping(scope)
+          scope = :left_outer_joins if scope == :left_joins
+          if !VALID_UNSCOPING_VALUES.include?(scope)
+            raise ArgumentError, "Called unscope() with invalid unscoping argument ':#{scope}'. Valid arguments are :#{VALID_UNSCOPING_VALUES.to_a.join(", :")}."
+          end
+          assert_mutability!
+          @values[scope] = DEFAULT_VALUES[scope]
         when Hash
           scope.each do |key, target_value|
             if key != :where
@@ -472,7 +499,7 @@ module ActiveRecord
     def joins!(*args) # :nodoc:
       args.compact!
       args.flatten!
-      self.joins_values += args
+      self.joins_values |= args
       self
     end
 
@@ -482,20 +509,17 @@ module ActiveRecord
     #   => SELECT "users".* FROM "users" LEFT OUTER JOIN "posts" ON "posts"."user_id" = "users"."id"
     #
     def left_outer_joins(*args)
-      check_if_method_has_arguments!(:left_outer_joins, args)
-
-      args.compact!
-      args.flatten!
-
+      check_if_method_has_arguments!(__callee__, args)
       spawn.left_outer_joins!(*args)
     end
     alias :left_joins :left_outer_joins
 
     def left_outer_joins!(*args) # :nodoc:
-      self.left_outer_joins_values += args
+      args.compact!
+      args.flatten!
+      self.left_outer_joins_values |= args
       self
     end
-    alias :left_joins! :left_outer_joins!
 
     # Returns a new relation, which is the result of filtering the current relation
     # according to the conditions in the arguments.
@@ -658,7 +682,7 @@ module ActiveRecord
     # present). Neither relation may have a #limit, #offset, or #distinct set.
     #
     #    Post.where("id = 1").or(Post.where("author_id = 3"))
-    #    # SELECT `posts`.* FROM `posts`  WHERE (('id = 1' OR 'author_id = 3'))
+    #    # SELECT `posts`.* FROM `posts` WHERE ((id = 1) OR (author_id = 3))
     #
     def or(other)
       unless other.is_a? Relation
@@ -676,7 +700,8 @@ module ActiveRecord
       end
 
       self.where_clause = self.where_clause.or(other.where_clause)
-      self.having_clause = self.having_clause.or(other.having_clause)
+      self.having_clause = having_clause.or(other.having_clause)
+      self.references_values += other.references_values
 
       self
     end
@@ -707,13 +732,6 @@ module ActiveRecord
     end
 
     def limit!(value) # :nodoc:
-      if string_containing_comma?(value)
-        # Remove `string_containing_comma?` when removing this deprecation
-        ActiveSupport::Deprecation.warn(<<-WARNING.squish)
-          Passing a string to limit in the form "1,2" is deprecated and will be
-          removed in Rails 5.1. Please call `offset` explicitly instead.
-        WARNING
-      end
       self.limit_value = value
       self
     end
@@ -780,7 +798,7 @@ module ActiveRecord
     #   end
     #
     def none
-      where("1=0").extending!(NullRelation)
+      spawn.none!
     end
 
     def none! # :nodoc:
@@ -824,7 +842,7 @@ module ActiveRecord
         value = sanitize_forbidden_attributes(value)
         self.create_with_value = create_with_value.merge(value)
       else
-        self.create_with_value = {}
+        self.create_with_value = FROZEN_EMPTY_HASH
       end
 
       self
@@ -865,16 +883,12 @@ module ActiveRecord
     def distinct(value = true)
       spawn.distinct!(value)
     end
-    alias uniq distinct
-    deprecate uniq: :distinct
 
     # Like #distinct, but modifies relation in place.
     def distinct!(value = true) # :nodoc:
       self.distinct_value = value
       self
     end
-    alias uniq! distinct!
-    deprecate uniq!: :distinct!
 
     # Used to extend a scope with additional methods, either through
     # a module or through a block provided.
@@ -930,6 +944,29 @@ module ActiveRecord
       self
     end
 
+    # Specify optimizer hints to be used in the SELECT statement.
+    #
+    # Example (for MySQL):
+    #
+    #   Topic.optimizer_hints("MAX_EXECUTION_TIME(50000)", "NO_INDEX_MERGE(topics)")
+    #   # SELECT /*+ MAX_EXECUTION_TIME(50000) NO_INDEX_MERGE(topics) */ `topics`.* FROM `topics`
+    #
+    # Example (for PostgreSQL with pg_hint_plan):
+    #
+    #   Topic.optimizer_hints("SeqScan(topics)", "Parallel(topics 8)")
+    #   # SELECT /*+ SeqScan(topics) Parallel(topics 8) */ "topics".* FROM "topics"
+    def optimizer_hints(*args)
+      check_if_method_has_arguments!(:optimizer_hints, args)
+      spawn.optimizer_hints!(*args)
+    end
+
+    def optimizer_hints!(*args) # :nodoc:
+      args.flatten!
+
+      self.optimizer_hints_values |= args
+      self
+    end
+
     # Reverse the existing order clause on the relation.
     #
     #   User.order('name ASC').reverse_order # generated SQL has 'ORDER BY name DESC'
@@ -944,299 +981,404 @@ module ActiveRecord
       self
     end
 
-    # Returns the Arel object associated with the relation.
-    def arel # :nodoc:
-      @arel ||= build_arel
+    def skip_query_cache!(value = true) # :nodoc:
+      self.skip_query_cache_value = value
+      self
     end
 
-    private
+    def skip_preloading! # :nodoc:
+      self.skip_preloading_value = true
+      self
+    end
+
+    # Adds an SQL comment to queries generated from this relation. For example:
+    #
+    #   User.annotate("selecting user names").select(:name)
+    #   # SELECT "users"."name" FROM "users" /* selecting user names */
+    #
+    #   User.annotate("selecting", "user", "names").select(:name)
+    #   # SELECT "users"."name" FROM "users" /* selecting */ /* user */ /* names */
+    #
+    # The SQL block comment delimiters, "/*" and "*/", will be added automatically.
+    def annotate(*args)
+      check_if_method_has_arguments!(:annotate, args)
+      spawn.annotate!(*args)
+    end
 
-    def assert_mutability!
-      raise ImmutableRelation if @loaded
-      raise ImmutableRelation if defined?(@arel) && @arel
+    # Like #annotate, but modifies relation in place.
+    def annotate!(*args) # :nodoc:
+      self.annotate_values += args
+      self
     end
 
-    def build_arel
-      arel = Arel::SelectManager.new(table)
+    # Returns the Arel object associated with the relation.
+    def arel(aliases = nil) # :nodoc:
+      @arel ||= build_arel(aliases)
+    end
 
-      build_joins(arel, joins_values.flatten) unless joins_values.empty?
-      build_left_outer_joins(arel, left_outer_joins_values.flatten) unless left_outer_joins_values.empty?
+    def construct_join_dependency(associations, join_type) # :nodoc:
+      ActiveRecord::Associations::JoinDependency.new(
+        klass, table, associations, join_type
+      )
+    end
 
-      arel.where(where_clause.ast) unless where_clause.empty?
-      arel.having(having_clause.ast) unless having_clause.empty?
-      if limit_value
-        if string_containing_comma?(limit_value)
-          arel.take(connection.sanitize_limit(limit_value))
-        else
-          arel.take(Arel::Nodes::BindParam.new)
+    protected
+      def build_subquery(subquery_alias, select_value) # :nodoc:
+        subquery = except(:optimizer_hints).arel.as(subquery_alias)
+
+        Arel::SelectManager.new(subquery).project(select_value).tap do |arel|
+          arel.optimizer_hints(*optimizer_hints_values) unless optimizer_hints_values.empty?
         end
       end
-      arel.skip(Arel::Nodes::BindParam.new) if offset_value
-      arel.group(*arel_columns(group_values.uniq.reject(&:blank?))) unless group_values.empty?
-
-      build_order(arel)
-
-      build_select(arel)
 
-      arel.distinct(distinct_value)
-      arel.from(build_from) unless from_clause.empty?
-      arel.lock(lock_value) if lock_value
+    private
+      def assert_mutability!
+        raise ImmutableRelation if @loaded
+        raise ImmutableRelation if defined?(@arel) && @arel
+      end
 
-      arel
-    end
+      def build_arel(aliases)
+        arel = Arel::SelectManager.new(table)
 
-    def symbol_unscoping(scope)
-      if !VALID_UNSCOPING_VALUES.include?(scope)
-        raise ArgumentError, "Called unscope() with invalid unscoping argument ':#{scope}'. Valid arguments are :#{VALID_UNSCOPING_VALUES.to_a.join(", :")}."
-      end
+        if !joins_values.empty?
+          build_joins(arel, joins_values.flatten, aliases)
+        elsif !left_outer_joins_values.empty?
+          build_left_outer_joins(arel, left_outer_joins_values.flatten, aliases)
+        end
 
-      clause_method = Relation::CLAUSE_METHODS.include?(scope)
-      multi_val_method = Relation::MULTI_VALUE_METHODS.include?(scope)
-      if clause_method
-        unscope_code = "#{scope}_clause="
-      else
-        unscope_code = "#{scope}_value#{'s' if multi_val_method}="
-      end
+        arel.where(where_clause.ast) unless where_clause.empty?
+        arel.having(having_clause.ast) unless having_clause.empty?
+        if limit_value
+          limit_attribute = ActiveModel::Attribute.with_cast_value(
+            "LIMIT",
+            connection.sanitize_limit(limit_value),
+            Type.default_value,
+          )
+          arel.take(Arel::Nodes::BindParam.new(limit_attribute))
+        end
+        if offset_value
+          offset_attribute = ActiveModel::Attribute.with_cast_value(
+            "OFFSET",
+            offset_value.to_i,
+            Type.default_value,
+          )
+          arel.skip(Arel::Nodes::BindParam.new(offset_attribute))
+        end
+        arel.group(*arel_columns(group_values.uniq.reject(&:blank?))) unless group_values.empty?
 
-      case scope
-      when :order
-        result = []
-      else
-        result = [] if multi_val_method
-      end
+        build_order(arel)
 
-      self.send(unscope_code, result)
-    end
+        build_select(arel)
 
-    def association_for_table(table_name)
-      table_name = table_name.to_s
-      @klass._reflect_on_association(table_name) ||
-        @klass._reflect_on_association(table_name.singularize)
-    end
+        arel.optimizer_hints(*optimizer_hints_values) unless optimizer_hints_values.empty?
+        arel.distinct(distinct_value)
+        arel.from(build_from) unless from_clause.empty?
+        arel.lock(lock_value) if lock_value
+        arel.comment(*annotate_values) unless annotate_values.empty?
 
-    def build_from
-      opts = from_clause.value
-      name = from_clause.name
-      case opts
-      when Relation
-        name ||= 'subquery'
-        opts.arel.as(name.to_s)
-      else
-        opts
+        arel
       end
-    end
 
-    def build_left_outer_joins(manager, outer_joins)
-      buckets = outer_joins.group_by do |join|
-        case join
-        when Hash, Symbol, Array
-          :association_join
+      def build_from
+        opts = from_clause.value
+        name = from_clause.name
+        case opts
+        when Relation
+          if opts.eager_loading?
+            opts = opts.send(:apply_join_dependency)
+          end
+          name ||= "subquery"
+          opts.arel.as(name.to_s)
         else
-          raise ArgumentError, 'only Hash, Symbol and Array are allowed'
+          opts
         end
       end
 
-      build_join_query(manager, buckets, Arel::Nodes::OuterJoin)
-    end
+      def select_association_list(associations)
+        result = []
+        associations.each do |association|
+          case association
+          when Hash, Symbol, Array
+            result << association
+          else
+            yield if block_given?
+          end
+        end
+        result
+      end
 
-    def build_joins(manager, joins)
-      buckets = joins.group_by do |join|
-        case join
-        when String
-          :string_join
-        when Hash, Symbol, Array
-          :association_join
-        when ActiveRecord::Associations::JoinDependency
-          :stashed_join
-        when Arel::Nodes::Join
-          :join_node
-        else
-          raise 'unknown class: %s' % join.class.name
+      def valid_association_list(associations)
+        select_association_list(associations) do
+          raise ArgumentError, "only Hash, Symbol and Array are allowed"
         end
       end
 
-      build_join_query(manager, buckets, Arel::Nodes::InnerJoin)
-    end
+      def build_left_outer_joins(manager, outer_joins, aliases)
+        buckets = Hash.new { |h, k| h[k] = [] }
+        buckets[:association_join] = valid_association_list(outer_joins)
+        build_join_query(manager, buckets, Arel::Nodes::OuterJoin, aliases)
+      end
 
-    def build_join_query(manager, buckets, join_type)
-      buckets.default = []
+      def build_joins(manager, joins, aliases)
+        buckets = Hash.new { |h, k| h[k] = [] }
 
-      association_joins         = buckets[:association_join]
-      stashed_association_joins = buckets[:stashed_join]
-      join_nodes                = buckets[:join_node].uniq
-      string_joins              = buckets[:string_join].map(&:strip).uniq
+        unless left_outer_joins_values.empty?
+          left_joins = valid_association_list(left_outer_joins_values.flatten)
+          buckets[:stashed_join] << construct_join_dependency(left_joins, Arel::Nodes::OuterJoin)
+        end
 
-      join_list = join_nodes + convert_join_strings_to_ast(manager, string_joins)
+        if joins.last.is_a?(ActiveRecord::Associations::JoinDependency)
+          buckets[:stashed_join] << joins.pop if joins.last.base_klass == klass
+        end
 
-      join_dependency = ActiveRecord::Associations::JoinDependency.new(
-        @klass,
-        association_joins,
-        join_list
-      )
+        joins.map! do |join|
+          if join.is_a?(String)
+            table.create_string_join(Arel.sql(join.strip)) unless join.blank?
+          else
+            join
+          end
+        end.delete_if(&:blank?).uniq!
+
+        while joins.first.is_a?(Arel::Nodes::Join)
+          join_node = joins.shift
+          if join_node.is_a?(Arel::Nodes::StringJoin) && !buckets[:stashed_join].empty?
+            buckets[:join_node] << join_node
+          else
+            buckets[:leading_join] << join_node
+          end
+        end
 
-      join_infos = join_dependency.join_constraints stashed_association_joins, join_type
+        joins.each do |join|
+          case join
+          when Hash, Symbol, Array
+            buckets[:association_join] << join
+          when ActiveRecord::Associations::JoinDependency
+            buckets[:stashed_join] << join
+          when Arel::Nodes::Join
+            buckets[:join_node] << join
+          else
+            raise "unknown class: %s" % join.class.name
+          end
+        end
 
-      join_infos.each do |info|
-        info.joins.each { |join| manager.from(join) }
-        manager.bind_values.concat info.binds
+        build_join_query(manager, buckets, Arel::Nodes::InnerJoin, aliases)
       end
 
-      manager.join_sources.concat(join_list)
+      def build_join_query(manager, buckets, join_type, aliases)
+        association_joins = buckets[:association_join]
+        stashed_joins     = buckets[:stashed_join]
+        leading_joins     = buckets[:leading_join]
+        join_nodes        = buckets[:join_node]
 
-      manager
-    end
+        join_sources = manager.join_sources
+        join_sources.concat(leading_joins) unless leading_joins.empty?
 
-    def convert_join_strings_to_ast(table, joins)
-      joins
-        .flatten
-        .reject(&:blank?)
-        .map { |join| table.create_string_join(Arel.sql(join)) }
-    end
+        unless association_joins.empty? && stashed_joins.empty?
+          alias_tracker = alias_tracker(leading_joins + join_nodes, aliases)
+          join_dependency = construct_join_dependency(association_joins, join_type)
+          join_sources.concat(join_dependency.join_constraints(stashed_joins, alias_tracker))
+        end
 
-    def build_select(arel)
-      if select_values.any?
-        arel.project(*arel_columns(select_values.uniq))
-      else
-        arel.project(@klass.arel_table[Arel.star])
+        join_sources.concat(join_nodes) unless join_nodes.empty?
       end
-    end
 
-    def arel_columns(columns)
-      columns.map do |field|
-        if (Symbol === field || String === field) && (klass.has_attribute?(field) || klass.attribute_alias?(field)) && !from_clause.value
-          arel_attribute(field)
-        elsif Symbol === field
-          connection.quote_table_name(field.to_s)
+      def build_select(arel)
+        if select_values.any?
+          arel.project(*arel_columns(select_values.uniq))
+        elsif klass.ignored_columns.any?
+          arel.project(*klass.column_names.map { |field| arel_attribute(field) })
         else
-          field
+          arel.project(table[Arel.star])
         end
       end
-    end
 
-    def reverse_sql_order(order_query)
-      if order_query.empty?
-        return [arel_attribute(primary_key).desc] if primary_key
-        raise IrreversibleOrderError,
-          "Relation has no current order and table has no primary key to be used as default order"
+      def arel_columns(columns)
+        columns.flat_map do |field|
+          case field
+          when Symbol
+            arel_column(field.to_s) do |attr_name|
+              connection.quote_table_name(attr_name)
+            end
+          when String
+            arel_column(field, &:itself)
+          when Proc
+            field.call
+          else
+            field
+          end
+        end
       end
 
-      order_query.flat_map do |o|
-        case o
-        when Arel::Attribute
-          o.desc
-        when Arel::Nodes::Ordering
-          o.reverse
-        when String
-          if does_not_support_reverse?(o)
-            raise IrreversibleOrderError, "Order #{o.inspect} can not be reversed automatically"
-          end
-          o.split(',').map! do |s|
-            s.strip!
-            s.gsub!(/\sasc\Z/i, ' DESC') || s.gsub!(/\sdesc\Z/i, ' ASC') || s.concat(' DESC')
-          end
+      def arel_column(field)
+        field = klass.attribute_aliases[field] || field
+        from = from_clause.name || from_clause.value
+
+        if klass.columns_hash.key?(field) && (!from || table_name_matches?(from))
+          arel_attribute(field)
         else
-          o
+          yield field
         end
       end
-    end
 
-    def does_not_support_reverse?(order)
-      # Uses SQL function with multiple arguments.
-      (order.include?(',') && order.split(',').find { |section| section.count('(') != section.count(')')}) ||
-        # Uses "nulls first" like construction.
-        order =~ /nulls (first|last)\Z/i
-    end
+      def table_name_matches?(from)
+        table_name = Regexp.escape(table.name)
+        quoted_table_name = Regexp.escape(connection.quote_table_name(table.name))
+        /(?:\A|(?<!FROM)\s)(?:\b#{table_name}\b|#{quoted_table_name})(?!\.)/i.match?(from.to_s)
+      end
 
-    def build_order(arel)
-      orders = order_values.uniq
-      orders.reject!(&:blank?)
+      def reverse_sql_order(order_query)
+        if order_query.empty?
+          return [arel_attribute(primary_key).desc] if primary_key
+          raise IrreversibleOrderError,
+            "Relation has no current order and table has no primary key to be used as default order"
+        end
 
-      arel.order(*orders) unless orders.empty?
-    end
+        order_query.flat_map do |o|
+          case o
+          when Arel::Attribute
+            o.desc
+          when Arel::Nodes::Ordering
+            o.reverse
+          when String
+            if does_not_support_reverse?(o)
+              raise IrreversibleOrderError, "Order #{o.inspect} cannot be reversed automatically"
+            end
+            o.split(",").map! do |s|
+              s.strip!
+              s.gsub!(/\sasc\Z/i, " DESC") || s.gsub!(/\sdesc\Z/i, " ASC") || (s << " DESC")
+            end
+          else
+            o
+          end
+        end
+      end
 
-    VALID_DIRECTIONS = [:asc, :desc, :ASC, :DESC,
-                        'asc', 'desc', 'ASC', 'DESC'] # :nodoc:
+      def does_not_support_reverse?(order)
+        # Account for String subclasses like Arel::Nodes::SqlLiteral that
+        # override methods like #count.
+        order = String.new(order) unless order.instance_of?(String)
 
-    def validate_order_args(args)
-      args.each do |arg|
-        next unless arg.is_a?(Hash)
-        arg.each do |_key, value|
-          raise ArgumentError, "Direction \"#{value}\" is invalid. Valid " \
-                               "directions are: #{VALID_DIRECTIONS.inspect}" unless VALID_DIRECTIONS.include?(value)
-        end
+        # Uses SQL function with multiple arguments.
+        (order.include?(",") && order.split(",").find { |section| section.count("(") != section.count(")") }) ||
+          # Uses "nulls first" like construction.
+          /\bnulls\s+(?:first|last)\b/i.match?(order)
       end
-    end
 
-    def preprocess_order_args(order_args)
-      order_args.map! do |arg|
-        klass.send(:sanitize_sql_for_order, arg)
+      def build_order(arel)
+        orders = order_values.uniq
+        orders.reject!(&:blank?)
+
+        arel.order(*orders) unless orders.empty?
       end
-      order_args.flatten!
-      validate_order_args(order_args)
 
-      references = order_args.grep(String)
-      references.map! { |arg| arg =~ /^([a-zA-Z]\w*)\.(\w+)/ && $1 }.compact!
-      references!(references) if references.any?
+      VALID_DIRECTIONS = [:asc, :desc, :ASC, :DESC,
+                          "asc", "desc", "ASC", "DESC"].to_set # :nodoc:
 
-      # if a symbol is given we prepend the quoted table name
-      order_args.map! do |arg|
-        case arg
-        when Symbol
-          arel_attribute(arg).asc
-        when Hash
-          arg.map { |field, dir|
-            arel_attribute(field).send(dir.downcase)
-          }
-        else
-          arg
+      def validate_order_args(args)
+        args.each do |arg|
+          next unless arg.is_a?(Hash)
+          arg.each do |_key, value|
+            unless VALID_DIRECTIONS.include?(value)
+              raise ArgumentError,
+                "Direction \"#{value}\" is invalid. Valid directions are: #{VALID_DIRECTIONS.to_a.inspect}"
+            end
+          end
         end
-      end.flatten!
-    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."
+      def preprocess_order_args(order_args)
+        order_args.reject!(&:blank?)
+        order_args.map! do |arg|
+          klass.sanitize_sql_for_order(arg)
+        end
+        order_args.flatten!
+
+        @klass.disallow_raw_sql!(
+          order_args.flat_map { |a| a.is_a?(Hash) ? a.keys : a },
+          permit: connection.column_name_with_order_matcher
+        )
+
+        validate_order_args(order_args)
+
+        references = order_args.grep(String)
+        references.map! { |arg| arg =~ /^\W?(\w+)\W?\./ && $1 }.compact!
+        references!(references) if references.any?
+
+        # if a symbol is given we prepend the quoted table name
+        order_args.map! do |arg|
+          case arg
+          when Symbol
+            order_column(arg.to_s).asc
+          when Hash
+            arg.map { |field, dir|
+              case field
+              when Arel::Nodes::SqlLiteral
+                field.send(dir.downcase)
+              else
+                order_column(field.to_s).send(dir.downcase)
+              end
+            }
+          else
+            arg
+          end
+        end.flatten!
       end
-    end
 
-    def structurally_incompatible_values_for_or(other)
-      Relation::SINGLE_VALUE_METHODS.reject { |m| send("#{m}_value") == other.send("#{m}_value") } +
-        (Relation::MULTI_VALUE_METHODS - [:extending]).reject { |m| send("#{m}_values") == other.send("#{m}_values") } +
-        (Relation::CLAUSE_METHODS - [:having, :where]).reject { |m| send("#{m}_clause") == other.send("#{m}_clause") }
-    end
+      def order_column(field)
+        arel_column(field) do |attr_name|
+          if attr_name == "count" && !group_values.empty?
+            arel_attribute(attr_name)
+          else
+            Arel.sql(connection.quote_table_name(attr_name))
+          end
+        end
+      end
 
-    def new_where_clause
-      Relation::WhereClause.empty
-    end
-    alias new_having_clause new_where_clause
+      # 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
 
-    def where_clause_factory
-      @where_clause_factory ||= Relation::WhereClauseFactory.new(klass, predicate_builder)
-    end
-    alias having_clause_factory where_clause_factory
+      STRUCTURAL_OR_METHODS = Relation::VALUE_METHODS - [:extending, :where, :having, :unscope, :references]
+      def structurally_incompatible_values_for_or(other)
+        values = other.values
+        STRUCTURAL_OR_METHODS.reject do |method|
+          default = DEFAULT_VALUES[method]
+          @values.fetch(method, default) == values.fetch(method, default)
+        end
+      end
 
-    def new_from_clause
-      Relation::FromClause.empty
-    end
+      def where_clause_factory
+        @where_clause_factory ||= Relation::WhereClauseFactory.new(klass, predicate_builder)
+      end
+      alias having_clause_factory where_clause_factory
 
-    def string_containing_comma?(value)
-      ::String === value && value.include?(",")
-    end
+      DEFAULT_VALUES = {
+        create_with: FROZEN_EMPTY_HASH,
+        where: Relation::WhereClause.empty,
+        having: Relation::WhereClause.empty,
+        from: Relation::FromClause.empty
+      }
+
+      Relation::MULTI_VALUE_METHODS.each do |value|
+        DEFAULT_VALUES[value] ||= FROZEN_EMPTY_ARRAY
+      end
   end
 end