Deprecate ActiveRecord::ImmutableRelation

activerecord/lib/active_record/errors.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
+require "active_support/deprecation"
+
 module ActiveRecord
+  include ActiveSupport::Deprecation::DeprecatedConstantAccessor
+
   # = Active Record Errors
   #
   # Generic Active Record exception class.
@@ -476,10 +480,15 @@ def initialize(model = nil, description = nil)
   #   relation.loaded? # => true
   #
   #   # Methods which try to mutate a loaded relation fail.
-  #   relation.where!(title: 'TODO')  # => ActiveRecord::ImmutableRelation
-  #   relation.limit!(5)              # => ActiveRecord::ImmutableRelation
-  class ImmutableRelation < ActiveRecordError
+  #   relation.where!(title: 'TODO')  # => ActiveRecord::UnmodifiableRelation
+  #   relation.limit!(5)              # => ActiveRecord::UnmodifiableRelation
+  class UnmodifiableRelation < ActiveRecordError
   end
+  deprecate_constant(
+    :ImmutableRelation,
+    "ActiveRecord::UnmodifiableRelation",
+    deprecator: ActiveRecord.deprecator
+  )
 
   # TransactionIsolationError will be raised under the following conditions:
   #

activerecord/lib/active_record/relation/query_methods.rb

@@ -174,7 +174,7 @@ def #{method_name}                     # def includes_values
         end                                    # end
 
         def #{method_name}=(value)             # def includes_values=(value)
-          assert_mutability!                   #   assert_mutability!
+          assert_modifiable!                   #   assert_modifiable!
           @values[:#{name}] = value            #   @values[:includes] = value
         end                                    # end
       CODE
@@ -814,7 +814,7 @@ def unscope!(*args) # :nodoc:
           if !VALID_UNSCOPING_VALUES.include?(scope)
             raise ArgumentError, "Called unscope() with invalid unscoping argument ':#{scope}'. Valid arguments are :#{VALID_UNSCOPING_VALUES.to_a.join(", :")}."
           end
-          assert_mutability!
+          assert_modifiable!
           @values.delete(scope)
         when Hash
           scope.each do |key, target_value|
@@ -1723,8 +1723,8 @@ def build_join_dependencies
         )
       end
 
-      def assert_mutability!
-        raise ImmutableRelation if @loaded || @arel
+      def assert_modifiable!
+        raise UnmodifiableRelation if @loaded || @arel
       end
 
       def build_arel(connection, aliases = nil)

activerecord/test/cases/errors_test.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "cases/helper"
+require "active_record/errors"
 
 class ErrorsTest < ActiveRecord::TestCase
   def test_can_be_instantiated_with_no_args
@@ -15,4 +16,11 @@ def test_can_be_instantiated_with_no_args
       end
     end
   end
+
+  def test_active_record_immutable_relation_deprecation
+    expected_message = "ActiveRecord::ImmutableRelation is deprecated! Use ActiveRecord::UnmodifiableRelation instead"
+    assert_deprecated(expected_message, ActiveRecord.deprecator) do
+      assert_same ActiveRecord::UnmodifiableRelation, ActiveRecord::ImmutableRelation
+    end
+  end
 end

activerecord/test/cases/relations_test.rb

@@ -2057,7 +2057,7 @@ def test_destroy_by
     relation = Post.all
     relation.to_a
 
-    assert_raises(ActiveRecord::ImmutableRelation) do
+    assert_raises(ActiveRecord::UnmodifiableRelation) do
       relation.where! "foo"
     end
   end
@@ -2066,7 +2066,7 @@ def test_destroy_by
     relation = Post.all
     relation.to_a
 
-    assert_raises(ActiveRecord::ImmutableRelation) do
+    assert_raises(ActiveRecord::UnmodifiableRelation) do
       relation.limit! 5
     end
   end
@@ -2075,7 +2075,7 @@ def test_destroy_by
     relation = Post.all
     relation.to_a
 
-    assert_raises(ActiveRecord::ImmutableRelation) do
+    assert_raises(ActiveRecord::UnmodifiableRelation) do
       relation.merge! where: "foo"
     end
   end
@@ -2084,7 +2084,7 @@ def test_destroy_by
     relation = Post.all
     relation.to_a
 
-    assert_raises(ActiveRecord::ImmutableRelation) do
+    assert_raises(ActiveRecord::UnmodifiableRelation) do
       relation.extending! Module.new
     end
   end
@@ -2093,8 +2093,8 @@ def test_destroy_by
     relation = Post.all
     relation.arel
 
-    assert_raises(ActiveRecord::ImmutableRelation) { relation.limit!(5) }
-    assert_raises(ActiveRecord::ImmutableRelation) { relation.where!("1 = 2") }
+    assert_raises(ActiveRecord::UnmodifiableRelation) { relation.limit!(5) }
+    assert_raises(ActiveRecord::UnmodifiableRelation) { relation.where!("1 = 2") }
   end
 
   test "relations show the records in #inspect" do