activerecord 6.1.4.1 → 7.0.0.rc2

data/lib/active_record/persistence.rb

@@ -63,8 +63,8 @@ module ActiveRecord
       # go through Active Record's type casting and serialization.
       #
       # See <tt>ActiveRecord::Persistence#insert_all</tt> for documentation.
-      def insert(attributes, returning: nil, unique_by: nil)
-        insert_all([ attributes ], returning: returning, unique_by: unique_by)
+      def insert(attributes, returning: nil, unique_by: nil, record_timestamps: nil)
+        insert_all([ attributes ], returning: returning, unique_by: unique_by, record_timestamps: record_timestamps)
       end
 
       # Inserts multiple records into the database in a single SQL INSERT
@@ -91,6 +91,9 @@ module ActiveRecord
       #   or <tt>returning: false</tt> to omit the underlying <tt>RETURNING</tt> SQL
       #   clause entirely.
       #
+      #   You can also pass an SQL string if you need more control on the return values
+      #   (for example, <tt>returning: "id, name as new_name"</tt>).
+      #
       # [:unique_by]
       #   (PostgreSQL and SQLite only) By default rows are considered to be unique
       #   by every unique index on the table. Any duplicate rows are skipped.
@@ -107,6 +110,17 @@ module ActiveRecord
       #     unique_by: %i[ author_id name ]
       #     unique_by: :index_books_on_isbn
       #
+      # [:record_timestamps]
+      #   By default, automatic setting of timestamp columns is controlled by
+      #   the model's <tt>record_timestamps</tt> config, matching typical
+      #   behavior.
+      #
+      #   To override this and force automatic setting of timestamp columns one
+      #   way or the other, pass <tt>:record_timestamps</tt>:
+      #
+      #     record_timestamps: true  # Always set timestamps automatically
+      #     record_timestamps: false # Never set timestamps automatically
+      #
       # Because it relies on the index information from the database
       # <tt>:unique_by</tt> is recommended to be paired with
       # Active Record's schema_cache.
@@ -120,8 +134,16 @@ module ActiveRecord
       #     { id: 1, title: "Rework", author: "David" },
       #     { id: 1, title: "Eloquent Ruby", author: "Russ" }
       #   ])
-      def insert_all(attributes, returning: nil, unique_by: nil)
-        InsertAll.new(self, attributes, on_duplicate: :skip, returning: returning, unique_by: unique_by).execute
+      #
+      #   # insert_all works on chained scopes, and you can use create_with
+      #   # to set default attributes for all inserted records.
+      #
+      #   author.books.create_with(created_at: Time.now).insert_all([
+      #     { id: 1, title: "Rework" },
+      #     { id: 2, title: "Eloquent Ruby" }
+      #   ])
+      def insert_all(attributes, returning: nil, unique_by: nil, record_timestamps: nil)
+        InsertAll.new(self, attributes, on_duplicate: :skip, returning: returning, unique_by: unique_by, record_timestamps: record_timestamps).execute
       end
 
       # Inserts a single record into the database in a single SQL INSERT
@@ -130,8 +152,8 @@ module ActiveRecord
       # go through Active Record's type casting and serialization.
       #
       # See <tt>ActiveRecord::Persistence#insert_all!</tt> for more.
-      def insert!(attributes, returning: nil)
-        insert_all!([ attributes ], returning: returning)
+      def insert!(attributes, returning: nil, record_timestamps: nil)
+        insert_all!([ attributes ], returning: returning, record_timestamps: record_timestamps)
       end
 
       # Inserts multiple records into the database in a single SQL INSERT
@@ -160,6 +182,20 @@ module ActiveRecord
       #   or <tt>returning: false</tt> to omit the underlying <tt>RETURNING</tt> SQL
       #   clause entirely.
       #
