activerecord 7.0.8.7 → 7.2.2.1

data/lib/active_record/core.rb

@@ -1,29 +1,50 @@
 # frozen_string_literal: true
 
 require "active_support/core_ext/enumerable"
-require "active_support/core_ext/hash/indifferent_access"
-require "active_support/core_ext/string/filters"
+require "active_support/core_ext/module/delegation"
 require "active_support/parameter_filter"
 require "concurrent/map"
 
 module ActiveRecord
+  # = Active Record \Core
   module Core
     extend ActiveSupport::Concern
+    include ActiveModel::Access
 
     included do
       ##
       # :singleton-method:
       #
-      # Accepts a logger conforming to the interface of Log4r which is then
-      # passed on to any new database connections made and which can be
-      # retrieved on both a class and instance level by calling +logger+.
+      # Accepts a logger conforming to the interface of Log4r or the default
+      # Ruby +Logger+ class, which is then passed on to any new database
+      # connections made. You can retrieve this logger by calling +logger+ on
+      # either an Active Record model class or an Active Record model instance.
       class_attribute :logger, instance_writer: false
 
+      class_attribute :_destroy_association_async_job, instance_accessor: false, default: "ActiveRecord::DestroyAssociationAsyncJob"
+
+      # The job class used to destroy associations in the background.
+      def self.destroy_association_async_job
+        if _destroy_association_async_job.is_a?(String)
+          self._destroy_association_async_job = _destroy_association_async_job.constantize
+        end
+        _destroy_association_async_job
+      rescue NameError => error
+        raise NameError, "Unable to load destroy_association_async_job: #{error.message}"
+      end
+
+      singleton_class.alias_method :destroy_association_async_job=, :_destroy_association_async_job=
+      delegate :destroy_association_async_job, to: :class
+
       ##
       # :singleton-method:
       #
-      # Specifies the job used to destroy associations in the background
-      class_attribute :destroy_association_async_job, instance_writer: false, instance_predicate: false, default: false
+      # Specifies the maximum number of records that will be destroyed in a
+      # single background job by the <tt>dependent: :destroy_async</tt>
+      # association option. When +nil+ (default), all dependent records will be
+      # destroyed in a single background job. If specified, the records to be
+      # destroyed will be split into multiple background jobs.
+      class_attribute :destroy_association_async_batch_size, instance_writer: false, instance_predicate: false, default: nil
 
       ##
       # Contains the database configuration - as is typically stored in config/database.yml -
@@ -33,26 +54,26 @@ module ActiveRecord
       #
       #   development:
       #     adapter: sqlite3
-      #     database: db/development.sqlite3
+      #     database: storage/development.sqlite3
       #
       #   production:
       #     adapter: sqlite3
-      #     database: db/production.sqlite3
+      #     database: storage/production.sqlite3
       #
       # ...would result in ActiveRecord::Base.configurations to look like this:
       #
       #   #<ActiveRecord::DatabaseConfigurations:0x00007fd1acbdf800 @configurations=[
       #     #<ActiveRecord::DatabaseConfigurations::HashConfig:0x00007fd1acbded10 @env_name="development",
-      #       @name="primary", @config={adapter: "sqlite3", database: "db/development.sqlite3"}>,
+      #       @name="primary", @config={adapter: "sqlite3", database: "storage/development.sqlite3"}>,
       #     #<ActiveRecord::DatabaseConfigurations::HashConfig:0x00007fd1acbdea90 @env_name="production",
-      #       @name="primary", @config={adapter: "sqlite3", database: "db/production.sqlite3"}>
+      #       @name="primary", @config={adapter: "sqlite3", database: "storage/production.sqlite3"}>
       #   ]>
       def self.configurations=(config)
         @@configurations = ActiveRecord::DatabaseConfigurations.new(config)
       end
       self.configurations = {}
 
-      # Returns fully resolved ActiveRecord::DatabaseConfigurations object
+      # Returns a fully resolved ActiveRecord::DatabaseConfigurations object.
       def self.configurations
         @@configurations
       end
@@ -71,6 +92,8 @@ module ActiveRecord
 
       class_attribute :has_many_inversing, instance_accessor: false, default: false
 
