Merge pull request rails#50883 from Shopify/infer-inverse-of-deprecation

Put plural inverse association inference behind a configuration flag

Author: byroot

activerecord/lib/active_record/reflection.rb

@@ -11,6 +11,7 @@ module Reflection # :nodoc:
       class_attribute :_reflections, instance_writer: false, default: {}
       class_attribute :aggregate_reflections, instance_writer: false, default: {}
       class_attribute :automatic_scope_inversing, instance_writer: false, default: false
+      class_attribute :automatically_invert_plural_associations, instance_writer: false, default: false
     end
 
     class << self
@@ -700,10 +701,25 @@ def inverse_name
         def automatic_inverse_of
           if can_find_inverse_of_automatically?(self)
             inverse_name = ActiveSupport::Inflector.underscore(options[:as] || active_record.name.demodulize).to_sym
-            plural_inverse_name = ActiveSupport::Inflector.pluralize(inverse_name)
 
             begin
-              reflection = klass._reflect_on_association(inverse_name) || klass._reflect_on_association(plural_inverse_name)
+              reflection = klass._reflect_on_association(inverse_name)
+              if !reflection
+                plural_inverse_name = ActiveSupport::Inflector.pluralize(inverse_name)
+                reflection = klass._reflect_on_association(plural_inverse_name)
+
+                if reflection && !active_record.automatically_invert_plural_associations
+                  ActiveRecord.deprecator.warn(
+                    "The `#{active_record.name}##{name}` inverse association could have been automatically" \
+                    " inferred as `#{klass.name}##{plural_inverse_name}` but wasn't because `automatically_invert_plural_associations`" \
+                    " is disabled.\n\n" \
+                    "If automatic inference is intended, you can consider enabling" \
+                    " `config.active_record.automatically_invert_plural_associations`.\n\n" \
+                    "If automatic inference is not intended, you can silence this warning by defining the association with `inverse_of: false`."
+                  )
+                  reflection = nil
+                end
+              end
             rescue NameError => error
               raise unless error.name.to_s == class_name
 

activerecord/test/cases/associations/inverse_associations_test.rb

@@ -201,6 +201,8 @@ def test_has_many_and_belongs_to_automatic_inverse_shares_objects_on_comment
   end
 
   def test_belongs_to_should_find_inverse_has_many_automatically
+    assert_equal true, Subscription.automatically_invert_plural_associations
+
     book = Book.create!
     subscriber = book.subscribers.new nick: "Nickname"
 

activerecord/test/cases/helper.rb

@@ -32,6 +32,8 @@
 # Quote "type" if it's a reserved word for the current connection.
 QUOTED_TYPE = ActiveRecord::Base.lease_connection.quote_column_name("type")
 
+ActiveRecord::Base.automatically_invert_plural_associations = true
+
 ActiveRecord.raise_on_assign_to_attr_readonly = true
 ActiveRecord.belongs_to_required_validates_foreign_key = false
 

activerecord/test/models/subscriber.rb

@@ -2,6 +2,7 @@
 
 class Subscriber < ActiveRecord::Base
   self.primary_key = "nick"
+
   has_many :subscriptions
   has_many :books, through: :subscriptions
 end

activerecord/test/models/subscription.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 class Subscription < ActiveRecord::Base
+  self.automatically_invert_plural_associations = true
+
   belongs_to :subscriber, counter_cache: :books_count
   belongs_to :book, -> { author_visibility_visible }
 

guides/source/configuring.md

@@ -60,6 +60,7 @@ Below are the default values associated with each target version. In cases of co
 
 #### Default Values for Target Version 7.2
 
+- [`config.active_record.automatically_invert_plural_associations`](#config-active-record-automatically-invert-plural-associations): `true`
 - [`config.active_record.validate_migration_timestamps`](#config-active-record-validate-migration-timestamps): `true`
 - [`config.active_storage.web_image_content_types`](#config-active-storage-web-image-content-types): `%w[image/png image/jpeg image/gif image/webp]`
 
@@ -1051,6 +1052,49 @@ Specifies if an error should be raised if the order of a query is ignored during
 
 Controls whether migrations are numbered with serial integers or with timestamps. The default is `true`, to use timestamps, which are preferred if there are multiple developers working on the same application.
 
+#### `config.active_record.automatically_invert_plural_associations`
+
+Controls whether Active Record will automatically look for an inverse relations with a pluralized name.
+
+Example:
+
+```ruby
+class Post < ApplicationRecord
+  has_many :comments
+end
+
+class Comment < ApplicationRecord
+  belongs_to :post
+end
+```
+
+In the above case Active Record used to only look for a `:comment` (singular) association in `Post`, and won't find it.
+
+With this option enabled, it will also look for a `:comments` association. In the vast majority of cases
+having the inverse association discovered is beneficial as it can prevent some useless queries, but
+it may cause backward compatibility issues with legacy code that doesn't expect it.
+
+This behavior can be disable on a per-model basis:
+
+
+```ruby
+class Comment < ApplicationRecord
+  self.automatically_invert_plural_associations = false
+
+  belongs_to :post
+end
+```
+
+And on a per-association basis:
+
+```ruby
+class Comment < ApplicationRecord
+  self.automatically_invert_plural_associations = false
+
+  belongs_to :post, inverse_of: false
+end
+```
+
 #### `config.active_record.validate_migration_timestamps`
 
 Controls whether to validate migration timestamps. When set, an error will be raised if the

railties/lib/rails/application/configuration.rb

@@ -328,6 +328,7 @@ def load_defaults(target_version)
 
           if respond_to?(:active_record)
             active_record.validate_migration_timestamps = true
+            active_record.automatically_invert_plural_associations = true
           end
         else
           raise "Unknown version #{target_version.to_s.inspect}"

railties/lib/rails/generators/rails/app/templates/config/initializers/new_framework_defaults_7_2.rb.tt

@@ -27,3 +27,17 @@
 # expected format can disable validation by setting this config to `false`.
 #++
 # Rails.application.config.active_record.validate_migration_timestamps = true
+
+###
+# Controls whether Active Record will automatically look for an inverse relations
+# with a pluralized name.
+#
+# Example:
+#   class Comment < ActiveRecord::Base
+#     belongs_to :post
+#   end
+#
+# In the above case Active Record will now try to infer a `:comments` relation
+# on `Post`, while previously it would only look for `:comment`.
+#++
+# Rails.application.config.active_record.automatically_invert_plural_associations = true