+      #   You can also pass an SQL string if you need more control on the return values
+      #   (for example, <tt>returning: "id, name as new_name"</tt>).
+      #
+      # [:record_timestamps]
+      #   By default, automatic setting of timestamp columns is controlled by
+      #   the model's <tt>record_timestamps</tt> config, matching typical
+      #   behavior.
+      #
+      #   To override this and force automatic setting of timestamp columns one
+      #   way or the other, pass <tt>:record_timestamps</tt>:
+      #
+      #     record_timestamps: true  # Always set timestamps automatically
+      #     record_timestamps: false # Never set timestamps automatically
+      #
       # ==== Examples
       #
       #   # Insert multiple records
@@ -174,8 +210,8 @@ module ActiveRecord
       #     { id: 1, title: "Rework", author: "David" },
       #     { id: 1, title: "Eloquent Ruby", author: "Russ" }
       #   ])
-      def insert_all!(attributes, returning: nil)
-        InsertAll.new(self, attributes, on_duplicate: :raise, returning: returning).execute
+      def insert_all!(attributes, returning: nil, record_timestamps: nil)
+        InsertAll.new(self, attributes, on_duplicate: :raise, returning: returning, record_timestamps: record_timestamps).execute
       end
 
       # Updates or inserts (upserts) a single record into the database in a
@@ -184,8 +220,8 @@ module ActiveRecord
       # go through Active Record's type casting and serialization.
       #
       # See <tt>ActiveRecord::Persistence#upsert_all</tt> for documentation.
-      def upsert(attributes, returning: nil, unique_by: nil)
-        upsert_all([ attributes ], returning: returning, unique_by: unique_by)
+      def upsert(attributes, on_duplicate: :update, returning: nil, unique_by: nil, record_timestamps: nil)
+        upsert_all([ attributes ], on_duplicate: on_duplicate, returning: returning, unique_by: unique_by, record_timestamps: record_timestamps)
       end
 
       # Updates or inserts (upserts) multiple records into the database in a
@@ -199,6 +235,10 @@ module ActiveRecord
       # Returns an <tt>ActiveRecord::Result</tt> with its contents based on
       # <tt>:returning</tt> (see below).
       #
+      # By default, +upsert_all+ will update all the columns that can be updated when
+      # there is a conflict. These are all the columns except primary keys, read-only
+      # columns, and columns covered by the optional +unique_by+.
+      #
       # ==== Options
       #
       # [:returning]
@@ -208,6 +248,9 @@ module ActiveRecord
       #   or <tt>returning: false</tt> to omit the underlying <tt>RETURNING</tt> SQL
       #   clause entirely.
       #
+      #   You can also pass an SQL string if you need more control on the return values
+      #   (for example, <tt>returning: "id, name as new_name"</tt>).
+      #
       # [:unique_by]
       #   (PostgreSQL and SQLite only) By default rows are considered to be unique
       #   by every unique index on the table. Any duplicate rows are skipped.
@@ -228,6 +271,54 @@ module ActiveRecord
       # <tt>:unique_by</tt> is recommended to be paired with
       # Active Record's schema_cache.
       #
+      # [:on_duplicate]
+      #   Configure the SQL update sentence that will be used in case of conflict.
+      #
+      #   NOTE: If you use this option you must provide all the columns you want to update
+      #   by yourself.
+      #
+      #   Example:
+      #
+      #     Commodity.upsert_all(
+      #       [
+      #         { id: 2, name: "Copper", price: 4.84 },
+      #         { id: 4, name: "Gold", price: 1380.87 },
+      #         { id: 6, name: "Aluminium", price: 0.35 }
+      #       ],
+      #       on_duplicate: Arel.sql("price = GREATEST(commodities.price, EXCLUDED.price)")
+      #     )
+      #
+      #   See the related +:update_only+ option. Both options can't be used at the same time.
+      #
+      # [:update_only]
+      #   Provide a list of column names that will be updated in case of conflict. If not provided,
+      #   +upsert_all+ will update all the columns that can be updated. These are all the columns
+      #   except primary keys, read-only columns, and columns covered by the optional +unique_by+
+      #
+      #   Example:
+      #
+      #     Commodity.upsert_all(
+      #       [
+      #         { id: 2, name: "Copper", price: 4.84 },
+      #         { id: 4, name: "Gold", price: 1380.87 },
+      #         { id: 6, name: "Aluminium", price: 0.35 }
+      #       ],
+      #       update_only: [:price] # Only prices will be updated
+      #     )
+      #
+      #   See the related +:on_duplicate+ option. Both options can't be used at the same time.
+      #
+      # [:record_timestamps]
+      #   By default, automatic setting of timestamp columns is controlled by
+      #   the model's <tt>record_timestamps</tt> config, matching typical
+      #   behavior.
+      #
+      #   To override this and force automatic setting of timestamp columns one
+      #   way or the other, pass <tt>:record_timestamps</tt>:
+      #
+      #     record_timestamps: true  # Always set timestamps automatically
+      #     record_timestamps: false # Never set timestamps automatically
+      #
       # ==== Examples
       #
       #   # Inserts multiple records, performing an upsert when records have duplicate ISBNs.