+      class_attribute :run_commit_callbacks_on_first_saved_instances_in_transaction, instance_accessor: false, default: true
+
       class_attribute :default_connection_handler, instance_writer: false
 
       class_attribute :default_role, instance_writer: false
@@ -79,6 +102,21 @@ module ActiveRecord
 
       class_attribute :shard_selector, instance_accessor: false, default: nil
 
+      ##
+      # :singleton-method:
+      #
+      # Specifies the attributes that will be included in the output of the
+      # #inspect method:
+      #
+      #   Post.attributes_for_inspect = [:id, :title]
+      #   Post.first.inspect #=> "#<Post id: 1, title: "Hello, World!">"
+      #
+      # When set to `:all` inspect will list all the record's attributes:
+      #
+      #   Post.attributes_for_inspect = :all
+      #   Post.first.inspect #=> "#<Post id: 1, title: "Hello, World!", published_at: "2023-10-23 14:28:11 +0000">"
+      class_attribute :attributes_for_inspect, instance_accessor: false, default: :all
+
       def self.application_record_class? # :nodoc:
         if ActiveRecord.application_record_class
           self == ActiveRecord.application_record_class
@@ -99,33 +137,6 @@ module ActiveRecord
         ActiveSupport::IsolatedExecutionState[:active_record_connection_handler] = handler
       end
 
-      def self.connection_handlers
-        if ActiveRecord.legacy_connection_handling
-        else
-          raise NotImplementedError, "The new connection handling does not support accessing multiple connection handlers."
-        end
-
-        @@connection_handlers ||= {}
-      end
-
-      def self.connection_handlers=(handlers)
-        if ActiveRecord.legacy_connection_handling
-          ActiveSupport::Deprecation.warn(<<~MSG)
-            Using legacy connection handling is deprecated. Please set
-            `legacy_connection_handling` to `false` in your application.
-
-            The new connection handling does not support `connection_handlers`
-            getter and setter.
-
-            Read more about how to migrate at: https://guides.rubyonrails.org/active_record_multiple_databases.html#migrate-to-the-new-connection-handling
-          MSG
-        else
-          raise NotImplementedError, "The new connection handling does not support multiple connection handlers."
-        end
-
-        @@connection_handlers = handlers
-      end
-
       def self.asynchronous_queries_session # :nodoc:
         asynchronous_queries_tracker.current_session
       end
@@ -145,16 +156,12 @@ module ActiveRecord
       #     ActiveRecord::Base.current_role #=> :reading
       #   end
       def self.current_role
-        if ActiveRecord.legacy_connection_handling
-          connection_handlers.key(connection_handler) || default_role
-        else
-          connected_to_stack.reverse_each do |hash|
-            return hash[:role] if hash[:role] && hash[:klasses].include?(Base)
-            return hash[:role] if hash[:role] && hash[:klasses].include?(connection_class_for_self)
-          end
-
-          default_role
+        connected_to_stack.reverse_each do |hash|
+          return hash[:role] if hash[:role] && hash[:klasses].include?(Base)
+          return hash[:role] if hash[:role] && hash[:klasses].include?(connection_class_for_self)
         end
+
+        default_role
       end
 
       # Returns the symbol representing the current connected shard.
@@ -186,16 +193,12 @@ module ActiveRecord
       #     ActiveRecord::Base.current_preventing_writes #=> false
       #   end
       def self.current_preventing_writes
-        if ActiveRecord.legacy_connection_handling
-          connection_handler.prevent_writes
-        else
-          connected_to_stack.reverse_each do |hash|
-            return hash[:prevent_writes] if !hash[:prevent_writes].nil? && hash[:klasses].include?(Base)
-            return hash[:prevent_writes] if !hash[:prevent_writes].nil? && hash[:klasses].include?(connection_class_for_self)
-          end
-
-          false
+        connected_to_stack.reverse_each do |hash|
+          return hash[:prevent_writes] if !hash[:prevent_writes].nil? && hash[:klasses].include?(Base)
+          return hash[:prevent_writes] if !hash[:prevent_writes].nil? && hash[:klasses].include?(connection_class_for_self)
         end
+
+        false
       end
 
       def self.connected_to_stack # :nodoc:
@@ -252,19 +255,6 @@ module ActiveRecord
         @find_by_statement_cache = { true => Concurrent::Map.new, false => Concurrent::Map.new }
       end
 
