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.