# `PhoenixMountable.Migrations`
[🔗](https://github.com/hattoriai/phoenix_mountable/blob/v0.2.1/lib/phoenix_mountable/migrations.ex#L41)

Versioned migrations for a mountable library's tables in the host's database.

The library writes the versions; the host owns one line per upgrade:

    # in the library
    defmodule MyLib.Migrations do
      use PhoenixMountable.Migrations,
        otp_app: :my_lib,
        versions: [MyLib.Migrations.V1, MyLib.Migrations.V2, MyLib.Migrations.V3]
    end

    # in the host, generated by `mix phoenix_mountable.gen.migration MyLib.Migrations`
    defmodule MyApp.Repo.Migrations.AddMyLib do
      use Ecto.Migration
      def up, do: MyLib.Migrations.up(version: 3)
      def down, do: MyLib.Migrations.down(to: 0)
    end

Each version is a `PhoenixMountable.Migration` module. See the Migrations
guide for the reasoning behind each rule.

## `use` options

  * `:otp_app` (required) — the library's application.
  * `:versions` (required) — the version modules in order, version 1 first;
    or a map of adapter (`:postgres`, `:mysql`, `:sqlite`) to such a list,
    when the SQL differs too much to share modules.
  * `:library` — the name the version is tracked under. Defaults to the
    `:otp_app`. Never change it after a release.
  * `:baseline` — a `PhoenixMountable.Migration` with `baseline: n`
    creating the whole schema at version `n`, run on fresh installs instead
    of versions 1 to `n`. `PhoenixMountable.Migrations.Test` checks that both
    paths give the same schema.
  * `:compatible_with` — the oldest schema version the library's current
    code runs against. Defaults to the latest version. Between it and the
    latest, the app works and logs that an upgrade is pending; below it,
    the library refuses to run and names the command that fixes it.
  * `:legacy` — a module with `detect(ctx) :: non_neg_integer | nil`,
    returning the version of a database migrated before the library used
    PhoenixMountable (from a table comment, or from the columns present).
  * `:install_options` — options the host chooses once, at install time,
    that later versions need, as a NimbleOptions schema. A `:primary_key`
    option (`type: {:in, [:id, :binary_id]}`) defaults to the repo's
    `:migration_primary_key` type.
  * `:lock_timeout` — how long a version waits for a table lock before
    failing, instead of queueing behind long transactions and blocking the
    app: `"5s"` by default on Postgres and MySQL; `false` to disable.
  * `:gen_task` — the Mix task hosts run to generate migrations, for
    messages. Defaults to `"phoenix_mountable.gen.migration <module>"`.

## Functions

The module gets `up/1`, `down/1`, `migrated_version/1`, `latest_version/0`,
`status/1`, `check/1`, `verify/1` and `run_backfills/1`.

`up/1` options: `:version` (defaults to the latest, but hosts should pin
it), `:prefix`, `:backfills` (`:inline` or `:deferred`, overriding each
backfill's default) and the library's install options. `down/1` takes `:to`
(the version to roll back to, default `0`) and `:prefix`.

# `no_transaction?`

```elixir
@spec no_transaction?(module(), atom(), non_neg_integer(), non_neg_integer()) ::
  boolean()
```

Whether running versions `from + 1` to `to` needs the host migration to
disable its DDL transaction and migration lock.

# `versions`

```elixir
@spec versions(module(), atom()) :: [module()]
```

The version modules of a migrations module for an adapter.

---

*Consult [api-reference.md](api-reference.md) for complete listing*