-      def inherited(child_class) # :nodoc:
-        # initialize cache at class definition for thread safety
-        child_class.initialize_find_by_cache
-        unless child_class.base_class?
-          klass = self
-          until klass.base_class?
-            klass.initialize_find_by_cache
-            klass = klass.superclass
-          end
-        end
-        super
-      end
-
       def find(*ids) # :nodoc:
         # We don't have cache keys for this stuff yet
         return super unless ids.length == 1
@@ -274,14 +264,8 @@ module ActiveRecord
 
         return super if StatementCache.unsupported_value?(id)
 
-        key = primary_key
-
-        statement = cached_find_by_statement(key) { |params|
-          where(key => params.bind).limit(1)
-        }
-
-        statement.execute([id], connection).first ||
-          raise(RecordNotFound.new("Couldn't find #{name} with '#{key}'=#{id}", name, key, id))
+        cached_find_by([primary_key], [id]) ||
+          raise(RecordNotFound.new("Couldn't find #{name} with '#{primary_key}'=#{id}", name, primary_key, id))
       end
 
       def find_by(*args) # :nodoc:
@@ -303,58 +287,38 @@ module ActiveRecord
           elsif reflection.belongs_to? && !reflection.polymorphic?
             key = reflection.join_foreign_key
             pkey = reflection.join_primary_key
-            value = value.public_send(pkey) if value.respond_to?(pkey)
+
+            if pkey.is_a?(Array)
+              if pkey.all? { |attribute| value.respond_to?(attribute) }
+                value = pkey.map do |attribute|
+                  if attribute == "id"
+                    value.id_value
+                  else
+                    value.public_send(attribute)
+                  end
+                end
+                composite_primary_key = true
+              end
+            else
+              value = value.public_send(pkey) if value.respond_to?(pkey)
+            end
           end
 
-          if !columns_hash.key?(key) || StatementCache.unsupported_value?(value)
+          if !composite_primary_key &&
+            (!columns_hash.key?(key) || StatementCache.unsupported_value?(value))
             return super
           end
 
           h[key] = value
         end
 
-        keys = hash.keys
-        statement = cached_find_by_statement(keys) { |params|
-          wheres = keys.index_with { params.bind }
-          where(wheres).limit(1)
-        }
-
-        begin
-          statement.execute(hash.values, connection).first
-        rescue TypeError
-          raise ActiveRecord::StatementInvalid
-        end
+        cached_find_by(hash.keys, hash.values)
       end
 
       def find_by!(*args) # :nodoc:
         find_by(*args) || where(*args).raise_record_not_found_exception!
       end
 
-      %w(
-        reading_role writing_role legacy_connection_handling default_timezone index_nested_attribute_errors
-        verbose_query_logs queues warn_on_records_fetched_greater_than maintain_test_schema
-        application_record_class action_on_strict_loading_violation schema_format error_on_ignored_order
-        timestamped_migrations dump_schema_after_migration dump_schemas suppress_multiple_database_warning
-      ).each do |attr|
-        module_eval(<<~RUBY, __FILE__, __LINE__ + 1)
-          def #{attr}
-            ActiveSupport::Deprecation.warn(<<~MSG)
-              ActiveRecord::Base.#{attr} is deprecated and will be removed in Rails 7.1.
-              Use `ActiveRecord.#{attr}` instead.
-            MSG
-            ActiveRecord.#{attr}
-          end
-
-          def #{attr}=(value)
-            ActiveSupport::Deprecation.warn(<<~MSG)
-              ActiveRecord::Base.#{attr}= is deprecated and will be removed in Rails 7.1.
-              Use `ActiveRecord.#{attr}=` instead.
-            MSG
-            ActiveRecord.#{attr} = value
-          end
-        RUBY
-      end
-
       def initialize_generated_modules # :nodoc:
         generated_association_methods
       end
@@ -371,10 +335,10 @@ module ActiveRecord
 
       # Returns columns which shouldn't be exposed while calling +#inspect+.
       def filter_attributes
-        if defined?(@filter_attributes)
-          @filter_attributes
-        else
+        if @filter_attributes.nil?
           superclass.filter_attributes
+        else
+          @filter_attributes
         end
       end
 
@@ -385,24 +349,24 @@ module ActiveRecord
       end
 
       def inspection_filter # :nodoc:
