Ecto SQL v3.1.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.
Ensures the repo is started to perform migration operations.
Link to this section Functions
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 ofLogger.level/0
values or a boolean.:log_sql
- the level to use for logging of SQL instructions. Defaults tofalse
. Can be any ofLogger.level/0
values or a boolean.:prefix
- the prefix to run the migrations on:dynamic_repo
- the name of the Repo supervisor process. SeeEcto.Repo.put_dynamic_repo/1
.
migrated_versions(repo, opts \\ [])
View Source
migrated_versions(Ecto.Repo.t(), Keyword.t()) :: [integer()]
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:dynamic_repo
- the name of the Repo supervisor process. SeeEcto.Repo.put_dynamic_repo/1
.
migrations(repo)
View Source
migrations(Ecto.Repo.t()) :: [
{:up | :down, id :: integer(), name :: String.t()}
]
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))
migrations(repo, directory)
View Source
migrations(Ecto.Repo.t(), String.t()) :: [
{:up | :down, id :: integer(), name :: String.t()}
]
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.
migrations_path(repo)
View Source
migrations_path(Ecto.Repo.t()) :: String.t()
migrations_path(Ecto.Repo.t()) :: String.t()
Gets the migrations path from a repository.
run(repo, direction, opts)
View Source
run(Ecto.Repo.t(), atom(), Keyword.t()) :: [integer()]
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.
run(repo, migration_source, direction, opts) View Source
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 iftrue
: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 ofLogger.level/0
values or a boolean.:prefix
- the prefix to run the migrations on
up(repo, version, module, opts \\ [])
View Source
up(Ecto.Repo.t(), integer(), module(), Keyword.t()) :: :ok | :already_up
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 ofLogger.level/0
values or a boolean.:log_sql
- the level to use for logging of SQL instructions. Defaults tofalse
. Can be any ofLogger.level/0
values or a boolean.:prefix
- the prefix to run the migrations on:dynamic_repo
- the name of the Repo supervisor process. SeeEcto.Repo.put_dynamic_repo/1
.:strict_version_order
- abort when applying a migration with old timestamp
with_repo(repo, fun, opts \\ []) View Source
Ensures the repo is started to perform migration operations.
All of the application required to run the repo will be started
before hand with chosen mode. If the repo has not yet been started,
it is manually started, with a :pool_size
of 2, before the given
function is executed, and the repo is then terminated. If the repo
was already started, then the function is directly executed, without
terminating the repo afterwards.
Although this function was designed to start repositories for running migrations, it can be used by any code, Mix task, or release tooling that needs to briefly start a repository to perform a certain operation and then terminate.
The repo may also configure a :start_apps_before_migration
option
which is a list of applications to be started before the migration
runs.
It returns {:ok, fun_return, apps}
, with all apps that have been
started, or {:error, term}
.
Options
:pool_size
- The pool size to start the repo for migrations. Defaults to 2.:mode
- The mode to start all applications. Defaults to:permanent
.
Examples
{:ok, _, _} =
Ecto.Migrator.with_repo(repo, fn repo ->
Ecto.Migrator.run(repo, :up, all: true)
end)