add_foreign_key

Adds a new foreign key. from_table is the table with the key column, to_table contains the referenced primary key.

The foreign key will be named after the following pattern: fk_rails_<identifier>. identifier is a 10 character long string which is deterministically generated from the from_table and column. A custom name can be specified with the :name option.

Creating a simple foreign key

add_foreign_key :articles, :authors

generates:

ALTER TABLE "articles" ADD CONSTRAINT fk_rails_e74ce85cbc FOREIGN KEY ("author_id") REFERENCES "authors" ("id")

Creating a foreign key, ignoring method call if the foreign key exists

add_foreign_key(:articles, :authors, if_not_exists: true)

Creating a foreign key on a specific column

add_foreign_key :articles, :users, column: :author_id, primary_key: "lng_id"

generates:

ALTER TABLE "articles" ADD CONSTRAINT fk_rails_58ca3d3a82 FOREIGN KEY ("author_id") REFERENCES "users" ("lng_id")

Creating a cascading foreign key

add_foreign_key :articles, :authors, on_delete: :cascade

generates:

ALTER TABLE "articles" ADD CONSTRAINT fk_rails_e74ce85cbc FOREIGN KEY ("author_id") REFERENCES "authors" ("id") ON DELETE CASCADE

The options hash can include the following keys:

:column

The foreign key column name on from_table. Defaults to to_table.singularize + "_id"

:primary_key

The primary key column name on to_table. Defaults to id.

:name

The constraint name. Defaults to fk_rails_<identifier>.

:on_delete

Action that happens ON DELETE. Valid values are :nullify, :cascade and :restrict

:on_update

Action that happens ON UPDATE. Valid values are :nullify, :cascade and :restrict

:if_not_exists

Specifies if the foreign key already exists to not try to re-add it. This will avoid duplicate column errors.

:validate

(PostgreSQL only) Specify whether or not the constraint should be validated. Defaults to true.

:deferrable

(PostgreSQL only) Specify whether or not the foreign key should be deferrable. Valid values are booleans or :deferred or :immediate to specify the default behavior. Defaults to false.

# File activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb, line 1085
      def add_foreign_key(from_table, to_table, **options)
        return unless supports_foreign_keys?
        return if options[:if_not_exists] == true && foreign_key_exists?(from_table, to_table)

        options = foreign_key_options(from_table, to_table, options)
        at = create_alter_table from_table
        at.add_foreign_key to_table, options

        execute schema_creation.accept(at)
      end