`:to_table` when adding a fk through `add_reference`.

Closes #21563.

The `name` argument of `add_references` was both used to generate the
column name `<name>_id` and as the target table for the foreign key
`name.pluralize`.

It's primary purpose is to define the column name. In cases where the
`to_table` of the foreign key is different than the column name we
should be able to specify it individually.

2 files changed, 13 insertions, 3 deletions

diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
index 10329de5f4..eb1aece32d 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
@@ -123,23 +123,29 @@ module ActiveRecord
       end
 
       def foreign_key_options
-        as_options(foreign_key)
+        as_options(foreign_key).merge(column: column_name)
       end
 
       def columns
-        result = [["#{name}_id", type, options]]
+        result = [[column_name, type, options]]
         if polymorphic
           result.unshift(["#{name}_type", :string, polymorphic_options])
         end
         result
       end
 
+      def column_name
+        "#{name}_id"
+      end
+
       def column_names
         columns.map(&:first)
       end
 
       def foreign_table_name
-        Base.pluralize_table_names ? name.to_s.pluralize : name
+        foreign_key_options.fetch(:to_table) do
+          Base.pluralize_table_names ? name.to_s.pluralize : name
+        end
       end
     end
 
diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
index ccff853987..b69fd75377 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
@@ -724,6 +724,10 @@ module ActiveRecord
       #
       #   add_reference(:products, :supplier, foreign_key: true)
       #
+      # ====== Create a supplier_id column and a foreign key to the firms table
+      #
+      #   add_reference(:products, :supplier, foreign_key: {to_table: :firms})
+      #
       def add_reference(table_name, *args)
         ReferenceDefinition.new(*args).add_to(update_table_definition(table_name, self))
       end