Ecto SQL v3.0.3 Ecto.Migrator View Source

This module provides the migration API.

Example

defmodule MyApp.MigrationExample do
  use Ecto.Migration

  def up do
    execute "CREATE TABLE users(id serial PRIMARY_KEY, username text)"
  end

  def down do
    execute "DROP TABLE users"
  end
end

Ecto.Migrator.up(Repo, 20080906120000, MyApp.MigrationExample)

Link to this section Summary

Functions

Runs a down migration on the given repository

Gets all migrated versions

Returns an array of tuples as the migration status of the given repo, without actually running any migrations

Returns an array of tuples as the migration status of the given repo, without actually running any migrations

Gets the migrations path from a repository

Runs migrations for the given repository

Apply migrations to a repository with a given strategy

Runs an up migration on the given repository

Link to this section Functions

Link to this function down(repo, version, module, opts \\ []) View Source

Runs a down migration on the given repository.

Options

  • :log - the level to use for logging. Defaults to :info. Can be any of Logger.level/0 values or a boolean.
  • :log_sql - the level to use for logging of SQL instructions. Defaults to false. Can be any of Logger.level/0 values or a boolean.
  • :prefix - the prefix to run the migrations on
Link to this function migrated_versions(repo, opts \\ []) View Source
migrated_versions(Ecto.Repo.t(), Keyword.t()) :: [integer()]

Gets all migrated versions.

This function ensures the migration table exists if no table has been defined yet.

Options

  • :prefix - the prefix to run the migrations on
Link to this function migrations(repo) View Source
migrations(Ecto.Repo.t()) :: [
  {:up | :down, id :: integer(), name :: String.t()}
]

Returns an array of tuples as the migration status of the given repo, without actually running any migrations.

Equivalent to:

Ecto.Migrator.migrations(repo, Ecto.Migrator.migrations_path(repo))
Link to this function migrations(repo, directory) View Source
migrations(Ecto.Repo.t(), String.t()) :: [
  {:up | :down, id :: integer(), name :: String.t()}
]

Returns an array of tuples as the migration status of the given repo, without actually running any migrations.

Link to this function migrations_path(repo) View Source
migrations_path(Ecto.Repo.t()) :: String.t()

Gets the migrations path from a repository.

Link to this function run(repo, direction, opts) View Source
run(Ecto.Repo.t(), atom(), Keyword.t()) :: [integer()]

Runs migrations for the given repository.

Equivalent to:

Ecto.Migrator.run(repo, Ecto.Migrator.migrations_path(repo), direction, opts)

See run/4 for more information.

Link to this function run(repo, migration_source, direction, opts) View Source
run(Ecto.Repo.t(), binary() | [{integer(), module()}], atom(), Keyword.t()) :: [
  integer()
]

Apply migrations to a repository with a given strategy.

The second argument identifies where the migrations are sourced from. A binary representing a directory may be passed, in which case we will load all files following the “#{VERSION}_#{NAME}.exs” schema. The migration_source may also be a list of a list of tuples that identify the version number and migration modules to be run, for example:

Ecto.Migrator.run(Repo, [{0, MyApp.Migration1}, {1, MyApp.Migration2}, ...], :up, opts)

A strategy (which is one of :all, :step or :to) must be given as an option.

Execution model

In order to run migrations, at least two database connections are necessary. One is used to lock the “schema_migrations” table and the other one to effectively run the migrations. This allows multiple nodes to run migrations at the same time, but guarantee that only one of them will effectively migrate the database.

A downside of this approach is that migrations cannot run dynamically during test under the Ecto.Adapters.SQL.Sandbox, as the sandbox has to share a single connection across processes to guarantee the changes can be reverted.

Options

  • :all - runs all available if true
  • :step - runs the specific number of migrations
  • :to - runs all until the supplied version is reached
  • :log - the level to use for logging. Defaults to :info. Can be any of Logger.level/0 values or a boolean.
  • :prefix - the prefix to run the migrations on
Link to this function up(repo, version, module, opts \\ []) View Source
up(Ecto.Repo.t(), integer(), module(), Keyword.t()) :: :ok | :already_up

Runs an up migration on the given repository.

Options

  • :log - the level to use for logging of migration instructions. Defaults to :info. Can be any of Logger.level/0 values or a boolean.
  • :log_sql - the level to use for logging of SQL instructions. Defaults to false. Can be any of Logger.level/0 values or a boolean.
  • :prefix - the prefix to run the migrations on
  • :strict_version_order - abort when applying a migration with old timestamp