-        if defined?(@filter_attributes)
+        if @filter_attributes.nil?
+          superclass.inspection_filter
+        else
           @inspection_filter ||= begin
             mask = InspectionMask.new(ActiveSupport::ParameterFilter::FILTERED)
             ActiveSupport::ParameterFilter.new(@filter_attributes, mask: mask)
           end
-        else
-          superclass.inspection_filter
         end
       end
 
       # Returns a string like 'Post(id:integer, title:string, body:text)'
       def inspect # :nodoc:
-        if self == Base
+        if self == Base || singleton_class?
           super
         elsif abstract_class?
           "#{super}(abstract)"
-        elsif !connected?
-          "#{super} (call '#{super}.connection' to establish a connection)"
+        elsif !schema_loaded? && !connected?
+          "#{super} (call '#{super}.load_schema' to load schema informations)"
         elsif table_exists?
           attr_list = attribute_types.map { |name, type| "#{name}: #{type.type}" } * ", "
           "#{super}(#{attr_list})"
@@ -411,12 +375,7 @@ module ActiveRecord
         end
       end
 
-      # Override the default class equality method to provide support for decorated models.
-      def ===(object) # :nodoc:
-        object.is_a?(self)
-      end
-
-      # Returns an instance of <tt>Arel::Table</tt> loaded with the current table name.
+      # Returns an instance of +Arel::Table+ loaded with the current table name.
       def arel_table # :nodoc:
         @arel_table ||= Arel::Table.new(table_name, klass: self)
       end
@@ -429,12 +388,34 @@ module ActiveRecord
         TypeCaster::Map.new(self)
       end
 
-      def cached_find_by_statement(key, &block) # :nodoc:
+      def cached_find_by_statement(connection, key, &block) # :nodoc:
         cache = @find_by_statement_cache[connection.prepared_statements]
         cache.compute_if_absent(key) { StatementCache.create(connection, &block) }
       end
 
       private
+        def inherited(subclass)
+          super
+
+          # initialize cache at class definition for thread safety
+          subclass.initialize_find_by_cache
+          unless subclass.base_class?
+            klass = self
+            until klass.base_class?
+              klass.initialize_find_by_cache
+              klass = klass.superclass
+            end
+          end
+
+          subclass.class_eval do
+            @arel_table = nil
+            @predicate_builder = nil
+            @inspection_filter = nil
+            @filter_attributes ||= nil
+            @generated_association_methods ||= nil
+          end
+        end
+
         def relation
           relation = Relation.create(self)
 
@@ -448,6 +429,27 @@ module ActiveRecord
         def table_metadata
           TableMetadata.new(self, arel_table)
         end
+
+        def cached_find_by(keys, values)
+          with_connection do |connection|
+            statement = cached_find_by_statement(connection, keys) { |params|
+              wheres = keys.index_with do |key|
+                if key.is_a?(Array)
+                  [key.map { params.bind }]
+                else
+                  params.bind
+                end
+              end
+              where(wheres).limit(1)
+            }
+
+            begin
+              statement.execute(values.flatten, connection, allow_retry: true).first
+            rescue TypeError
+              raise ActiveRecord::StatementInvalid
+            end
+          end
+        end
     end
 
     # New objects can be instantiated as either empty (pass no construction parameter) or pre-set with
@@ -455,7 +457,7 @@ module ActiveRecord
     # In both instances, valid attribute keys are determined by the column names of the associated table --
     # hence you can't have attributes that aren't part of the table columns.
     #
-    # ==== Example:
+    # ==== Example
     #   # Instantiates a single new object
     #   User.new(first_name: 'Jamie')
     def initialize(attributes = nil)
@@ -465,7 +467,7 @@ module ActiveRecord
       init_internals
       initialize_internals_callback
 
-      assign_attributes(attributes) if attributes
+      super
 
       yield self if block_given?
       _run_initialize_callbacks
@@ -533,12 +535,17 @@ module ActiveRecord
     # only, not its associations. The extent of a "deep" copy is application
     # specific and is therefore left to the application to implement according
     # to its need.
-    # The dup method does not preserve the timestamps (created|updated)_(at|on).
+    # The dup method does not preserve the timestamps (created|updated)_(at|on)
+    # and locking column.
 
     ##
     def initialize_dup(other) # :nodoc:
       @attributes = @attributes.deep_dup
