activerecord 7.2.4 → 8.1.4

data/README.rdoc

@@ -139,7 +139,7 @@ A short rundown of some of the major features:
 
 * Database agnostic schema management with Migrations.
 
-    class AddSystemSettings < ActiveRecord::Migration[7.2]
+    class AddSystemSettings < ActiveRecord::Migration[8.1]
       def up
         create_table :system_settings do |t|
           t.string  :name

data/lib/active_record/association_relation.rb

@@ -17,7 +17,7 @@ module ActiveRecord
 
     %w(insert insert_all insert! insert_all! upsert upsert_all).each do |method|
       class_eval <<~RUBY, __FILE__, __LINE__ + 1
-        def #{method}(attributes, **kwargs)
+        def #{method}(...)
           if @association.reflection.through_reflection?
             raise ArgumentError, "Bulk insert or upsert is currently not supported for has_many through association"
           end
@@ -43,6 +43,7 @@ module ActiveRecord
       def exec_queries
         super do |record|
           @association.set_inverse_instance_from_queries(record)
+          @association.set_strict_loading(record)
           yield record if block_given?
         end
       end

data/lib/active_record/associations/association.rb

@@ -34,7 +34,7 @@ module ActiveRecord
     # the <tt>reflection</tt> object represents a <tt>:has_many</tt> macro.
     class Association # :nodoc:
       attr_accessor :owner
-      attr_reader :target, :reflection, :disable_joins
+      attr_reader :reflection, :disable_joins
 
       delegate :options, to: :reflection
 
@@ -50,6 +50,13 @@ module ActiveRecord
         @skip_strict_loading = nil
       end
 
+      def target
+        if @target.is_a?(Promise)
+          @target = @target.value
+        end
+        @target
+      end
+
       # Resets the \loaded flag to +false+ and sets the \target to +nil+.
       def reset
         @loaded = false
@@ -113,6 +120,14 @@ module ActiveRecord
         @association_scope = nil
       end
 
