Merge branch 'master' into adequaterecord

* master: (311 commits)
  Add a missing changelog entry for #13981 and #14035
  Revert "Fixed plugin_generator test"
  implements new option :month_format_string for date select helpers [Closes #13618]
  add factory methods for empty alias trackers
  guarantee a list in the alias tracker so we can remove a conditional
  stop exposing table_joins
  make most parameters to the AliasTracker required
  make a singleton for AssociationScope
  pass the association and connection to the scope method
  pass the tracker down the stack and construct it in the scope method
  clean up add_constraints signature
  remove the reflection delegate
  remove klass delegator
  remove railties changes. fixes #14054
  remove chain delegate
  remove scope_chain delegate
  Add verb to sanitization note
  fix path shown in mailer's templates
  updated Travis build status image url
  fix guide active_support_core_extensions. add Note to String#indent [ci skip]
  ...

Conflicts:
	activerecord/lib/active_record/associations/join_dependency.rb
	activerecord/test/cases/associations/association_scope_test.rb

3 files changed, 149 insertions, 37 deletions

diff --git a/activerecord/lib/active_record/relation/batches.rb b/activerecord/lib/active_record/relation/batches.rb
index 49b01909c6..29fc150b3d 100644
--- a/activerecord/lib/active_record/relation/batches.rb
+++ b/activerecord/lib/active_record/relation/batches.rb
@@ -52,7 +52,9 @@ module ActiveRecord
           records.each { |record| yield record }
         end
       else
-        enum_for :find_each, options
+        enum_for :find_each, options do
+          options[:start] ? where(table[primary_key].gteq(options[:start])).size : size
+        end
       end
     end
 
@@ -64,6 +66,16 @@ module ActiveRecord
     #     group.each { |person| person.party_all_night! }
     #   end
     #
+    # If you do not provide a block to #find_in_batches, it will return an Enumerator
+    # for chaining with other methods:
+    #
+    #   Person.find_in_batches.with_index do |group, batch|
+    #     puts "Processing group ##{batch}"
+    #     group.each(&:recover_from_last_night!)
+    #   end
+    #
+    # To be yielded each record one by one, use #find_each instead.
+    #
     # ==== Options
     # * <tt>:batch_size</tt> - Specifies the size of the batch. Default to 1000.
     # * <tt>:start</tt> - Specifies the starting point for the batch processing.
@@ -88,30 +100,33 @@ module ActiveRecord
       options.assert_valid_keys(:start, :batch_size)
 
       relation = self
+      start = options[:start]
+      batch_size = options[:batch_size] || 1000
+
+      unless block_given?
+        return to_enum(:find_in_batches, options) do
+          total = start ? where(table[primary_key].gteq(start)).size : size
+          (total - 1).div(batch_size) + 1
+        end
+      end
 
       if logger && (arel.orders.present? || arel.taken.present?)
         logger.warn("Scoped order and limit are ignored, it's forced to be batch order and batch size")
       end
 
-      start = options.delete(:start)
-      batch_size = options.delete(:batch_size) || 1000
-
       relation = relation.reorder(batch_order).limit(batch_size)
       records = start ? relation.where(table[primary_key].gteq(start)).to_a : relation.to_a
 
       while records.any?
         records_size = records.size
         primary_key_offset = records.last.id
+        raise "Primary key not included in the custom select clause" unless primary_key_offset
 
         yield records
 
         break if records_size < batch_size
 
-        if primary_key_offset
-          records = relation.where(table[primary_key].gt(primary_key_offset)).to_a
-        else
-          raise "Primary key not included in the custom select clause"
-        end
+        records = relation.where(table[primary_key].gt(primary_key_offset)).to_a
       end
     end
 
diff --git a/activerecord/lib/active_record/relation/finder_methods.rb b/activerecord/lib/active_record/relation/finder_methods.rb
index 64ac265689..4519a756a7 100644
--- a/activerecord/lib/active_record/relation/finder_methods.rb
+++ b/activerecord/lib/active_record/relation/finder_methods.rb
@@ -127,9 +127,9 @@ module ActiveRecord
     #
     def first(limit = nil)
       if limit
-        find_first_with_limit(limit)
+        find_nth_with_limit(offset_value, limit)
       else
-        find_first
+        find_nth(:first, offset_value)
       end
     end
 
@@ -172,6 +172,86 @@ module ActiveRecord
       last or raise RecordNotFound
     end
 
+    # Find the second record.
+    # If no order is defined it will order by primary key.
+    #
+    #   Person.second # returns the second object fetched by SELECT * FROM people
+    #   Person.offset(3).second # returns the second object from OFFSET 3 (which is OFFSET 4)
+    #   Person.where(["user_name = :u", { u: user_name }]).second
+    def second
+      find_nth(:second, offset_value ? offset_value + 1 : 1)
+    end
+
+    # Same as +second+ but raises <tt>ActiveRecord::RecordNotFound</tt> if no record
+    # is found.
+    def second!
+      second or raise RecordNotFound
+    end
+
+    # Find the third record.
+    # If no order is defined it will order by primary key.
+    #
+    #   Person.third # returns the third object fetched by SELECT * FROM people
+    #   Person.offset(3).third # returns the third object from OFFSET 3 (which is OFFSET 5)
+    #   Person.where(["user_name = :u", { u: user_name }]).third
+    def third
+      find_nth(:third, offset_value ? offset_value + 2 : 2)
+    end
+
+    # Same as +third+ but raises <tt>ActiveRecord::RecordNotFound</tt> if no record
+    # is found.
+    def third!
+      third or raise RecordNotFound
+    end
+
+    # Find the fourth record.
+    # If no order is defined it will order by primary key.
+    #
+    #   Person.fourth # returns the fourth object fetched by SELECT * FROM people
+    #   Person.offset(3).fourth # returns the fourth object from OFFSET 3 (which is OFFSET 6)
+    #   Person.where(["user_name = :u", { u: user_name }]).fourth
+    def fourth
+      find_nth(:fourth, offset_value ? offset_value + 3 : 3)
+    end
+
+    # Same as +fourth+ but raises <tt>ActiveRecord::RecordNotFound</tt> if no record
+    # is found.
+    def fourth!
+      fourth or raise RecordNotFound
+    end
+
+    # Find the fifth record.
+    # If no order is defined it will order by primary key.
+    #
+    #   Person.fifth # returns the fifth object fetched by SELECT * FROM people
+    #   Person.offset(3).fifth # returns the fifth object from OFFSET 3 (which is OFFSET 7)
+    #   Person.where(["user_name = :u", { u: user_name }]).fifth
+    def fifth
+      find_nth(:fifth, offset_value ? offset_value + 4 : 4)
+    end
+
+    # Same as +fifth+ but raises <tt>ActiveRecord::RecordNotFound</tt> if no record
+    # is found.
+    def fifth!
+      fifth or raise RecordNotFound
+    end
+
+    # Find the forty-second record. Also known as accessing "the reddit".
+    # If no order is defined it will order by primary key.
+    #
+    #   Person.forty_two # returns the forty-second object fetched by SELECT * FROM people
+    #   Person.offset(3).forty_two # returns the fifth object from OFFSET 3 (which is OFFSET 44)
+    #   Person.where(["user_name = :u", { u: user_name }]).forty_two
+    def forty_two
+      find_nth(:forty_two, offset_value ? offset_value + 41 : 41)
+    end
+
+    # Same as +forty_two+ but raises <tt>ActiveRecord::RecordNotFound</tt> if no record
+    # is found.
+    def forty_two!
+      forty_two or raise RecordNotFound
+    end
+
     # Returns +true+ if a record exists in the table that matches the +id+ or
     # conditions given, or +false+ otherwise. The argument can take six forms:
     #
@@ -231,9 +311,9 @@ module ActiveRecord
       conditions = " [#{conditions}]" if conditions
 
       if Array(ids).size == 1
-        error = "Couldn't find #{@klass.name} with #{primary_key}=#{ids}#{conditions}"
+        error = "Couldn't find #{@klass.name} with '#{primary_key}'=#{ids}#{conditions}"
       else
-        error = "Couldn't find all #{@klass.name.pluralize} with IDs "
+        error = "Couldn't find all #{@klass.name.pluralize} with '#{primary_key}': "
         error << "(#{ids.join(", ")})#{conditions} (found #{result_size} results, but was looking for #{expected_size})"
       end
 
@@ -268,7 +348,15 @@ module ActiveRecord
     end
 
     def construct_relation_for_association_calculations
-      apply_join_dependency(self, construct_join_dependency(arel.froms.first))
+      from = arel.froms.first
+      if Arel::Table === from
+        apply_join_dependency(self, construct_join_dependency)
+      else
+        # FIXME: as far as I can tell, `from` will always be an Arel::Table.
+        # There are no tests that test this branch, but presumably it's
+        # possible for `from` to be a list?
+        apply_join_dependency(self, construct_join_dependency(from))
+      end
     end
 
     def apply_join_dependency(relation, join_dependency)
@@ -365,19 +453,19 @@ module ActiveRecord
       end
     end
 
-    def find_first
+    def find_nth(ordinal, offset)
       if loaded?
-        @records.first
+        @records.send(ordinal)
       else
-        @first ||= find_first_with_limit(1).first
+        @offsets[offset] ||= find_nth_with_limit(offset, 1).first
       end
     end
 
-    def find_first_with_limit(limit)
+    def find_nth_with_limit(offset, limit)
       if order_values.empty? && primary_key
-        order(arel_table[primary_key].asc).limit(limit).to_a
+        order(arel_table[primary_key].asc).limit(limit).offset(offset).to_a
       else
-        limit(limit).to_a
+        limit(limit).offset(offset).to_a
       end
     end
 
diff --git a/activerecord/lib/active_record/relation/query_methods.rb b/activerecord/lib/active_record/relation/query_methods.rb
index 6cf57b679d..7d2b427289 100644
--- a/activerecord/lib/active_record/relation/query_methods.rb
+++ b/activerecord/lib/active_record/relation/query_methods.rb
@@ -120,6 +120,9 @@ module ActiveRecord
     # Will throw an error, but this will work:
     #
     #   User.includes(:posts).where('posts.name = ?', 'example').references(:posts)
+    #
+    # Note that +includes+ works with association names while +references+ needs
+    # the actual table name.
     def includes(*args)
       check_if_method_has_arguments!(:includes, args)
       spawn.includes!(*args)
@@ -163,24 +166,26 @@ module ActiveRecord
       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.
+    # 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 conjuction with +includes+.
+    # See #includes for more details.
     #
     #   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)
+    def references(*table_names)
+      check_if_method_has_arguments!(:references, table_names)
+      spawn.references!(*table_names)
     end
 
-    def references!(*args) # :nodoc:
-      args.flatten!
-      args.map!(&:to_s)
+    def references!(*table_names) # :nodoc:
+      table_names.flatten!
+      table_names.map!(&:to_s)
 
-      self.references_values |= args
+      self.references_values |= table_names
       self
     end
 
@@ -234,7 +239,9 @@ module ActiveRecord
 
     def select!(*fields) # :nodoc:
       fields.flatten!
-
+      fields.map! do |field|
+        klass.attribute_alias?(field) ? klass.attribute_alias(field).to_sym : field
+      end
       self.select_values += fields
       self
     end
@@ -817,11 +824,12 @@ module ActiveRecord
     end
 
     # Returns the Arel object associated with the relation.
-    def arel
+    def arel # :nodoc:
       @arel ||= build_arel
     end
 
-    # Like #arel, but ignores the default scope of the model.
+    private
+
     def build_arel
       arel = Arel::SelectManager.new(table.engine, table)
 
@@ -856,8 +864,6 @@ module ActiveRecord
       arel
     end
 
-    private
-
     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(", :")}."