-      @attributes.reset(@primary_key)
+      if self.class.composite_primary_key?
+        @primary_key.each { |key| @attributes.reset(key) }
+      else
+        @attributes.reset(@primary_key)
+      end
 
       _run_initialize_callbacks
 
@@ -568,6 +575,35 @@ module ActiveRecord
       coder["active_record_yaml_version"] = 2
     end
 
+    ##
+    # :method: slice
+    #
+    # :call-seq: slice(*methods)
+    #
+    # Returns a hash of the given methods with their names as keys and returned
+    # values as values.
+    #
+    #   topic = Topic.new(title: "Budget", author_name: "Jason")
+    #   topic.slice(:title, :author_name)
+    #   => { "title" => "Budget", "author_name" => "Jason" }
+    #
+    #--
+    # Implemented by ActiveModel::Access#slice.
+
+    ##
+    # :method: values_at
+    #
+    # :call-seq: values_at(*methods)
+    #
+    # Returns an array of the values returned by the given methods.
+    #
+    #   topic = Topic.new(title: "Budget", author_name: "Jason")
+    #   topic.values_at(:title, :author_name)
+    #   => ["Budget", "Jason"]
+    #
+    #--
+    # Implemented by ActiveModel::Access#values_at.
+
     # Returns true if +comparison_object+ is the same exact object, or +comparison_object+
     # is of the same type and +self+ has an ID and it is equal to +comparison_object.id+.
     #
@@ -580,7 +616,7 @@ module ActiveRecord
     def ==(comparison_object)
       super ||
         comparison_object.instance_of?(self.class) &&
-        !id.nil? &&
+        primary_key_values_present? &&
         comparison_object.id == id
     end
     alias :eql? :==
@@ -590,7 +626,7 @@ module ActiveRecord
     def hash
       id = self.id
 
-      if id
+      if primary_key_values_present?
         self.class.hash ^ id.hash
       else
         super
@@ -642,25 +678,33 @@ module ActiveRecord
     #
     #   user = User.first
     #   user.strict_loading! # => true
-    #   user.comments
+    #   user.address.city
+    #   => ActiveRecord::StrictLoadingViolationError
+    #   user.comments.to_a
     #   => ActiveRecord::StrictLoadingViolationError
     #
-    # === Parameters:
+    # ==== Parameters
     #
-    # * value - Boolean specifying whether to enable or disable strict loading.
-    # * mode - Symbol specifying strict loading mode. Defaults to :all. Using
-    #          :n_plus_one_only mode will only raise an error if an association
-    #          that will lead to an n plus one query is lazily loaded.
+    # * +value+ - Boolean specifying whether to enable or disable strict loading.
+    # * <tt>:mode</tt> - Symbol specifying strict loading mode. Defaults to :all. Using
+    #   :n_plus_one_only mode will only raise an error if an association that
+    #   will lead to an n plus one query is lazily loaded.
     #
-    # === Example:
+    # ==== Examples
     #
     #   user = User.first
     #   user.strict_loading!(false) # => false
-    #   user.comments
-    #   => #<ActiveRecord::Associations::CollectionProxy>
+    #   user.address.city # => "Tatooine"
+    #   user.comments.to_a # => [#<Comment:0x00...]
+    #
+    #   user.strict_loading!(mode: :n_plus_one_only)
+    #   user.address.city # => "Tatooine"
+    #   user.comments.to_a # => [#<Comment:0x00...]
+    #   user.comments.first.ratings.to_a
+    #   => ActiveRecord::StrictLoadingViolationError
     def strict_loading!(value = true, mode: :all)
       unless [:all, :n_plus_one_only].include?(mode)
-        raise ArgumentError, "The :mode option must be one of [:all, :n_plus_one_only]."
+        raise ArgumentError, "The :mode option must be one of [:all, :n_plus_one_only] but #{mode.inspect} was provided."
       end
 
       @strict_loading_mode = mode
@@ -674,7 +718,16 @@ module ActiveRecord
       @strict_loading_mode == :n_plus_one_only
     end
 
+    # Returns +true+ if the record uses strict_loading with +:all+ mode enabled.
+    def strict_loading_all?
+      @strict_loading_mode == :all
+    end
+
     # Marks this record as read only.
