Module: ActiveRecord::ConnectionAdapters::SchemaStatements

Adds a new column to the named table. See TableDefinition#column for details of the options you can use.

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 articles_author_id_fk FOREIGN KEY ("author_id") REFERENCES "authors" ("id")

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 articles_author_id_fk 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

Adds a new index to the table. column_name can be a single ::Symbol, or an ::Array of Symbols.

The index will be named after the table and the column name(s), unless you pass :name as an option.

Creating a simple index

add_index(:suppliers, :name)

generates:

CREATE INDEX suppliers_name_index ON suppliers(name)

Creating a unique index

add_index(:accounts, [:branch_id, :party_id], unique: true)

generates:

CREATE UNIQUE INDEX accounts_branch_id_party_id_index ON accounts(branch_id, party_id)

Creating a named index

add_index(:accounts, [:branch_id, :party_id], unique: true, name: 'by_branch_party')

generates:

CREATE UNIQUE INDEX by_branch_party ON accounts(branch_id, party_id)

Creating an index with specific key length

add_index(:accounts, :name, name: 'by_name', length: 10)

generates:

CREATE INDEX by_name ON accounts(name(10))

add_index(:accounts, [:name, :surname], name: 'by_name_surname', length: {name: 10, surname: 15})

generates:

CREATE INDEX by_name_surname ON accounts(name(10), surname(15))

Note: SQLite doesn't support index length.

Creating an index with a sort order (desc or asc, asc is the default)

add_index(:accounts, [:branch_id, :party_id, :surname], order: {branch_id: :desc, party_id: :asc})

generates:

CREATE INDEX by_branch_desc_party ON accounts(branch_id DESC, party_id ASC, surname)

Note: MySQL doesn't yet support index order (it accepts the syntax but ignores it).

Creating a partial index

add_index(:accounts, [:branch_id, :party_id], unique: true, where: "active")

generates:

CREATE UNIQUE INDEX index_accounts_on_branch_id_and_party_id ON accounts(branch_id, party_id) WHERE active

Note: Partial indexes are only supported for PostgreSQL and SQLite 3.8.0+.

Creating an index with a specific method

add_index(:developers, :name, using: 'btree')

generates:

CREATE INDEX index_developers_on_name ON developers USING btree (name) -- PostgreSQL
CREATE INDEX index_developers_on_name USING btree ON developers (name) -- MySQL

Note: only supported by PostgreSQL and MySQL

Creating an index with a specific type

add_index(:developers, :name, type: :fulltext)

generates:

CREATE FULLTEXT INDEX index_developers_on_name ON developers (name) -- MySQL

Note: only supported by MySQL. Supported: :fulltext and :spatial on MyISAM tables.

Adds a reference. The reference column is an integer by default, the :type option can be used to specify a different type. Optionally adds a _type column, if :polymorphic option is provided. add_reference and #add_belongs_to are acceptable.

The options hash can include the following keys:

:type

The reference column type. Defaults to :integer.

:index

Add an appropriate index. Defaults to false.

:foreign_key

Add an appropriate foreign key. Defaults to false.

:polymorphic

Wether an additional _type column should be added. Defaults to false.

Create a user_id integer column

add_reference(:products, :user)

Create a user_id string column

add_reference(:products, :user, type: :string)

Create supplier_id, supplier_type columns and appropriate index

add_reference(:products, :supplier, polymorphic: true, index: true)

Adds timestamps (created_at and updated_at) columns to table_name. Additional options (like null: false) are forwarded to #add_column.

add_timestamps(:suppliers, null: false)

Changes the column's definition according to the new options. See TableDefinition#column for details of the options you can use.

change_column(:suppliers, :name, :string, limit: 80)
change_column(:accounts, :description, :text)

Sets a new default value for a column:

change_column_default(:suppliers, :qualification, 'new')
change_column_default(:accounts, :authorized, 1)

Setting the default to nil effectively drops the default:

change_column_default(:users, :email, nil)

Sets or removes a NOT NULL constraint on a column. The null flag indicates whether the value can be NULL. For example

change_column_null(:users, :nickname, false)

says nicknames cannot be NULL (adds the constraint), whereas

change_column_null(:users, :nickname, true)

allows them to be NULL (drops the constraint).

The method accepts an optional fourth argument to replace existing NULLs with some other value. Use that one when enabling the constraint if needed, since otherwise those rows would not be valid.

Please note the fourth argument does not set a column's default.

A block for changing columns in table.