@@ -239,8 +330,8 @@ module ActiveRecord
       #   ], unique_by: :isbn)
       #
       #   Book.find_by(isbn: "1").title # => "Eloquent Ruby"
-      def upsert_all(attributes, returning: nil, unique_by: nil)
-        InsertAll.new(self, attributes, on_duplicate: :update, returning: returning, unique_by: unique_by).execute
+      def upsert_all(attributes, on_duplicate: :update, update_only: nil, returning: nil, unique_by: nil, record_timestamps: nil)
+        InsertAll.new(self, attributes, on_duplicate: on_duplicate, update_only: update_only, returning: returning, unique_by: unique_by, record_timestamps: record_timestamps).execute
       end
 
       # Given an attributes hash, +instantiate+ returns a new instance of
@@ -264,6 +355,7 @@ module ActiveRecord
       # ==== Parameters
       #
       # * +id+ - This should be the id or an array of ids to be updated.
+      #   Optional argument, defaults to all records in the relation.
       # * +attributes+ - This should be a hash of attributes or an array of hashes.
       #
       # ==== Examples
@@ -286,6 +378,11 @@ module ActiveRecord
       # for updating all records in a single query.
       def update(id = :all, attributes)
         if id.is_a?(Array)
+          if id.any?(ActiveRecord::Base)
+            raise ArgumentError,
+              "You are passing an array of ActiveRecord::Base instances to `update`. " \
+              "Please pass the ids of the objects by calling `pluck(:id)` or `map(&:id)`."
+          end
           id.map { |one_id| find(one_id) }.each_with_index { |object, idx|
             object.update(attributes[idx])
           }
@@ -303,6 +400,32 @@ module ActiveRecord
         end
       end
 
+      # Updates the object (or multiple objects) just like #update but calls #update! instead
+      # of +update+, so an exception is raised if the record is invalid and saving will fail.
+      def update!(id = :all, attributes)
+        if id.is_a?(Array)
+          if id.any?(ActiveRecord::Base)
+            raise ArgumentError,
+              "You are passing an array of ActiveRecord::Base instances to `update!`. " \
+              "Please pass the ids of the objects by calling `pluck(:id)` or `map(&:id)`."
+          end
+          id.map { |one_id| find(one_id) }.each_with_index { |object, idx|
+            object.update!(attributes[idx])
+          }
+        elsif id == :all
+          all.each { |record| record.update!(attributes) }
+        else
+          if ActiveRecord::Base === id
+            raise ArgumentError,
+              "You are passing an instance of ActiveRecord::Base to `update!`. " \
+              "Please pass the id of the object by calling `.id`."
+          end
+          object = find(id)
+          object.update!(attributes)
+          object
+        end
+      end
+
       # Destroy an object (or multiple objects) that has the given id. The object is instantiated first,
       # therefore all callbacks and filters are fired off before the object is deleted. This method is
       # less efficient than #delete but allows cleanup methods and other actions to be run.
@@ -356,40 +479,52 @@ module ActiveRecord
         primary_key = self.primary_key
         primary_key_value = nil
 
-        if primary_key && Hash === values
-          primary_key_value = values[primary_key]
-
-          if !primary_key_value && prefetch_primary_key?
+        if prefetch_primary_key? && primary_key
+          values[primary_key] ||= begin
             primary_key_value = next_sequence_value