+    #
+    #   customer = Customer.first
+    #   customer.readonly!
+    #   customer.save # Raises an ActiveRecord::ReadOnlyRecord
     def readonly!
       @readonly = true
     end
@@ -683,21 +736,28 @@ module ActiveRecord
       self.class.connection_handler
     end
 
-    # Returns the contents of the record as a nicely formatted string.
+    # Returns the attributes of the record as a nicely formatted string.
+    #
+    #   Post.first.inspect
+    #   #=> "#<Post id: 1, title: "Hello, World!", published_at: "2023-10-23 14:28:11 +0000">"
+    #
+    # The attributes can be limited by setting <tt>.attributes_for_inspect</tt>.
+    #
+    #   Post.attributes_for_inspect = [:id, :title]
+    #   Post.first.inspect
+    #   #=> "#<Post id: 1, title: "Hello, World!">"
     def inspect
-      # We check defined?(@attributes) not to issue warnings if the object is
-      # allocated but not initialized.
-      inspection = if defined?(@attributes) && @attributes
-        self.class.attribute_names.filter_map do |name|
-          if _has_attribute?(name)
-            "#{name}: #{attribute_for_inspect(name)}"
-          end
-        end.join(", ")
-      else
-        "not initialized"
-      end
+      inspect_with_attributes(attributes_for_inspect)
+    end
 
-      "#<#{self.class} #{inspection}>"
+    # Returns all attributes of the record as a nicely formatted string,
+    # ignoring <tt>.attributes_for_inspect</tt>.
+    #
+    #   Post.first.full_inspect
+    #   #=> "#<Post id: 1, title: "Hello, World!", published_at: "2023-10-23 14:28:11 +0000">"
+    #
+    def full_inspect
+      inspect_with_attributes(all_attributes_for_inspect)
     end
 
     # Takes a PP and prettily prints this record to it, allowing you to get a nice result from <tt>pp record</tt>
@@ -705,17 +765,17 @@ module ActiveRecord
     def pretty_print(pp)
       return super if custom_inspect_method_defined?
       pp.object_address_group(self) do
-        if defined?(@attributes) && @attributes
-          attr_names = self.class.attribute_names.select { |name| _has_attribute?(name) }
+        if @attributes
+          attr_names = attributes_for_inspect.select { |name| _has_attribute?(name.to_s) }
           pp.seplist(attr_names, proc { pp.text "," }) do |attr_name|
+            attr_name = attr_name.to_s
             pp.breakable " "
             pp.group(1) do
               pp.text attr_name
               pp.text ":"
               pp.breakable
-              value = _read_attribute(attr_name)
-              value = inspection_filter.filter_param(attr_name, value) unless value.nil?
-              pp.pp value
+              value = attribute_for_inspect(attr_name)
+              pp.text value
             end
           end
         else
@@ -725,16 +785,6 @@ module ActiveRecord
       end
     end
 
-    # Returns a hash of the given methods with their names as keys and returned values as values.
-    def slice(*methods)
-      methods.flatten.index_with { |method| public_send(method) }.with_indifferent_access
-    end
-
-    # Returns an array of the values returned by the given methods.
-    def values_at(*methods)
-      methods.flatten.map! { |method| public_send(method) }
-    end
-
     private
       # +Array#flatten+ will call +#to_ary+ (recursively) on each of the elements of
       # the array, and then rescues from the possible +NoMethodError+. If those elements are
@@ -782,5 +832,30 @@ module ActiveRecord
       def inspection_filter
         self.class.inspection_filter
       end
+
+      def inspect_with_attributes(attributes_to_list)
+        inspection = if @attributes
+          attributes_to_list.filter_map do |name|
+            name = name.to_s
+            if _has_attribute?(name)
+              "#{name}: #{attribute_for_inspect(name)}"
+            end
+          end.join(", ")
+        else
+          "not initialized"
+        end
+
+        "#<#{self.class} #{inspection}>"
+      end
+
+      def attributes_for_inspect
+        self.class.attributes_for_inspect == :all ? all_attributes_for_inspect : self.class.attributes_for_inspect
+      end
+
+      def all_attributes_for_inspect
+        return [] unless @attributes
+
+        attribute_names
+      end
   end
 end