Defines a foreign key.

By default it assumes you are linking to the referenced table via its primary key with name :id. If you are using a non-default key setup (e.g. using uuid type keys) you must ensure you set the options, such as :name and :type, to match your target key.

Examples

create table("products") do
  add :group_id, references("groups")
end

create table("categories") do
  add :group_id, :integer
  # A composite foreign that points from categories (product_id, group_id)
  # to products (id, group_id)
  add :product_id, references("products", with: [group_id: :group_id])
end

Options

• :name - The name of the underlying reference, which defaults to "#{table}_#{column}_fkey".
• :column - The foreign key column name, which defaults to :id.
• :prefix - The prefix for the reference. Defaults to the prefix defined by the block's table/2 struct (the "products" table in the example above), or nil.
• :type - The foreign key type, which defaults to :bigserial.
• :on_delete - What to do if the referenced entry is deleted. May be :nothing (default), :delete_all, :nilify_all, or :restrict.
• :on_update - What to do if the referenced entry is updated. May be :nothing (default), :update_all, :nilify_all, or :restrict.
• :validate - Whether or not to validate the foreign key constraint on creation or not. Only available in PostgreSQL, and should be followed by a command to validate the foreign key in a following migration if false.
• :with - defines additional keys to the foreign key in order to build a composite primary key
• :match - select if the match is :simple, :partial, or :full. This is supported only by PostgreSQL at the moment.