-            values[primary_key] = primary_key_value
+            _default_attributes[primary_key].with_cast_value(primary_key_value)
           end
         end
 
+        im = Arel::InsertManager.new(arel_table)
+
         if values.empty?
-          im = arel_table.compile_insert(connection.empty_insert_statement_value(primary_key))
-          im.into arel_table
+          im.insert(connection.empty_insert_statement_value(primary_key))
         else
-          im = arel_table.compile_insert(_substitute_values(values))
+          im.insert(values.transform_keys { |name| arel_table[name] })
         end
 
         connection.insert(im, "#{self} Create", primary_key || false, primary_key_value)
       end
 
       def _update_record(values, constraints) # :nodoc:
-        constraints = _substitute_values(constraints).map { |attr, bind| attr.eq(bind) }
+        constraints = constraints.map { |name, value| predicate_builder[name, value] }
+
+        default_constraint = build_default_constraint
+        constraints << default_constraint if default_constraint
+
+        if current_scope = self.global_current_scope
+          constraints << current_scope.where_clause.ast
+        end
 
-        um = arel_table.where(
-          constraints.reduce(&:and)
-        ).compile_update(_substitute_values(values), primary_key)
+        um = Arel::UpdateManager.new(arel_table)
+        um.set(values.transform_keys { |name| arel_table[name] })
+        um.wheres = constraints
 
         connection.update(um, "#{self} Update")
       end
 
       def _delete_record(constraints) # :nodoc:
-        constraints = _substitute_values(constraints).map { |attr, bind| attr.eq(bind) }
+        constraints = constraints.map { |name, value| predicate_builder[name, value] }
 
-        dm = Arel::DeleteManager.new
-        dm.from(arel_table)
+        default_constraint = build_default_constraint
+        constraints << default_constraint if default_constraint
+
+        if current_scope = self.global_current_scope
+          constraints << current_scope.where_clause.ast
+        end
+
+        dm = Arel::DeleteManager.new(arel_table)
         dm.wheres = constraints
 
         connection.delete(dm, "#{self} Destroy")
@@ -412,12 +547,14 @@ module ActiveRecord
           self
         end
 
-        def _substitute_values(values)
-          values.map do |name, value|
-            attr = arel_table[name]
-            bind = predicate_builder.build_bind_attribute(attr.name, value)
-            [attr, bind]
-          end
+        # Called by +_update_record+ and +_delete_record+
+        # to build `where` clause from default scopes.
+        # Skips empty scopes.
+        def build_default_constraint
+          return unless default_scopes?(all_queries: true)
+
+          default_where_clause = default_scoped(all_queries: true).where_clause
+          default_where_clause.ast unless default_where_clause.empty?
         end
     end
 
@@ -434,6 +571,11 @@ module ActiveRecord
       @previously_new_record
     end
 
+    # Returns true if this object was previously persisted but now it has been deleted.
+    def previously_persisted?
+      !new_record? && destroyed?
+    end
+
     # Returns true if this object has been destroyed, otherwise returns false.
     def destroyed?
       @destroyed
@@ -556,17 +698,17 @@ module ActiveRecord
     end
 
     # Returns an instance of the specified +klass+ with the attributes of the
-    # current record. This is mostly useful in relation to single-table
-    # inheritance structures where you want a subclass to appear as the
+    # current record. This is mostly useful in relation to single table
+    # inheritance (STI) structures where you want a subclass to appear as the
     # superclass. This can be used along with record identification in
     # Action Pack to allow, say, <tt>Client < Company</tt> to do something
     # like render <tt>partial: @client.becomes(Company)</tt> to render that
     # instance using the companies/company partial instead of clients/client.
     #
     # Note: The new instance will share a link to the same attributes as the original class.
-    # Therefore the sti column value will still be the same.
+    # Therefore the STI column value will still be the same.
     # Any change to the attributes on either instance will affect both instances.
