activerecord 6.1.7 → 7.1.0

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2004-2022 David Heinemeier Hansson
+Copyright (c) David Heinemeier Hansson
 
 Arel originally copyright (c) 2007-2016 Nick Kallen, Bryan Helmkamp, Emilio Tagua, Aaron Patterson
 

data/README.rdoc

@@ -1,4 +1,4 @@
-= Active Record -- Object-relational mapping in Rails
+= Active Record -- Object-relational mapping in \Rails
 
 Active Record connects classes to relational database tables to establish an
 almost zero-configuration persistence layer for applications. The library
@@ -13,29 +13,28 @@ columns. Although these mappings can be defined explicitly, it's recommended
 to follow naming conventions, especially when getting started with the
 library.
 
-You can read more about Active Record in the {Active Record Basics}[https://edgeguides.rubyonrails.org/active_record_basics.html] guide.
+You can read more about Active Record in the {Active Record Basics}[https://guides.rubyonrails.org/active_record_basics.html] guide.
 
 A short rundown of some of the major features:
 
 * Automated mapping between classes and tables, attributes and columns.
 
-   class Product < ActiveRecord::Base
-   end
-
-  {Learn more}[link:classes/ActiveRecord/Base.html]
+    class Product < ActiveRecord::Base
+    end
 
-The Product class is automatically mapped to the table named "products",
-which might look like this:
+  The Product class is automatically mapped to the table named "products",
+  which might look like this:
 
-   CREATE TABLE products (
-     id bigint NOT NULL auto_increment,
-     name varchar(255),
-     PRIMARY KEY  (id)
-   );
+    CREATE TABLE products (
+      id bigint NOT NULL auto_increment,
+      name varchar(255),
+      PRIMARY KEY  (id)
+    );
 
-This would also define the following accessors: <tt>Product#name</tt> and
-<tt>Product#name=(new_name)</tt>.
+  This would also define the following accessors: <tt>Product#name</tt> and
+  <tt>Product#name=(new_name)</tt>.
 
+  {Learn more}[link:classes/ActiveRecord/Base.html]
 
 * Associations between objects defined by simple class methods.
 
@@ -140,7 +139,7 @@ This would also define the following accessors: <tt>Product#name</tt> and
 
 * Database agnostic schema management with Migrations.
 
-    class AddSystemSettings < ActiveRecord::Migration[6.0]
+    class AddSystemSettings < ActiveRecord::Migration[7.1]
       def up
         create_table :system_settings do |t|
           t.string  :name
@@ -192,7 +191,7 @@ The latest version of Active Record can be installed with RubyGems:
 
   $ gem install activerecord
 
-Source code can be downloaded as part of the Rails project on GitHub:
+Source code can be downloaded as part of the \Rails project on GitHub:
 
 * https://github.com/rails/rails/tree/main/activerecord
 
@@ -210,7 +209,7 @@ API documentation is at:
 
 * https://api.rubyonrails.org
 
-Bug reports for the Ruby on Rails project can be filed here:
+Bug reports for the Ruby on \Rails project can be filed here:
 
 * https://github.com/rails/rails/issues
 

data/lib/active_record/aggregations.rb

@@ -4,7 +4,7 @@ module ActiveRecord
   # See ActiveRecord::Aggregations::ClassMethods for documentation
   module Aggregations
     def initialize_dup(*) # :nodoc:
-      @aggregation_cache = {}
+      @aggregation_cache = @aggregation_cache.dup
       super
     end
 
@@ -19,10 +19,12 @@ module ActiveRecord
       end
 
       def init_internals
-        @aggregation_cache = {}
         super
+        @aggregation_cache = {}
       end
 
+      # = Active Record \Aggregations
+      #
       # Active Record implements aggregation through a macro-like class method called #composed_of
       # for representing attributes as value objects. It expresses relationships like "Account [is]
       # composed of Money [among other things]" or "Person [is] composed of [an] address". Each call
@@ -32,8 +34,8 @@ module ActiveRecord
       # the database).
       #
       #   class Customer < ActiveRecord::Base
-      #     composed_of :balance, class_name: "Money", mapping: %w(balance amount)
-      #     composed_of :address, mapping: [ %w(address_street street), %w(address_city city) ]
+      #     composed_of :balance, class_name: "Money", mapping: { balance: :amount }
+      #     composed_of :address, mapping: { address_street: :street, address_city: :city }
       #   end
       #
       # The customer class now has the following methods to manipulate the value objects:
@@ -150,7 +152,7 @@ module ActiveRecord
       #   class NetworkResource < ActiveRecord::Base
       #     composed_of :cidr,
       #                 class_name: 'NetAddr::CIDR',
-      #                 mapping: [ %w(network_address network), %w(cidr_range bits) ],
+      #                 mapping: { network_address: :network, cidr_range: :bits },
       #                 allow_nil: true,
       #                 constructor: Proc.new { |network_address, cidr_range| NetAddr::CIDR.create("#{network_address}/#{cidr_range}") },
       #                 converter: Proc.new { |value| NetAddr::CIDR.create(value.is_a?(Array) ? value.join('/') : value) }
@@ -188,10 +190,10 @@ module ActiveRecord
         #   to the Address class, but if the real class name is +CompanyAddress+, you'll have to specify it
         #   with this option.
         # * <tt>:mapping</tt> - Specifies the mapping of entity attributes to attributes of the value
-        #   object. Each mapping is represented as an array where the first item is the name of the
-        #   entity attribute and the second item is the name of the attribute in the value object. The
+        #   object. Each mapping is represented as a key-value pair where the key is the name of the
+        #   entity attribute and the value is the name of the attribute in the value object. The
         #   order in which mappings are defined determines the order in which attributes are sent to the
-        #   value class constructor.
+        #   value class constructor. The mapping can be written as a hash or as an array of pairs.
         # * <tt>:allow_nil</tt> - Specifies that the value object will not be instantiated when all mapped
         #   attributes are +nil+. Setting the value object to +nil+ has the effect of writing +nil+ to all
         #   mapped attributes.
@@ -208,14 +210,15 @@ module ActiveRecord
         #   can return +nil+ to skip the assignment.
         #
         # Option examples:
-        #   composed_of :temperature, mapping: %w(reading celsius)
-        #   composed_of :balance, class_name: "Money", mapping: %w(balance amount)
+        #   composed_of :temperature, mapping: { reading: :celsius }
+        #   composed_of :balance, class_name: "Money", mapping: { balance: :amount }
+        #   composed_of :address, mapping: { address_street: :street, address_city: :city }
         #   composed_of :address, mapping: [ %w(address_street street), %w(address_city city) ]
         #   composed_of :gps_location
         #   composed_of :gps_location, allow_nil: true
         #   composed_of :ip_address,
         #               class_name: 'IPAddr',
-        #               mapping: %w(ip to_i),
+        #               mapping: { ip: :to_i },
         #               constructor: Proc.new { |ip| IPAddr.new(ip, Socket::AF_INET) },
         #               converter: Proc.new { |ip| ip.is_a?(Integer) ? IPAddr.new(ip, Socket::AF_INET) : IPAddr.new(ip.to_s) }
         #
@@ -249,7 +252,7 @@ module ActiveRecord
                 object = constructor.respond_to?(:call) ?
                   constructor.call(*attrs) :
                   class_name.constantize.send(constructor, *attrs)
-                @aggregation_cache[name] = object
+                @aggregation_cache[name] = object.freeze
               end
               @aggregation_cache[name]
             end
@@ -264,7 +267,7 @@ module ActiveRecord
               end
 
               hash_from_multiparameter_assignment = part.is_a?(Hash) &&
-                part.each_key.all? { |k| k.is_a?(Integer) }
+                part.keys.all?(Integer)
               if hash_from_multiparameter_assignment
                 raise ArgumentError unless part.size == part.each_key.max
                 part = klass.new(*part.sort.map(&:last))
@@ -275,7 +278,7 @@ module ActiveRecord
                 @aggregation_cache[name] = nil
               else
                 mapping.each { |key, value| write_attribute(key, part.send(value)) }
-                @aggregation_cache[name] = part.freeze
+                @aggregation_cache[name] = part.dup.freeze
               end
             end
           end

data/lib/active_record/association_relation.rb

@@ -16,7 +16,7 @@ module ActiveRecord
     end
 
     %w(insert insert_all insert! insert_all! upsert upsert_all).each do |method|
-      class_eval <<~RUBY
+      class_eval <<~RUBY, __FILE__, __LINE__ + 1
         def #{method}(attributes, **kwargs)
           if @association.reflection.through_reflection?
             raise ArgumentError, "Bulk insert or upsert is currently not supported for has_many through association"
@@ -27,16 +27,6 @@ module ActiveRecord
       RUBY
     end
 
-    def build(attributes = nil, &block)
-      if attributes.is_a?(Array)
-        attributes.collect { |attr| build(attr, &block) }
-      else
-        block = current_scope_restoring_block(&block)
-        scoping { _new(attributes, &block) }
-      end
-    end
-    alias new build
-
     private
       def _new(attributes, &block)
         @association.build(attributes, &block)

data/lib/active_record/associations/association.rb

@@ -19,7 +19,7 @@ module ActiveRecord
     # Associations in Active Record are middlemen between the object that
     # holds the association, known as the <tt>owner</tt>, and the associated
     # result set, known as the <tt>target</tt>. Association metadata is available in
-    # <tt>reflection</tt>, which is an instance of <tt>ActiveRecord::Reflection::AssociationReflection</tt>.
+    # <tt>reflection</tt>, which is an instance of +ActiveRecord::Reflection::AssociationReflection+.
     #
     # For example, given
     #
@@ -32,8 +32,8 @@ module ActiveRecord
     # The association of <tt>blog.posts</tt> has the object +blog+ as its
     # <tt>owner</tt>, the collection of its posts as <tt>target</tt>, and
     # the <tt>reflection</tt> object represents a <tt>:has_many</tt> macro.
-    class Association #:nodoc:
-      attr_reader :owner, :target, :reflection
+    class Association # :nodoc:
+      attr_reader :owner, :target, :reflection, :disable_joins
 
       delegate :options, to: :reflection
 
@@ -41,9 +41,12 @@ module ActiveRecord
         reflection.check_validity!
 
         @owner, @reflection = owner, reflection
+        @disable_joins = @reflection.options[:disable_joins] || false
 
         reset
         reset_scope
+
+        @skip_strict_loading = nil
       end
 
       # Resets the \loaded flag to +false+ and sets the \target to +nil+.
@@ -51,7 +54,6 @@ module ActiveRecord
         @loaded = false
         @target = nil
         @stale_state = nil
-        @inversed = false
       end
 
       def reset_negative_cache # :nodoc:
@@ -77,7 +79,6 @@ module ActiveRecord
       def loaded!
         @loaded = true
         @stale_state = stale_state
-        @inversed = false
       end
 
       # The target is stale if the target no longer points to the record(s) that the
@@ -87,7 +88,7 @@ module ActiveRecord
       #
       # Note that if the target has not been loaded, it is not considered stale.
       def stale_target?
-        !@inversed && loaded? && @stale_state != stale_state
+        loaded? && @stale_state != stale_state
       end
 
       # Sets the target of this association to <tt>\target</tt>, and the \loaded flag to +true+.
@@ -97,8 +98,12 @@ module ActiveRecord
       end
 
       def scope
-        if (scope = klass.current_scope) && scope.try(:proxy_association) == self
+        if disable_joins
+          DisableJoinsAssociationScope.create.scope(self)
+        elsif (scope = klass.current_scope) && scope.try(:proxy_association) == self
           scope.spawn
+        elsif scope = klass.global_current_scope
+          target_scope.merge!(association_scope).merge!(scope)
         else
           target_scope.merge!(association_scope)
         end
@@ -132,15 +137,11 @@ module ActiveRecord
 
       def inversed_from(record)
         self.target = record
-        @inversed = !!record
       end
 
       def inversed_from_queries(record)
         if inversable?(record)
           self.target = record
-          @inversed = true
-        else
-          @inversed = false
         end
       end
 
@@ -191,7 +192,7 @@ module ActiveRecord
         @reflection = @owner.class._reflect_on_association(reflection_name)
       end
 
-      def initialize_attributes(record, except_from_scope_attributes = nil) #:nodoc:
+      def initialize_attributes(record, except_from_scope_attributes = nil) # :nodoc:
         except_from_scope_attributes ||= {}
         skip_assign = [reflection.foreign_key, reflection.type].compact
         assigned_keys = record.changed_attribute_names_to_save
@@ -210,8 +211,14 @@ module ActiveRecord
       end
 
       private
+        # Reader and writer methods call this so that consistent errors are presented
+        # when the association target class does not exist.
+        def ensure_klass_exists!
+          klass
+        end
+
         def find_target
-          if strict_loading? && owner.validation_context.nil?
+          if violates_strict_loading?
             Base.strict_loading_violation!(owner: owner.class, reflection: reflection)
           end
 
@@ -224,13 +231,32 @@ module ActiveRecord
           end
 
           binds = AssociationScope.get_bind_values(owner, reflection.chain)
-          sc.execute(binds, klass.connection) { |record| set_inverse_instance(record) }
+          sc.execute(binds, klass.connection) do |record|
+            set_inverse_instance(record)
+            if owner.strict_loading_n_plus_one_only? && reflection.macro == :has_many
+              record.strict_loading!
+            else
+              record.strict_loading!(false, mode: owner.strict_loading_mode)
+            end
+          end
         end
 
-        def strict_loading?
+        def skip_strict_loading(&block)
+          skip_strict_loading_was = @skip_strict_loading
+          @skip_strict_loading = true
+          yield
+        ensure
+          @skip_strict_loading = skip_strict_loading_was
+        end
+
+        def violates_strict_loading?
+          return if @skip_strict_loading
+
+          return unless owner.validation_context.nil?
+
           return reflection.strict_loading? if reflection.options.key?(:strict_loading)
 
-          owner.strict_loading?
+          owner.strict_loading? && !owner.strict_loading_n_plus_one_only?
         end
 
         # The scope for this association.
@@ -241,7 +267,11 @@ module ActiveRecord
         # actually gets built.
         def association_scope
           if klass
-            @association_scope ||= AssociationScope.scope(self)
+            @association_scope ||= if disable_joins
+              DisableJoinsAssociationScope.scope(self)
+            else
+              AssociationScope.scope(self)
+            end
           end
         end
 
@@ -273,7 +303,7 @@ module ActiveRecord
 
         # Raises ActiveRecord::AssociationTypeMismatch unless +record+ is of
         # the kind of the class of the associated objects. Meant to be used as
-        # a sanity check when you are about to assign an associated record.
+        # a safety check when you are about to assign an associated record.
         def raise_on_type_mismatch!(record)
           unless record.is_a?(reflection.klass)
             fresh_class = reflection.class_name.safe_constantize
@@ -306,7 +336,8 @@ module ActiveRecord
 
         # Returns true if record contains the foreign_key
         def foreign_key_for?(record)
-          record._has_attribute?(reflection.foreign_key)
+          foreign_key = Array(reflection.foreign_key)
+          foreign_key.all? { |key| record._has_attribute?(key) }
         end
 
         # This should be implemented to return the values of the relevant key(s) on the owner,

data/lib/active_record/associations/association_scope.rb

@@ -2,7 +2,7 @@
 
 module ActiveRecord
   module Associations
-    class AssociationScope #:nodoc:
+    class AssociationScope # :nodoc:
       def self.scope(association)
         INSTANCE.scope(association)
       end
@@ -35,7 +35,7 @@ module ActiveRecord
         binds = []
         last_reflection = chain.last
 
-        binds << last_reflection.join_id_for(owner)
+        binds.push(*last_reflection.join_id_for(owner))
         if last_reflection.type
           binds << owner.class.polymorphic_name
         end
@@ -56,12 +56,15 @@ module ActiveRecord
         end
 
         def last_chain_scope(scope, reflection, owner)
-          primary_key = reflection.join_primary_key
-          foreign_key = reflection.join_foreign_key
+          primary_key = Array(reflection.join_primary_key)
+          foreign_key = Array(reflection.join_foreign_key)
 
           table = reflection.aliased_table
-          value = transform_value(owner[foreign_key])
-          scope = apply_scope(scope, table, primary_key, value)
+          primary_key_foreign_key_pairs = primary_key.zip(foreign_key)
+          primary_key_foreign_key_pairs.each do |join_key, foreign_key|
+            value = transform_value(owner._read_attribute(foreign_key))
+            scope = apply_scope(scope, table, join_key, value)
+          end
 
           if reflection.type
             polymorphic_type = transform_value(owner.class.polymorphic_name)
@@ -76,19 +79,23 @@ module ActiveRecord
         end
 
         def next_chain_scope(scope, reflection, next_reflection)
-          primary_key = reflection.join_primary_key
-          foreign_key = reflection.join_foreign_key
+          primary_key = Array(reflection.join_primary_key)
+          foreign_key = Array(reflection.join_foreign_key)
 
           table = reflection.aliased_table
           foreign_table = next_reflection.aliased_table
-          constraint = table[primary_key].eq(foreign_table[foreign_key])
+
+          primary_key_foreign_key_pairs = primary_key.zip(foreign_key)
+          constraints = primary_key_foreign_key_pairs.map do |join_primary_key, foreign_key|
+            table[join_primary_key].eq(foreign_table[foreign_key])
+          end.inject(&:and)
 
           if reflection.type
             value = transform_value(next_reflection.klass.polymorphic_name)
             scope = apply_scope(scope, table, reflection.type, value)
           end
 
-          scope.joins!(join(foreign_table, constraint))
+          scope.joins!(join(foreign_table, constraints))
         end
 
         class ReflectionProxy < SimpleDelegator # :nodoc:
@@ -123,8 +130,6 @@ module ActiveRecord
 
           chain_head = chain.first
           chain.reverse_each do |reflection|
-            # Exclude the scope of the association itself, because that
-            # was already merged in the #scope method.
             reflection.constraints.each do |scope_chain_item|
               item = eval_scope(reflection, scope_chain_item, owner)
 

data/lib/active_record/associations/belongs_to_association.rb

@@ -3,7 +3,7 @@
 module ActiveRecord
   module Associations
     # = Active Record Belongs To Association
-    class BelongsToAssociation < SingularAssociation #:nodoc:
+    class BelongsToAssociation < SingularAssociation # :nodoc:
       def handle_dependency
         return unless load_target
 
@@ -11,8 +11,13 @@ module ActiveRecord
         when :destroy
           raise ActiveRecord::Rollback unless target.destroy
         when :destroy_async
-          id = owner.public_send(reflection.foreign_key.to_sym)
-          primary_key_column = reflection.active_record_primary_key.to_sym
+          if reflection.foreign_key.is_a?(Array)
+            primary_key_column = reflection.active_record_primary_key.map(&:to_sym)
+            id = reflection.foreign_key.map { |col| owner.public_send(col.to_sym) }
+          else
+            primary_key_column = reflection.active_record_primary_key.to_sym
+            id = owner.public_send(reflection.foreign_key.to_sym)
+          end
 
           enqueue_destroy_association(
             owner_model_name: owner.class.to_s,
@@ -55,7 +60,8 @@ module ActiveRecord
 
       def decrement_counters_before_last_save
         if reflection.polymorphic?
-          model_was = owner.attribute_before_last_save(reflection.foreign_type)&.constantize
+          model_type_was = owner.attribute_before_last_save(reflection.foreign_type)
+          model_was = owner.class.polymorphic_class_for(model_type_was) if model_type_was
         else
           model_was = klass
         end
@@ -68,6 +74,14 @@ module ActiveRecord
       end
 
       def target_changed?
+        owner.attribute_changed?(reflection.foreign_key) || (!foreign_key_present? && target&.new_record?)
+      end
+
+      def target_previously_changed?
+        owner.attribute_previously_changed?(reflection.foreign_key)
+      end
+
+      def saved_change_to_target?
         owner.saved_change_to_attribute?(reflection.foreign_key)
       end
 
@@ -77,6 +91,8 @@ module ActiveRecord
             raise_on_type_mismatch!(record)
             set_inverse_instance(record)
             @updated = true
+          elsif target
+            remove_inverse_instance(target)
           end
 
           replace_keys(record, force: true)
@@ -108,10 +124,13 @@ module ActiveRecord
         end
 
         def replace_keys(record, force: false)
-          target_key = record ? record._read_attribute(primary_key(record.class)) : nil
+          target_key_values = record ? Array(primary_key(record.class)).map { |key| record._read_attribute(key) } : []
+          reflection_fk = Array(reflection.foreign_key)
 
-          if force || owner[reflection.foreign_key] != target_key
-            owner[reflection.foreign_key] = target_key
+          if force || reflection_fk.map { |fk| owner._read_attribute(fk) } != target_key_values
+            reflection_fk.zip(target_key_values).each do |key, value|
+              owner[key] = value
+            end
           end
         end
 
@@ -120,12 +139,12 @@ module ActiveRecord
         end
 
         def foreign_key_present?
-          owner._read_attribute(reflection.foreign_key)
+          Array(reflection.foreign_key).all? { |fk| owner._read_attribute(fk) }
         end
 
         def invertible_for?(record)
           inverse = inverse_reflection_for(record)
-          inverse && (inverse.has_one? || ActiveRecord::Base.has_many_inversing)
+          inverse && (inverse.has_one? || inverse.klass.has_many_inversing)
         end
 
         def stale_state

data/lib/active_record/associations/belongs_to_polymorphic_association.rb

@@ -3,13 +3,21 @@
 module ActiveRecord
   module Associations
     # = Active Record Belongs To Polymorphic Association
-    class BelongsToPolymorphicAssociation < BelongsToAssociation #:nodoc:
+    class BelongsToPolymorphicAssociation < BelongsToAssociation # :nodoc:
       def klass
         type = owner[reflection.foreign_type]
         type.presence && owner.class.polymorphic_class_for(type)
       end
 
       def target_changed?
+        super || owner.attribute_changed?(reflection.foreign_type)
+      end
+
+      def target_previously_changed?
+        super || owner.attribute_previously_changed?(reflection.foreign_type)
+      end
+
+      def saved_change_to_target?
         super || owner.saved_change_to_attribute?(reflection.foreign_type)
       end
 
@@ -19,7 +27,7 @@ module ActiveRecord
 
           target_type = record ? record.class.polymorphic_name : nil
 
-          if force || owner[reflection.foreign_type] != target_type
+          if force || owner._read_attribute(reflection.foreign_type) != target_type
             owner[reflection.foreign_type] = target_type
           end
         end

data/lib/active_record/associations/builder/association.rb

@@ -12,14 +12,14 @@
 #      - HasManyAssociation
 
 module ActiveRecord::Associations::Builder # :nodoc:
-  class Association #:nodoc:
+  class Association # :nodoc:
     class << self
       attr_accessor :extensions
     end
     self.extensions = []
 
     VALID_OPTIONS = [
-      :class_name, :anonymous_class, :primary_key, :foreign_key, :dependent, :validate, :inverse_of, :strict_loading
+      :class_name, :anonymous_class, :primary_key, :foreign_key, :dependent, :validate, :inverse_of, :strict_loading, :query_constraints
     ].freeze # :nodoc:
 
     def self.build(model, name, scope, options, &block)
@@ -33,6 +33,7 @@ module ActiveRecord::Associations::Builder # :nodoc:
       define_accessors model, reflection
       define_callbacks model, reflection
       define_validations model, reflection
+      define_change_tracking_methods model, reflection
       reflection
     end
 
@@ -117,14 +118,18 @@ module ActiveRecord::Associations::Builder # :nodoc:
       # noop
     end
 
+    def self.define_change_tracking_methods(model, reflection)
+      # noop
+    end
+
     def self.valid_dependent_options
       raise NotImplementedError
     end
 
     def self.check_dependent_options(dependent, model)
       if dependent == :destroy_async && !model.destroy_association_async_job
-        err_message = "ActiveJob is required to use destroy_async on associations"
-        raise ActiveRecord::ActiveJobRequiredError, err_message
+        err_message = "A valid destroy_association_async_job is required to use `dependent: :destroy_async` on associations"
+        raise ActiveRecord::ConfigurationError, err_message
       end
       unless valid_dependent_options.include? dependent
         raise ArgumentError, "The :dependent option must be one of #{valid_dependent_options}, but is :#{dependent}"
@@ -158,6 +163,7 @@ module ActiveRecord::Associations::Builder # :nodoc:
 
     private_class_method :build_scope, :macro, :valid_options, :validate_options, :define_extensions,
       :define_callbacks, :define_accessors, :define_readers, :define_writers, :define_validations,
-      :valid_dependent_options, :check_dependent_options, :add_destroy_callbacks, :add_after_commit_jobs_callback
+      :define_change_tracking_methods, :valid_dependent_options, :check_dependent_options,
+      :add_destroy_callbacks, :add_after_commit_jobs_callback
   end
 end