@@ -887,8 +893,6 @@ module ActiveRecord
         when Arel::Nodes::In, Arel::Nodes::NotIn, Arel::Nodes::Equality, Arel::Nodes::NotEqual
           subrelation = (rel.left.kind_of?(Arel::Attributes::Attribute) ? rel.left : rel.right)
           subrelation.name == target_value
-        else
-          raise "unscope(where: #{target_value.inspect}) failed: unscoping #{rel.class} is unimplemented."
         end
       end
 
@@ -1022,7 +1026,10 @@ module ActiveRecord
 
     def build_select(arel, selects)
       if !selects.empty?
-        arel.project(*selects)
+        expanded_select = selects.map do |field|
+          columns_hash.key?(field.to_s) ? arel_table[field] : field
+        end
+        arel.project(*expanded_select)
       elsif from_value
         arel.project(Arel.star)
       else
@@ -1080,9 +1087,11 @@ module ActiveRecord
       order_args.map! do |arg|
         case arg
         when Symbol
+          arg = klass.attribute_alias(arg).to_sym if klass.attribute_alias?(arg)
           table[arg].asc
         when Hash
           arg.map { |field, dir|
+            field = klass.attribute_alias(field).to_sym if klass.attribute_alias?(field)
             table[field].send(dir)
           }
         else