-    # If you want to change the sti column as well, use #becomes! instead.
+    # If you want to change the STI column as well, use #becomes! instead.
     def becomes(klass)
       became = klass.allocate
 
@@ -581,11 +723,11 @@ module ActiveRecord
       became
     end
 
-    # Wrapper around #becomes that also changes the instance's sti column value.
+    # Wrapper around #becomes that also changes the instance's STI column value.
     # This is especially useful if you want to persist the changed class in your
     # database.
     #
-    # Note: The old instance's sti column value will be changed too, as both objects
+    # Note: The old instance's STI column value will be changed too, as both objects
     # share the same set of attributes.
     def becomes!(klass)
       became = becomes(klass)
@@ -671,14 +813,15 @@ module ActiveRecord
         verify_readonly_attribute(name) || name
       end
 
-      id_in_database = self.id_in_database
-      attributes.each do |k, v|
-        write_attribute_without_type_cast(k, v)
+      update_constraints = _primary_key_constraints_hash
+      attributes = attributes.each_with_object({}) do |(k, v), h|
+        h[k] = @attributes.write_cast_value(k, v)
+        clear_attribute_change(k)
       end
 
       affected_rows = self.class._update_record(
         attributes,
-        @primary_key => id_in_database
+        update_constraints
       )
 
       affected_rows == 1
@@ -800,13 +943,13 @@ module ActiveRecord
     def reload(options = nil)
       self.class.connection.clear_query_cache
 
-      fresh_object =
-        if options && options[:lock]
-          self.class.unscoped { self.class.lock(options[:lock]).find(id) }
-        else
-          self.class.unscoped { self.class.find(id) }
-        end
+      fresh_object = if apply_scoping?(options)
+        _find_record(options)
+      else
+        self.class.unscoped { _find_record(options) }
+      end
 
+      @association_cache = fresh_object.instance_variable_get(:@association_cache)
       @attributes = fresh_object.instance_variable_get(:@attributes)
       @new_record = false
       @previously_new_record = false
@@ -865,6 +1008,29 @@ module ActiveRecord
     end
 
   private
+    def strict_loaded_associations
+      @association_cache.find_all do |_, assoc|
+        assoc.owner.strict_loading? && !assoc.owner.strict_loading_n_plus_one_only?
+      end.map(&:first)
+    end
+
+    def _find_record(options)
+      if options && options[:lock]
+        self.class.preload(strict_loaded_associations).lock(options[:lock]).find(id)
+      else
+        self.class.preload(strict_loaded_associations).find(id)
+      end
+    end
+
+    def apply_scoping?(options)
+      !(options && options[:unscoped]) &&
+        (self.class.default_scopes?(all_queries: true) || self.class.global_current_scope)
+    end
+
+    def _primary_key_constraints_hash
+      { @primary_key => id_in_database }
+    end
+
     # A hook to be overridden by association modules.
     def destroy_associations
     end
@@ -874,7 +1040,7 @@ module ActiveRecord
     end
 
     def _delete_row
-      self.class._delete_record(@primary_key => id_in_database)
+      self.class._delete_record(_primary_key_constraints_hash)
     end
 
     def _touch_row(attribute_names, time)
@@ -890,7 +1056,7 @@ module ActiveRecord
     def _update_row(attribute_names, attempted_action = "update")
       self.class._update_record(
         attributes_with_values(attribute_names),
-        @primary_key => id_in_database
+        _primary_key_constraints_hash
       )
     end
 
@@ -946,7 +1112,8 @@ module ActiveRecord
 
     def _raise_record_not_destroyed
       @_association_destroy_exception ||= nil
-      raise @_association_destroy_exception || RecordNotDestroyed.new("Failed to destroy the record", self)
+      key = self.class.primary_key
+      raise @_association_destroy_exception || RecordNotDestroyed.new("Failed to destroy #{self.class} with #{key}=#{send(key)}", self)
     ensure
       @_association_destroy_exception = nil
     end

data/lib/active_record/query_cache.rb

@@ -28,7 +28,7 @@ module ActiveRecord
     def self.run
       pools = []
 
