Method: ActiveRecord::ConnectionAdapters::SchemaStatements#add_foreign_key

Defined in:
activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb

#add_foreign_key(from_table, to_table, **options) ⇒ Object

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 composite foreign key
Assuming "carts" table has "(shop_id, user_id)" as a primary key.

add_foreign_key :orders, :carts, primary_key: [:shop_id, :user_id]

generates:

ALTER TABLE "orders" ADD CONSTRAINT fk_rails_6f5e4cb3a4 FOREIGN KEY ("cart_shop_id", "cart_user_id") REFERENCES "carts" ("shop_id", "user_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". Pass an array to create a composite foreign key.

:primary_key

The primary key column name on to_table. Defaults to id. Pass an array to create a composite foreign key.

: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.



1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
 
# File 'activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb', line 1173

def add_foreign_key(from_table, to_table, **options)
  return unless use_foreign_keys?
  return if options[:if_not_exists] == true && foreign_key_exists?(from_table, to_table, **options.slice(:column))

  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