activerecord 8.0.2 → 8.1.0.beta1

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[8.0]
+    class AddSystemSettings < ActiveRecord::Migration[8.1]
       def up
         create_table :system_settings do |t|
           t.string  :name
@@ -214,6 +214,6 @@ Bug reports for the Ruby on \Rails project can be filed here:
 
 * https://github.com/rails/rails/issues
 
-Feature requests should be discussed on the rails-core mailing list here:
+Feature requests should be discussed on the rubyonrails-core forum here:
 
 * https://discuss.rubyonrails.org/c/rubyonrails-core

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

data/lib/active_record/associations/association.rb

@@ -232,7 +232,7 @@ module ActiveRecord
         _create_record(attributes, true, &block)
       end
 
-      # Whether the association represent a single record
+      # Whether the association represents a single record
       # or a collection of records.
       def collection?
         false

data/lib/active_record/associations/belongs_to_association.rb

@@ -162,7 +162,15 @@ module ActiveRecord
         end
 
         def stale_state
-          owner._read_attribute(reflection.foreign_key) { |n| owner.send(:missing_attribute, n, caller) }
+          foreign_key = reflection.foreign_key
+          if foreign_key.is_a?(Array)
+            attributes = foreign_key.map do |fk|
+              owner._read_attribute(fk) { |n| owner.send(:missing_attribute, n, caller) }
+            end
+            attributes if attributes.any?
+          else
+            owner._read_attribute(foreign_key) { |n| owner.send(:missing_attribute, n, caller) }
+          end
         end
     end
   end

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)
@@ -102,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
@@ -110,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
@@ -138,8 +142,15 @@ module ActiveRecord::Associations::Builder # :nodoc:
     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
 
@@ -107,6 +108,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
 
@@ -144,11 +153,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

@@ -259,10 +259,10 @@ module ActiveRecord
         klass = reflection.klass
         return false unless record.is_a?(klass)
 
-        if record.new_record?
-          include_in_memory?(record)
-        elsif loaded?
+        if loaded?
           target.include?(record)
+        elsif record.new_record?
+          include_in_memory?(record)
         else
           record_id = klass.composite_primary_key? ? klass.primary_key.zip(record.id).to_h : record.id
           scope.exists?(record_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
@@ -1125,14 +1125,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

data/lib/active_record/associations/errors.rb

@@ -262,4 +262,7 @@ module ActiveRecord
       end
     end
   end
+
+  class DeprecatedAssociationError < ActiveRecordError
+  end
 end

data/lib/active_record/associations/join_dependency.rb

@@ -235,6 +235,8 @@ module ActiveRecord
               raise EagerLoadPolymorphicError.new(reflection)
             end
 
+            Deprecation.guard(reflection) { "referenced in query to join its table" }
+
             JoinAssociation.new(reflection, build(right, reflection.klass))
           end
         end

data/lib/active_record/associations/preloader/branch.rb

@@ -118,6 +118,7 @@ module ActiveRecord
         def loaders
           @loaders ||=
             grouped_records.flat_map do |reflection, reflection_records|
+              Deprecation.guard(reflection) { "referenced in query to preload records" }
               preloaders_for_reflection(reflection, reflection_records)
             end
         end