-      if ActiveRecord::Base.legacy_connection_handling
+      if ActiveRecord.legacy_connection_handling
         ActiveRecord::Base.connection_handlers.each do |key, handler|
           pools.concat(handler.connection_pool_list.reject { |p| p.query_cache_enabled }.each { |p| p.enable_query_cache! })
         end
@@ -42,7 +42,7 @@ module ActiveRecord
     def self.complete(pools)
       pools.each { |pool| pool.disable_query_cache! }
 
-      if ActiveRecord::Base.legacy_connection_handling
+      if ActiveRecord.legacy_connection_handling
         ActiveRecord::Base.connection_handlers.each do |_, handler|
           handler.connection_pool_list.each do |pool|
             pool.release_connection if pool.active_connection? && !pool.connection.transaction_open?

data/lib/active_record/query_logs.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/attribute_accessors_per_thread"
+
+module ActiveRecord
+  # = Active Record Query Logs
+  #
+  # Automatically tag SQL queries with runtime information.
+  #
+  # Default tags available for use:
+  #
+  # * +application+
+  # * +pid+
+  # * +socket+
+  # * +db_host+
+  # * +database+
+  #
+  # _Action Controller and Active Job tags are also defined when used in Rails:_
+  #
+  # * +controller+
+  # * +action+
+  # * +job+
+  #
+  # The tags used in a query can be configured directly:
+  #
+  #     ActiveRecord::QueryLogs.tags = [ :application, :controller, :action, :job ]
+  #
+  # or via Rails configuration:
+  #
+  #     config.active_record.query_log_tags = [ :application, :controller, :action, :job ]
+  #
+  # To add new comment tags, add a hash to the tags array containing the keys and values you
+  # want to add to the comment. Dynamic content can be created by setting a proc or lambda value in a hash,
+  # and can reference any value stored in the +context+ object.
+  #
+  # Example:
+  #
+  #    tags = [
+  #      :application,
+  #      {
+  #        custom_tag: ->(context) { context[:controller]&.controller_name },
+  #        custom_value: -> { Custom.value },
+  #      }
+  #    ]
+  #    ActiveRecord::QueryLogs.tags = tags
+  #
+  # The QueryLogs +context+ can be manipulated via the +ActiveSupport::ExecutionContext.set+ method.
+  #
+  # Temporary updates limited to the execution of a block:
+  #
+  #    ActiveSupport::ExecutionContext.set(foo: Bar.new) do
+  #      posts = Post.all
+  #    end
+  #
+  # Direct updates to a context value:
+  #
+  #    ActiveSupport::ExecutionContext[:foo] = Bar.new
+  #
+  # Tag comments can be prepended to the query:
+  #
+  #    ActiveRecord::QueryLogs.prepend_comment = true
+  #
+  # For applications where the content will not change during the lifetime of
+  # the request or job execution, the tags can be cached for reuse in every query:
+  #
+  #    ActiveRecord::QueryLogs.cache_query_log_tags = true
+  #
+  # This option can be set during application configuration or in a Rails initializer:
+  #
+  #    config.active_record.cache_query_log_tags = true
+  module QueryLogs
+    mattr_accessor :taggings, instance_accessor: false, default: {}
+    mattr_accessor :tags, instance_accessor: false, default: [ :application ]
+    mattr_accessor :prepend_comment, instance_accessor: false, default: false
+    mattr_accessor :cache_query_log_tags, instance_accessor: false, default: false
+    thread_mattr_accessor :cached_comment, instance_accessor: false
+
+    class << self
+      def call(sql) # :nodoc:
+        if prepend_comment
+          "#{self.comment} #{sql}"
+        else
+          "#{sql} #{self.comment}"
+        end.strip
+      end
+
+      def clear_cache # :nodoc:
+        self.cached_comment = nil
+      end
+
+      ActiveSupport::ExecutionContext.after_change { ActiveRecord::QueryLogs.clear_cache }
+
+      private
+        # Returns an SQL comment +String+ containing the query log tags.
+        # Sets and returns a cached comment if <tt>cache_query_log_tags</tt> is +true+.
+        def comment
+          if cache_query_log_tags
+            self.cached_comment ||= uncached_comment
+          else
+            uncached_comment
+          end
+        end
+
+        def uncached_comment
+          content = tag_content
+          if content.present?
+            "/*#{escape_sql_comment(content)}*/"
+          end
+        end
+
+        def escape_sql_comment(content)
+          content.to_s.gsub(%r{ (/ (?: | \g<1>) \*) \+? \s* | \s* (\* (?: | \g<2>) /) }x, "")
+        end
+
+        def tag_content
+          context = ActiveSupport::ExecutionContext.to_h
+
+          tags.flat_map { |i| [*i] }.filter_map do |tag|
+            key, handler = tag
+            handler ||= taggings[key]
+
+            val = if handler.nil?
+              context[key]
+            elsif handler.respond_to?(:call)
+              if handler.arity == 0
+                handler.call
+              else
+                handler.call(context)
+              end
+            else
+              handler
+            end
+            "#{key}:#{val}" unless val.nil?
+          end.join(",")
+        end
+    end
+  end
+end

