activerecord 8.0.0 → 8.1.2

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/alias_tracker.rb

@@ -26,16 +26,18 @@ module ActiveRecord
       end
 
       def self.initial_count_for(connection, name, table_joins)
-        quoted_name = nil
+        quoted_name_escaped = nil
+        name_escaped = nil
 
         counts = table_joins.map do |join|
           if join.is_a?(Arel::Nodes::StringJoin)
-            # quoted_name should be case ignored as some database adapters (Oracle) return quoted name in uppercase
-            quoted_name ||= connection.quote_table_name(name)
+            # quoted_name_escaped should be case ignored as some database adapters (Oracle) return quoted name in uppercase
+            quoted_name_escaped ||= Regexp.escape(connection.quote_table_name(name))
+            name_escaped ||= Regexp.escape(name)
 
             # Table names + table aliases
             join.left.scan(
-              /JOIN(?:\s+\w+)?\s+(?:\S+\s+)?(?:#{quoted_name}|#{name})\sON/i
+              /JOIN(?:\s+\w+)?\s+(?:\S+\s+)?(?:#{quoted_name_escaped}|#{name_escaped})\sON/i
             ).size
           elsif join.is_a?(Arel::Nodes::Join)
             join.left.name == name ? 1 : 0

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

@@ -19,10 +19,16 @@ module ActiveRecord
             id = owner.public_send(reflection.foreign_key)
           end
 
+          association_class = if reflection.polymorphic?
+            owner.public_send(reflection.foreign_type)
+          else
+            reflection.klass
+          end
+
           enqueue_destroy_association(
             owner_model_name: owner.class.to_s,
             owner_id: owner.id,
-            association_class: reflection.klass.to_s,
+            association_class: association_class.to_s,
             association_ids: [id],
             association_primary_key_column: primary_key_column,
             ensuring_owner_was_method: options.fetch(:ensuring_owner_was, nil)
@@ -129,7 +135,9 @@ module ActiveRecord
             target_key_values = record ? Array(primary_key(record.class)).map { |key| record._read_attribute(key) } : []
 
             if force || reflection_fk.map { |fk| owner._read_attribute(fk) } != target_key_values
+              owner_pk = Array(owner.class.primary_key)
               reflection_fk.each_with_index do |key, index|
+                next if record.nil? && owner_pk.include?(key)
                 owner[key] = target_key_values[index]
               end
             end
@@ -156,7 +164,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/join_association.rb

@@ -38,41 +38,39 @@ module ActiveRecord
             chain << [reflection, table]
           end
 
-          base_klass.with_connection do |connection|
-            # The chain starts with the target table, but we want to end with it here (makes
-            # more sense in this context), so we reverse
-            chain.reverse_each do |reflection, table|
-              klass = reflection.klass
+          # The chain starts with the target table, but we want to end with it here (makes
+          # more sense in this context), so we reverse
+          chain.reverse_each do |reflection, table|
+            klass = reflection.klass
 
-              scope = reflection.join_scope(table, foreign_table, foreign_klass)
+            scope = reflection.join_scope(table, foreign_table, foreign_klass)
 
-              unless scope.references_values.empty?
-                associations = scope.eager_load_values | scope.includes_values
+            unless scope.references_values.empty?
+              associations = scope.eager_load_values | scope.includes_values
 
-                unless associations.empty?
-                  scope.joins! scope.construct_join_dependency(associations, Arel::Nodes::OuterJoin)
-                end
+              unless associations.empty?
+                scope.joins! scope.construct_join_dependency(associations, Arel::Nodes::OuterJoin)
               end
+            end
 
-              arel = scope.arel(alias_tracker.aliases)
-              nodes = arel.constraints.first
+            arel = scope.arel(alias_tracker.aliases)
+            nodes = arel.constraints.first
 
-              if nodes.is_a?(Arel::Nodes::And)
-                others = nodes.children.extract! do |node|
-                  !Arel.fetch_attribute(node) { |attr| attr.relation.name == table.name }
-                end
+            if nodes.is_a?(Arel::Nodes::And)
+              others = nodes.children.extract! do |node|
+                !Arel.fetch_attribute(node) { |attr| attr.relation.name == table.name }
               end
+            end
 
-              joins << join_type.new(table, Arel::Nodes::On.new(nodes))
+            joins << join_type.new(table, Arel::Nodes::On.new(nodes))
 
-              if others && !others.empty?
-                joins.concat arel.join_sources
-                append_constraints(connection, joins.last, others)
-              end
-
-              # The current table in this iteration becomes the foreign table in the next
-              foreign_table, foreign_klass = table, klass
+            if others && !others.empty?
+              joins.concat arel.join_sources
+              append_constraints(joins.last, others)
             end
+
+            # The current table in this iteration becomes the foreign table in the next
+            foreign_table, foreign_klass = table, klass
           end
 
           joins
@@ -91,10 +89,10 @@ module ActiveRecord
         end
 
         private
-          def append_constraints(connection, join, constraints)
+          def append_constraints(join, constraints)
             if join.is_a?(Arel::Nodes::StringJoin)
               join_string = Arel::Nodes::And.new(constraints.unshift join.left)
-              join.left = Arel.sql(connection.visitor.compile(join_string))
+              join.left = join_string
             else
               right = join.right
               right.expr = Arel::Nodes::And.new(constraints.unshift right.expr)

data/lib/active_record/associations/join_dependency.rb

@@ -103,7 +103,7 @@ module ActiveRecord
       end
 
       def instantiate(result_set, strict_loading_value, &block)
-        primary_key = aliases.column_alias(join_root, join_root.primary_key)
+        primary_key = Array(join_root.primary_key).map { |column| aliases.column_alias(join_root, column) }
 
         seen = Hash.new { |i, parent|
           i[parent] = Hash.new { |j, child_class|
@@ -141,7 +141,7 @@ module ActiveRecord
 
         message_bus.instrument("instantiation.active_record", payload) do
           result_set.each { |row_hash|
-            parent_key = primary_key ? row_hash[primary_key] : row_hash
+            parent_key = primary_key.empty? ? row_hash : row_hash.values_at(*primary_key)
             parent = parents[parent_key] ||= join_root.instantiate(row_hash, column_aliases, column_types, &block)
             construct(parent, join_root, row_hash, seen, model_cache, strict_loading_value)
           }
@@ -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/batch.rb

@@ -38,7 +38,13 @@ module ActiveRecord
           attr_reader :loaders
 
           def group_and_load_similar(loaders)
-            loaders.grep_v(ThroughAssociation).group_by(&:loader_query).each_pair do |query, similar_loaders|
+            non_through = loaders.grep_v(ThroughAssociation)
+
+            grouped = non_through.group_by do |loader|
+              [loader.loader_query, loader.klass]
+            end
+
+            grouped.each do |(query, _klass), similar_loaders|
               query.load_records_in_batch(similar_loaders)
             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