Ecto v0.7.0 → Overview → Ecto → Migration

Ecto.Migration

Migrations are used to modify your database schema over time.

This module provides many helpers for migrating the database, allowing developers to use Elixir to alter their storage in a way it is database independent.

Here is an example:

defmodule MyRepo.Migrations.CreatePosts do
  use Ecto.Migration

  def up do
    create table(:weather) do
      add :city,    :string, size: 40
      add :temp_lo, :integer
      add :temp_hi, :integer
      add :prcp,    :float

      timestamps
    end
  end

  def down do
    drop table(:weather)
  end
end

Note migrations have an up/0 and down/0 instructions, where up/0 is used to update your database and down/0 rolls back the prompted changes.

Ecto provides some mix tasks to help developers work with migrations:

Run the mix help COMMAND for more information.

Change

Migrations can also be automatically reversible by implementing change/0 instead of up/0 and down/0. For example, the migration above can be written as:

defmodule MyRepo.Migrations.CreatePosts do
  use Ecto.Migration

  def change do
    create table(:weather) do
      add :city,    :string, size: 40
      add :temp_lo, :integer
      add :temp_hi, :integer
      add :prcp,    :float

      timestamps
    end
  end
end

Notice not all commands are reversible though. Trying to rollback a non-reversible command will raise an Ecto.MigrationError.

Source

Summary↑

add(column, type \\ :string, opts \\ [])

Adds a column when creating or altering a table
alter(object, list2)

Alters a table
create(object)

Creates an index
create(object, list2)

Creates a table
drop(object)

Drops a table or index
execute(command)

Executes arbitrary SQL
exists?(object)

Checks if a table or index exists
index(table, columns, opts \\ [])

Returns an index struct that can be used on create, drop, etc
modify(column, type, opts \\ [])

Modifies a column when altering a table
references(table, opts \\ [])

Adds a foreign key
remove(column)

Removes a column when altering a table
table(name, opts \\ [])

Returns a table struct that can be given on create, alter, etc
timestamps()

Adds :inserted_at and :updated_at timestamps columns

Functions

add(column, type \\ :string, opts \\ [])
(function) # ↑

Adds a column when creating or altering a table.

Examples

create table(:posts) do
  add :title, :string, default: "Untitled"
end

alter table(:posts) do
  add :summary, :text
end

Options

  • :default - the column's default value.
  • :primary_key - when true, marks this field as the primary key
  • :null - when false, the column does not allow null values.
  • :size - the size of the type (for example the numbers of characters). Default is no size.
  • :precision - the precision for a numberic type. Default is no precision.
  • :scale - the scale of a numberic type. Default is 0 scale.
Source
create(object)
(function) # ↑

Creates an index.

Examples

create index(:posts, [:name])
Source
drop(object)
(function) # ↑

Drops a table or index.

Examples

drop index(:posts, [:name])
drop table(:posts)
Source
execute(command)
(function) # ↑

Executes arbitrary SQL.

Examples

execute "UPDATE posts SET published_at = NULL"
Source
exists?(object)
(function) # ↑

Checks if a table or index exists.

Examples

exists? table(:products)
Source
index(table, columns, opts \\ [])
(function) # ↑

Returns an index struct that can be used on create, drop, etc.

Expects the table name as first argument and the index fields as second. The field can be an atom, representing a column, or a string representing an expression that is sent as is to the database.

Indexes are non-unique by default.

Examples

# Without a name, index defaults to products_category_id_sku_index
create index(:products, [:category_id, :sku], unique: true)

# Name can be given explicitly though
drop index(:products, [:category_id, :sku], name: :my_special_name)
Source
modify(column, type, opts \\ [])
(function) # ↑

Modifies a column when altering a table.

Examples

alter table(:posts) do
  modify :title, :text
end

Options

Accepts the same options as add/3.

Source
references(table, opts \\ [])
(function) # ↑

Adds a foreign key.

Examples

create table(:product) do
  add :category_id, references(:category)
end

Options

  • :column - The foreign key column, default is :id
  • :type - The foreign key type, default is :integer
Source
remove(column)
(function) # ↑

Removes a column when altering a table.

Examples

alter table(:posts) do
  remove :title
end
Source
table(name, opts \\ [])
(function) # ↑

Returns a table struct that can be given on create, alter, etc.

Examples

create table(:products) do
  add :name, :string
  add :price, :decimal
end

drop table(:products)

create table(:products, primary_key: false) do
  add :name, :string
  add :price, :decimal
end

Options

  • :primary_key - when false, does not generate primary key on table creation
Source
timestamps()
(function) # ↑

Adds :inserted_at and :updated_at timestamps columns.

Those columns are of :datetime type and cannot be null.

Source

Macros

alter(object, list2)
(macro) # ↑

Alters a table.

Examples

alter table(:posts) do
  add :summary, :text
  modify :title, :text
  remove :views
end
Source
create(object, list2)
(macro) # ↑

Creates a table.

By default, the table will also include a primary_key of name :id and type :serial. Check table/2 docs for more information.

Examples

create table(:posts) do
  add :title, :string, default: "Untitled"
  add :body,  :text

  timestamps
end
Source