data/lib/active_record/querying.rb

@@ -3,7 +3,7 @@
 module ActiveRecord
   module Querying
     QUERYING_METHODS = [
-      :find, :find_by, :find_by!, :take, :take!, :first, :first!, :last, :last!,
+      :find, :find_by, :find_by!, :take, :take!, :sole, :find_sole_by, :first, :first!, :last, :last!,
       :second, :second!, :third, :third!, :fourth, :fourth!, :fifth, :fifth!,
       :forty_two, :forty_two!, :third_to_last, :third_to_last!, :second_to_last, :second_to_last!,
       :exists?, :any?, :many?, :none?, :one?,
@@ -12,12 +12,12 @@ module ActiveRecord
       :create_or_find_by, :create_or_find_by!,
       :destroy_all, :delete_all, :update_all, :touch_all, :destroy_by, :delete_by,
       :find_each, :find_in_batches, :in_batches,
-      :select, :reselect, :order, :reorder, :group, :limit, :offset, :joins, :left_joins, :left_outer_joins,
-      :where, :rewhere, :preload, :extract_associated, :eager_load, :includes, :from, :lock, :readonly,
+      :select, :reselect, :order, :in_order_of, :reorder, :group, :limit, :offset, :joins, :left_joins, :left_outer_joins,
+      :where, :rewhere, :invert_where, :preload, :extract_associated, :eager_load, :includes, :from, :lock, :readonly,
       :and, :or, :annotate, :optimizer_hints, :extending,
       :having, :create_with, :distinct, :references, :none, :unscope, :merge, :except, :only,
       :count, :average, :minimum, :maximum, :sum, :calculate,
-      :pluck, :pick, :ids, :strict_loading
+      :pluck, :pick, :ids, :strict_loading, :excluding, :without
     ].freeze # :nodoc:
     delegate(*QUERYING_METHODS, to: :all)
 
@@ -43,8 +43,18 @@ module ActiveRecord
     #
     #   Post.find_by_sql ["SELECT title FROM posts WHERE author = ? AND created > ?", author_id, start_date]
     #   Post.find_by_sql ["SELECT body FROM comments WHERE author = :user_id OR approved_by = :user_id", { :user_id => user_id }]
+    #
+    # Note that building your own SQL query string from user input may expose your application to
+    # injection attacks (https://guides.rubyonrails.org/security.html#sql-injection).
     def find_by_sql(sql, binds = [], preparable: nil, &block)
-      result_set = connection.select_all(sanitize_sql(sql), "#{name} Load", binds, preparable: preparable)
+      _load_from_sql(_query_by_sql(sql, binds, preparable: preparable), &block)
+    end
+
+    def _query_by_sql(sql, binds = [], preparable: nil, async: false) # :nodoc:
+      connection.select_all(sanitize_sql(sql), "#{name} Load", binds, preparable: preparable, async: async)
+    end
+
+    def _load_from_sql(result_set, &block) # :nodoc:
       column_types = result_set.column_types
 
       unless column_types.empty?