# change_table() yields a Table instance
change_table(:suppliers) do |t|
  t.column :name, :string, limit: 60
  # Other column alterations here
end

The options hash can include the following keys:

:bulk

Set this to true to make this a bulk alter query, such as

ALTER TABLE `users` ADD COLUMN age INT(11), ADD COLUMN birthdate DATETIME ...

Defaults to false.

Add a column

change_table(:suppliers) do |t|
  t.column :name, :string, limit: 60
end

Add 2 integer columns

change_table(:suppliers) do |t|
  t.integer :width, :height, null: false, default: 0
end

Add created_at/updated_at columns

change_table(:suppliers) do |t|
  t.timestamps
end

Add a foreign key column

change_table(:suppliers) do |t|
  t.references :company
end

Creates a company_id(integer) column.

Add a polymorphic foreign key column

change_table(:suppliers) do |t|
  t.belongs_to :company, polymorphic: true
end

Creates company_type(varchar) and company_id(integer) columns.

Remove a column

change_table(:suppliers) do |t|
  t.remove :company
end

Remove several columns

change_table(:suppliers) do |t|
  t.remove :company_id
  t.remove :width, :height
end

Remove an index

change_table(:suppliers) do |t|
  t.remove_index :company_id
end

See also Table for details on all of the various column transformation.

Checks to see if a column exists in a given table.

# Check a column exists
column_exists?(:suppliers, :name)

# Check a column exists of a particular type
column_exists?(:suppliers, :name, :string)

# Check a column exists with a specific definition
column_exists?(:suppliers, :name, :string, limit: 100)
column_exists?(:suppliers, :name, :string, default: 'default')
column_exists?(:suppliers, :name, :string, null: false)
column_exists?(:suppliers, :tax, :decimal, precision: 8, scale: 2)

Returns an array of Column objects for the table specified by table_name. See the concrete implementation for details on the expected parameter values.

Creates a new join table with the name created using the lexical order of the first two arguments. These arguments can be a ::String or a ::Symbol.

# Creates a table called 'assemblies_parts' with no id.
create_join_table(:assemblies, :parts)

You can pass a options hash can include the following keys:

:table_name

Sets the table name overriding the default

:column_options

Any extra options you want appended to the columns definition.

:options

Any extra options you want appended to the table definition.

:temporary

Make a temporary table.

:force

Set to true to drop the table before creating it. Defaults to false.

Note that create_join_table does not create any indices by default; you can use its block form to do so yourself:

create_join_table :products, :categories do |t|
  t.index :product_id
  t.index :category_id
end

Add a backend specific option to the generated SQL (MySQL)

create_join_table(:assemblies, :parts, options: 'ENGINE=InnoDB DEFAULT CHARSET=utf8')

generates:

CREATE TABLE assemblies_parts (
  assembly_id int NOT NULL,
  part_id int NOT NULL,
) ENGINE=InnoDB DEFAULT CHARSET=utf8

Creates a new table with the name table_name. table_name may either be a ::String or a ::Symbol.

There are two ways to work with create_table. You can use the block form or the regular form, like this:

Block form

# create_table() passes a TableDefinition object to the block.
# This form will not only create the table, but also columns for the
# table.

create_table(:suppliers) do |t|
  t.column :name, :string, limit: 60
  # Other fields here
end

Block form, with shorthand

# You can also use the column types as method calls, rather than calling the column method.
create_table(:suppliers) do |t|
  t.string :name, limit: 60
  # Other fields here
end

Regular form

# Creates a table called 'suppliers' with no columns.
create_table(:suppliers)
# Add a column to 'suppliers'.
add_column(:suppliers, :name, :string, {limit: 60})

The options hash can include the following keys:

:id

Whether to automatically add a primary key column. Defaults to true. Join tables for has_and_belongs_to_many should set it to false.

:primary_key

The name of the primary key, if one is to be added automatically. Defaults to id. If :id is false this option is ignored.

Note that Active Record models will automatically detect their primary key. This can be avoided by using self.primary_key= on the model to define the key explicitly.

:options

Any extra options you want appended to the table definition.

:temporary

Make a temporary table.

:force

Set to true to drop the table before creating it. Set to :cascade to drop dependent objects as well. Defaults to false.

:as

SQL to use to generate the table. When this option is used, the block is ignored, as are the :id and :primary_key options.

Add a backend specific option to the generated SQL (MySQL)

create_table(:suppliers, options: 'ENGINE=InnoDB DEFAULT CHARSET=utf8')

generates:

CREATE TABLE suppliers (
  id int(11) DEFAULT NULL auto_increment PRIMARY KEY
) ENGINE=InnoDB DEFAULT CHARSET=utf8

Rename the primary key column

create_table(:objects, primary_key: 'guid') do |t|
  t.column :name, :string, limit: 80
end

generates:

CREATE TABLE objects (
  guid int(11) DEFAULT NULL auto_increment PRIMARY KEY,
  name varchar(80)
)

Do not add a primary key column

create_table(:categories_suppliers, id: false) do |t|
  t.column :category_id, :integer
  t.column :supplier_id, :integer
end

generates:

CREATE TABLE categories_suppliers (
  category_id int,
  supplier_id int
)

Create a temporary table based on a query

create_table(:long_query, temporary: true,
  as: "SELECT * FROM orders INNER JOIN line_items ON order_id=orders.id")

generates:

CREATE TEMPORARY TABLE long_query AS
  SELECT * FROM orders INNER JOIN line_items ON order_id=orders.id

See also TableDefinition#column for details on how to create columns.

Checks to see if the data source name exists on the database.

data_source_exists?(:ebooks)

Returns the relation names useable to back Active Record models. For most adapters this means all tables and views.

Drops the join table specified by the given arguments. See #create_join_table for details.

Although this command ignores the block if one is given, it can be helpful to provide one in a migration's change method so it can be reverted. In that case, the block will be used by create_join_table.

Drops a table from the database.

:force

Set to :cascade to drop dependent objects as well. Defaults to false.

Although this command ignores most options and the block if one is given, it can be helpful to provide these in a migration's change method so it can be reverted. In that case, options and the block will be used by create_table.

Returns an array of foreign keys for the given table. The foreign keys are represented as ForeignKeyDefinition objects.

Checks to see if an index exists on a table for a given index definition.

# Check an index exists
index_exists?(:suppliers, :company_id)

# Check an index on multiple columns exists
index_exists?(:suppliers, [:company_id, :company_type])

# Check a unique index exists
index_exists?(:suppliers, :company_id, unique: true)

# Check an index with a custom name exists
index_exists?(:suppliers, :company_id, name: "idx_company_id")

Verifies the existence of an index with a given name.

The default argument is returned if the underlying implementation does not define the indexes method, as there's no way to determine the correct answer in that case.

Should not be called normally, but this operation is non-destructive. The migrations module handles this automatically.

Returns a hash of mappings from the abstract data types to the native database types. See TableDefinition#column for details on the recognized abstract data types.

Alias for #remove_reference.

Removes the column from the table definition.

remove_column(:suppliers, :qualification)

The type and options parameters will be ignored if present. It can be helpful to provide these in a migration's change method so it can be reverted. In that case, type and options will be used by add_column.

Removes the given columns from the table definition.

remove_columns(:suppliers, :qualification, :experience)

Removes the given foreign key from the table.

Removes the foreign key on accounts.branch_id.

remove_foreign_key :accounts, :branches

Removes the foreign key on accounts.owner_id.

remove_foreign_key :accounts, column: :owner_id

Removes the foreign key named special_fk_name on the accounts table.

remove_foreign_key :accounts, name: :special_fk_name

Removes the given index from the table.

Removes the index_accounts_on_column in the accounts table.

remove_index :accounts, :column

Removes the index named index_accounts_on_branch_id in the accounts table.

remove_index :accounts, column: :branch_id

Removes the index named index_accounts_on_branch_id_and_party_id in the accounts table.

remove_index :accounts, column: [:branch_id, :party_id]

Removes the index named by_branch_party in the accounts table.

remove_index :accounts, name: :by_branch_party

Removes the reference(s). Also removes a type column if one exists. remove_reference, remove_references and #remove_belongs_to are acceptable.

Remove the reference

remove_reference(:products, :user, index: true)

Remove polymorphic reference

remove_reference(:products, :supplier, polymorphic: true)

Remove the reference with a foreign key

remove_reference(:products, :user, index: true, foreign_key: true)

Removes the timestamp columns (created_at and updated_at) from the table definition.

remove_timestamps(:suppliers)

Renames a column.

rename_column(:suppliers, :description, :name)

Renames an index.

Rename the index_people_on_last_name index to index_users_on_last_name:

rename_index :people, 'index_people_on_last_name', 'index_users_on_last_name'

Renames a table.

rename_table('octopuses', 'octopi')

Truncates a table alias according to the limits of the current adapter.

Checks to see if the table table_name exists on the database.

table_exists?(:developers)