Add a `foreign_key` option to `references` while creating the table

Rather than having to do:

    create_table :posts do |t|
      t.references :user
    end

    add_foreign_key :posts, :users

You can instead do:

    create_table :posts do |t|
      t.references :user, foreign_key: true
    end

Similar to the `index` option, you can also pass a hash. This will be
passed as the options to `add_foreign_key`. e.g.:

    create_table :posts do |t|
      t.references :user, foreign_key: { primary_key: :other_id }
    end

is equivalent to

    create_table :posts do |t|
      t.references :user
    end

    add_foreign_key :posts, :users, primary_key: :other_id

1 files changed, 60 insertions, 0 deletions

diff --git a/activerecord/test/cases/migration/references_foreign_key_test.rb b/activerecord/test/cases/migration/references_foreign_key_test.rb
new file mode 100644
index 0000000000..2fa7584a60
--- /dev/null
+++ b/activerecord/test/cases/migration/references_foreign_key_test.rb
@@ -0,0 +1,60 @@
+require 'cases/helper'
+
+if ActiveRecord::Base.connection.supports_foreign_keys?
+module ActiveRecord
+  class Migration
+    class ReferencesForeignKeyTest < ActiveRecord::TestCase
+      setup do
+        @connection = ActiveRecord::Base.connection
+        @connection.transaction do
+          @connection.create_table(:testing_parents, force: true)
+        end
+      end
+
+      teardown do
+        @connection.execute("drop table if exists testings")
+        @connection.execute("drop table if exists testing_parents")
+      end
+
+      test "foreign keys can be created with the table" do
+        @connection.create_table :testings do |t|
+          t.references :testing_parent, foreign_key: true
+        end
+
+        fk = @connection.foreign_keys("testings").first
+        assert_equal "testings", fk.from_table
+        assert_equal "testing_parents", fk.to_table
+      end
+
+      test "no foreign key is created by default" do
+        @connection.create_table :testings do |t|
+          t.references :testing_parent
+        end
+
+        assert_equal [], @connection.foreign_keys("testings")
+      end
+
+      test "options hash can be passed" do
+        @connection.change_table :testing_parents do |t|
+          t.integer :other_id
+          t.index :other_id, unique: true
+        end
+        @connection.create_table :testings do |t|
+          t.references :testing_parent, foreign_key: { primary_key: :other_id }
+        end
+
+        fk = @connection.foreign_keys("testings").find { |k| k.to_table == "testing_parents" }
+        assert_equal "other_id", fk.primary_key
+      end
+
+      test "foreign keys cannot be added to polymorphic relations when creating the table" do
+        @connection.create_table :testings do |t|
+          assert_raises(ArgumentError) do
+            t.references :testing_parent, polymorphic: true, foreign_key: true
+          end
+        end
+      end
+    end
+  end
+end
+end