+      def set_strict_loading(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
+
       # Set the inverse association, if possible
       def set_inverse_instance(record)
         if inverse = inverse_association_for(record)
@@ -172,7 +187,7 @@ module ActiveRecord
       # ActiveRecord::RecordNotFound is rescued within the method, and it is
       # not reraised. The proxy is \reset and +nil+ is the return value.
       def load_target
-        @target = find_target if (@stale_state && stale_target?) || find_target?
+        @target = find_target(async: false) if (@stale_state && stale_target?) || find_target?
 
         loaded! unless loaded?
         target
@@ -180,6 +195,13 @@ module ActiveRecord
         reset
       end
 
+      def async_load_target # :nodoc:
+        @target = find_target(async: true) if (@stale_state && stale_target?) || find_target?
+
+        loaded! unless loaded?
+        nil
+      end
+
       # We can't dump @reflection and @through_reflection since it contains the scope proc
       def marshal_dump
         ivars = (instance_variables - [:@reflection, :@through_reflection]).map { |name| [name, instance_variable_get(name)] }
@@ -210,7 +232,19 @@ module ActiveRecord
         _create_record(attributes, true, &block)
       end
 
-      # Whether the association represent a single record
+      def violates_strict_loading?
+        return unless find_target?
+
+        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_n_plus_one_only?
+      end
+
+      # Whether the association represents a single record
       # or a collection of records.
       def collection?
         false
@@ -223,13 +257,19 @@ module ActiveRecord
           klass
         end
 
-        def find_target
+        def find_target(async: false)
           if violates_strict_loading?
             Base.strict_loading_violation!(owner: owner.class, reflection: reflection)
           end
 
           scope = self.scope
-          return scope.to_a if skip_statement_cache?(scope)
+          if skip_statement_cache?(scope)
+            if async
+              return scope.load_async.then(&:to_a)
+            else
+              return scope.to_a
+            end
+          end
 
           sc = reflection.association_scope_cache(klass, owner) do |params|
             as = AssociationScope.create { params.bind }
@@ -238,13 +278,9 @@ module ActiveRecord
 
           binds = AssociationScope.get_bind_values(owner, reflection.chain)
           klass.with_connection do |c|
-            sc.execute(binds, c) do |record|
+            sc.execute(binds, c, async: async) 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
+              set_strict_loading(record)
             end
           end
         end
@@ -257,16 +293,6 @@ module ActiveRecord
           @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_n_plus_one_only?
-        end
-
         # The scope for this association.
         #
         # Note that the association_scope is merged into the target_scope only when the
@@ -385,12 +411,28 @@ module ActiveRecord
         end
 
         def matches_foreign_key?(record)
-          if foreign_key_for?(record)
-            record.read_attribute(reflection.foreign_key) == owner.id ||
-              (foreign_key_for?(owner) && owner.read_attribute(reflection.foreign_key) == record.id)
-          else
-            owner.read_attribute(reflection.foreign_key) == record.id
-          end
+          (foreign_key_for?(record) && record_foreign_key_matches_owner?(record)) ||
+            (foreign_key_for?(owner) && owner_foreign_key_matches_record?(record))
+        end
+
+        def record_foreign_key_matches_owner?(record)
+          foreign_key_values(record) == active_record_primary_key_values(owner)
+        end
+
+        def owner_foreign_key_matches_record?(record)
+          foreign_key_values(owner) == association_primary_key_values(record)
+        end
+
+        def foreign_key_values(record)
+          Array(reflection.foreign_key).map { |key| record.read_attribute(key) }
+        end
+
+        def active_record_primary_key_values(record)
+          Array(reflection.active_record_primary_key).map { |key| record.read_attribute(key) }
+        end
+
+        def association_primary_key_values(record)
+          Array(reflection.association_primary_key(record.class)).map { |key| record.read_attribute(key) }
         end
     end
   end

data/lib/active_record/associations/association_scope.rb

@@ -149,7 +149,7 @@ module ActiveRecord
                 scope.includes_values |= item.includes_values
               end
 
-              scope.unscope!(*item.unscope_values)
+              scope.unscope!(*item.table_name_qualified_unscope_values)
               scope.where_clause += item.where_clause
               scope.order_values = item.order_values | scope.order_values
             end

data/lib/active_record/associations/belongs_to_association.rb

@@ -80,11 +80,11 @@ module ActiveRecord
       end
 
       def target_changed?
-        owner.attribute_changed?(reflection.foreign_key) || (!foreign_key_present? && target&.new_record?)
+        Array(reflection.foreign_key).any? { |fk| owner.attribute_changed?(fk) } || (!foreign_key_present? && target&.new_record?)
       end
 
       def target_previously_changed?
-        owner.attribute_previously_changed?(reflection.foreign_key)
+        Array(reflection.foreign_key).any? { |fk| owner.attribute_previously_changed?(fk) }
       end
 
       def saved_change_to_target?

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

@@ -19,7 +19,7 @@ module ActiveRecord::Associations::Builder # :nodoc:
     self.extensions = []
 
     VALID_OPTIONS = [
-      :class_name, :anonymous_class, :primary_key, :foreign_key, :dependent, :validate, :inverse_of, :strict_loading, :query_constraints
+      :anonymous_class, :primary_key, :foreign_key, :dependent, :validate, :inverse_of, :strict_loading, :query_constraints, :deprecated
     ].freeze # :nodoc:
 
     def self.build(model, name, scope, options, &block)
@@ -30,10 +30,10 @@ module ActiveRecord::Associations::Builder # :nodoc:
       end
 
       reflection = create_reflection(model, name, scope, options, &block)
-      define_accessors model, reflection
-      define_callbacks model, reflection
-      define_validations model, reflection
-      define_change_tracking_methods model, reflection
+      define_accessors(model, reflection)
+      define_callbacks(model, reflection)
+      define_validations(model, reflection)
+      define_change_tracking_methods(model, reflection)
       reflection
     end
 
@@ -71,6 +71,7 @@ module ActiveRecord::Associations::Builder # :nodoc:
     end
 
     def self.define_extensions(model, name)
+      # noop
     end
 
     def self.define_callbacks(model, reflection)
@@ -81,7 +82,7 @@ module ActiveRecord::Associations::Builder # :nodoc:
       end
 
       Association.extensions.each do |extension|
-        extension.build model, reflection
+        extension.build(model, reflection)
       end
     end
 
@@ -101,7 +102,9 @@ module ActiveRecord::Associations::Builder # :nodoc:
     def self.define_readers(mixin, name)
       mixin.class_eval <<-CODE, __FILE__, __LINE__ + 1
         def #{name}
-          association(:#{name}).reader
+          association = association(:#{name})
+          deprecated_associations_api_guard(association, __method__)
+          association.reader
         end
       CODE
     end
@@ -109,7 +112,9 @@ module ActiveRecord::Associations::Builder # :nodoc:
     def self.define_writers(mixin, name)
       mixin.class_eval <<-CODE, __FILE__, __LINE__ + 1
         def #{name}=(value)
-          association(:#{name}).writer(value)
+          association = association(:#{name})
+          deprecated_associations_api_guard(association, __method__)
+          association.writer(value)
         end
       CODE
     end
@@ -131,14 +136,21 @@ module ActiveRecord::Associations::Builder # :nodoc:
         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
+      unless valid_dependent_options.include?(dependent)
         raise ArgumentError, "The :dependent option must be one of #{valid_dependent_options}, but is :#{dependent}"
       end
     end
 
     def self.add_destroy_callbacks(model, reflection)
-      name = reflection.name
-      model.before_destroy(->(o) { o.association(name).handle_dependency })
+      if reflection.deprecated?
+        # If :dependent is set, destroying the record has a side effect that
+        # would no longer happen if the association is removed.
+        model.before_destroy do
+          report_deprecated_association(reflection, context: ":dependent has a side effect here")
+        end
+      end
+
+      model.before_destroy(->(o) { o.association(reflection.name).handle_dependency })
     end
 
     def self.add_after_commit_jobs_callback(model, dependent)

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

@@ -8,8 +8,9 @@ module ActiveRecord::Associations::Builder # :nodoc:
 
     def self.valid_options(options)
       valid = super + [:polymorphic, :counter_cache, :optional, :default]
-      valid += [:foreign_type] if options[:polymorphic]
-      valid += [:ensuring_owner_was] if options[:dependent] == :destroy_async
+      valid << :class_name unless options[:polymorphic]
+      valid << :foreign_type if options[:polymorphic]
+      valid << :ensuring_owner_was if options[:dependent] == :destroy_async
       valid
     end
 
@@ -42,7 +43,16 @@ module ActiveRecord::Associations::Builder # :nodoc:
     end
 
     def self.touch_record(o, changes, foreign_key, name, touch) # :nodoc:
-      old_foreign_id = changes[foreign_key] && changes[foreign_key].first
+      old_foreign_id =
+        if foreign_key.is_a?(Array)
+          if foreign_key.any? { |fk| changes[fk] }
+            foreign_key.map do |fk|
+              changes[fk] ? changes[fk].first : o.read_attribute(fk)
+            end
+          end
+        elsif changes[foreign_key]
+          changes[foreign_key].first
+        end
 
       if old_foreign_id
         association = o.association(name)
@@ -55,7 +65,7 @@ module ActiveRecord::Associations::Builder # :nodoc:
           klass = association.klass
         end
         primary_key = reflection.association_primary_key(klass)
-        old_record = klass.find_by(primary_key => old_foreign_id)
+        old_record = klass.find_by(primary_key => [old_foreign_id])
 
         if old_record
           if touch != true
@@ -107,6 +117,14 @@ module ActiveRecord::Associations::Builder # :nodoc:
     end
 
     def self.add_destroy_callbacks(model, reflection)
+      if reflection.deprecated?
+        # If :dependent is set, destroying the record has some side effect that
+        # would no longer happen if the association is removed.
+        model.before_destroy do
+          report_deprecated_association(reflection, context: ":dependent has a side effect here")
+        end
+      end
+
       model.after_destroy lambda { |o| o.association(reflection.name).handle_dependency }
     end
 
@@ -131,8 +149,14 @@ module ActiveRecord::Associations::Builder # :nodoc:
             foreign_key = reflection.foreign_key
             foreign_type = reflection.foreign_type
 
-            record.read_attribute(foreign_key).nil? ||
-              record.attribute_changed?(foreign_key) ||
+            fk_missing_or_changed = if foreign_key.is_a?(Array)
+              foreign_key.any? { |fk| record.read_attribute(fk).nil? || record.attribute_changed?(fk) }
+            else
+              record.read_attribute(foreign_key).nil? ||
+                record.attribute_changed?(foreign_key)
+            end
+
+            fk_missing_or_changed ||
               (reflection.polymorphic? && (record.read_attribute(foreign_type).nil? || record.attribute_changed?(foreign_type)))
           }
 
@@ -144,11 +168,15 @@ module ActiveRecord::Associations::Builder # :nodoc:
     def self.define_change_tracking_methods(model, reflection)
       model.generated_association_methods.class_eval <<-CODE, __FILE__, __LINE__ + 1
         def #{reflection.name}_changed?
-          association(:#{reflection.name}).target_changed?
+          association = association(:#{reflection.name})
+          deprecated_associations_api_guard(association, __method__)
+          association.target_changed?
         end
 
         def #{reflection.name}_previously_changed?
-          association(:#{reflection.name}).target_previously_changed?
+          association = association(:#{reflection.name})
+          deprecated_associations_api_guard(association, __method__)
+          association.target_previously_changed?
         end
       CODE
     end

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

@@ -7,7 +7,7 @@ module ActiveRecord::Associations::Builder # :nodoc:
     CALLBACKS = [:before_add, :after_add, :before_remove, :after_remove]
 
     def self.valid_options(options)
-      super + [:before_add, :after_add, :before_remove, :after_remove, :extend]
+      super + [:class_name, :before_add, :after_add, :before_remove, :after_remove, :extend]
     end
 
     def self.define_callbacks(model, reflection)
@@ -60,7 +60,9 @@ module ActiveRecord::Associations::Builder # :nodoc:
 
       mixin.class_eval <<-CODE, __FILE__, __LINE__ + 1
         def #{name.to_s.singularize}_ids
-          association(:#{name}).ids_reader
+          association = association(:#{name})
+          deprecated_associations_api_guard(association, __method__)
+          association.ids_reader
         end
       CODE
     end
@@ -70,7 +72,9 @@ module ActiveRecord::Associations::Builder # :nodoc:
 
       mixin.class_eval <<-CODE, __FILE__, __LINE__ + 1
         def #{name.to_s.singularize}_ids=(ids)
-          association(:#{name}).ids_writer(ids)
+          association = association(:#{name})
+          deprecated_associations_api_guard(association, __method__)
+          association.ids_writer(ids)
         end
       CODE
     end

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

@@ -7,7 +7,7 @@ module ActiveRecord::Associations::Builder # :nodoc:
     end
 
     def self.valid_options(options)
-      valid = super + [:as, :through]
+      valid = super + [:class_name, :as, :through]
       valid += [:foreign_type] if options[:as]
       valid += [:ensuring_owner_was] if options[:dependent] == :destroy_async
       valid += [:source, :source_type, :disable_joins] if options[:through]

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

@@ -17,11 +17,15 @@ module ActiveRecord::Associations::Builder # :nodoc:
 
       mixin.class_eval <<-CODE, __FILE__, __LINE__ + 1
         def reload_#{name}
-          association(:#{name}).force_reload_reader
+          association = association(:#{name})
+          deprecated_associations_api_guard(association, __method__)
+          association.force_reload_reader
         end
 
         def reset_#{name}
-          association(:#{name}).reset
+          association = association(:#{name})
+          deprecated_associations_api_guard(association, __method__)
+          association.reset
         end
       CODE
     end
@@ -30,19 +34,43 @@ module ActiveRecord::Associations::Builder # :nodoc:
     def self.define_constructors(mixin, name)
       mixin.class_eval <<-CODE, __FILE__, __LINE__ + 1
         def build_#{name}(*args, &block)
-          association(:#{name}).build(*args, &block)
+          association = association(:#{name})
+          deprecated_associations_api_guard(association, __method__)
+          association.build(*args, &block)
         end
 
         def create_#{name}(*args, &block)
-          association(:#{name}).create(*args, &block)
+          association = association(:#{name})
+          deprecated_associations_api_guard(association, __method__)
+          association.create(*args, &block)
         end
 
         def create_#{name}!(*args, &block)
-          association(:#{name}).create!(*args, &block)
+          association = association(:#{name})
+          deprecated_associations_api_guard(association, __method__)
+          association.create!(*args, &block)
         end
       CODE
     end
 
+    def self.define_callbacks(model, reflection)
+      super
+
+      # If the record is saved or destroyed and `:touch` is set, the parent
+      # record gets a timestamp updated. We want to know about it, because
+      # deleting the association would change that side-effect and perhaps there
+      # is code relying on it.
+      if reflection.deprecated? && reflection.options[:touch]
+        model.before_save do
+          report_deprecated_association(reflection, context: ":touch has a side effect here")
+        end
+
+        model.before_destroy do
+          report_deprecated_association(reflection, context: ":touch has a side effect here")
+        end
+      end
+    end
+
     private_class_method :valid_options, :define_accessors, :define_constructors
   end
 end

data/lib/active_record/associations/collection_association.rb

@@ -61,15 +61,19 @@ module ActiveRecord
       # Implements the ids writer method, e.g. foo.item_ids= for Foo.has_many :items
       def ids_writer(ids)
         primary_key = reflection.association_primary_key
-        pk_type = klass.type_for_attribute(primary_key)
         ids = Array(ids).compact_blank
-        ids.map! { |id| pk_type.cast(id) }
 
         records = if klass.composite_primary_key?
+          pk_types = primary_key.map { |column| klass.type_for_attribute(column) }
+          ids.map! { |id| pk_types.zip(id).map! { |type, value| type.cast(value) } }
+
           klass.where(primary_key => ids).index_by do |record|
             primary_key.map { |primary_key| record._read_attribute(primary_key) }
           end
         else
+          pk_type = klass.type_for_attribute(primary_key)
+          ids.map! { |id| pk_type.cast(id) }
+
           klass.where(primary_key => ids).index_by do |record|
             record._read_attribute(primary_key)
           end
@@ -94,7 +98,7 @@ module ActiveRecord
       def find(*args)
         if options[:inverse_of] && loaded?
           args_flatten = args.flatten
-          model = scope.klass
+          model = scope.model
 
           if args_flatten.blank?
             error_message = "Couldn't find #{model.name} without an ID"

data/lib/active_record/associations/collection_proxy.rb

@@ -110,7 +110,7 @@ module ActiveRecord
       #   #    ]
 
       # Finds an object in the collection responding to the +id+. Uses the same
-      # rules as ActiveRecord::FinderMethods.find. Returns ActiveRecord::RecordNotFound
+      # rules as ActiveRecord::FinderMethods.find. Raises ActiveRecord::RecordNotFound
       # error if the object cannot be found.
       #
       #   class Person < ActiveRecord::Base
@@ -726,6 +726,10 @@ module ActiveRecord
       end
 
       def pluck(*column_names)
+        if proxy_association.violates_strict_loading?
+          Base.strict_loading_violation!(owner: proxy_association.owner.class, reflection: proxy_association.reflection)
+        end
+
         null_scope? ? scope.pluck(*column_names) : super
       end
 
@@ -1125,14 +1129,32 @@ module ActiveRecord
         super
       end
 
+      %w(insert insert_all insert! insert_all! upsert upsert_all).each do |method|
+        class_eval <<~RUBY, __FILE__, __LINE__ + 1
+          def #{method}(...)
+            if @association&.target&.any? { |r| r.new_record? }
+              association_name = @association.reflection.name
+              ActiveRecord.deprecator.warn(<<~MSG)
+                Using #{method} on association \#{association_name} with unpersisted records
+                is deprecated and will be removed in Rails 8.2.
+                The unpersisted records will be lost after this operation.
+                Please either persist your records first or store them separately before
+                calling #{method}.
+              MSG
+              scope.#{method}(...)
+            else
+              scope.#{method}(...).tap { reset }
+            end
+          end
+        RUBY
+      end
+
       delegate_methods = [
         QueryMethods,
         SpawnMethods,
       ].flat_map { |klass|
         klass.public_instance_methods(false)
-      } - self.public_instance_methods(false) - [:select] + [
-        :scoping, :values, :insert, :insert_all, :insert!, :insert_all!, :upsert, :upsert_all, :load_async
-      ]
+      } - self.public_instance_methods(false) - [ :select ] + [ :scoping, :values, :load_async ]
 
       delegate(*delegate_methods, to: :scope)
 

data/lib/active_record/associations/deprecation.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+require "active_support/core_ext/array/conversions"
+
+module ActiveRecord::Associations::Deprecation # :nodoc:
+  EVENT = "deprecated_association.active_record"
+  private_constant :EVENT
+
+  MODES = [:warn, :raise, :notify].freeze
+  private_constant :MODES
+
+  class << self
+    attr_reader :mode, :backtrace
+
+    def mode=(value) # private setter
+      unless MODES.include?(value)
+        raise ArgumentError, "invalid deprecated associations mode #{value.inspect} (valid modes are #{MODES.map(&:inspect).to_sentence})"
+      end
+
+      @mode = value
+    end
+
+    def backtrace=(value)
+      @backtrace = !!value
+    end
+
+    def guard(reflection)
+      report(reflection, context: yield) if reflection.deprecated?
+
+      if reflection.through_reflection?
+        reflection.deprecated_nested_reflections.each do |deprecated_nested_reflection|
+          context = "referenced as nested association of the through #{reflection.active_record}##{reflection.name}"
+          report(deprecated_nested_reflection, context: context)
+        end
+      end
+    end
+
+    def report(reflection, context:)
+      reflection = user_facing_reflection(reflection)
+
+      message = +"The association #{reflection.active_record}##{reflection.name} is deprecated, #{context}"
+      message << " (#{backtrace_cleaner.first_clean_frame})"
+
+      case @mode
+      when :warn
+        message = [message, *clean_frames].join("\n\t") if @backtrace
+        ActiveRecord::Base.logger&.warn(message)
+      when :raise
+        error = ActiveRecord::DeprecatedAssociationError.new(message)
+        if set_backtrace_supports_array_of_locations?
+          error.set_backtrace(clean_locations)
+        else
+          error.set_backtrace(clean_frames)
+        end
+        raise error
+      else
+        payload = { reflection: reflection, message: message, location: backtrace_cleaner.first_clean_location }
+        payload[:backtrace] = clean_locations if @backtrace
+        ActiveSupport::Notifications.instrument(EVENT, payload)
+      end
+    end
+
+    private
+      def backtrace_cleaner
+        ActiveRecord::LogSubscriber.backtrace_cleaner
+      end
+
+      def clean_frames
+        backtrace_cleaner.clean(caller)
+      end
+
+      def clean_locations
+        backtrace_cleaner.clean_locations(caller_locations)
+      end
+
+      def set_backtrace_supports_array_of_locations?
+        @backtrace_supports_array_of_locations ||= Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.4.0")
+      end
+
+      def user_facing_reflection(reflection)
+        reflection.active_record.reflect_on_association(reflection.name)
+      end
+  end
+
+  self.mode = :warn
+  self.backtrace = false
+end