# `Sig.Migration`
[🔗](https://github.com/peeeuzin/sig/blob/v0.1.0/lib/sig/migration.ex#L1)

Creates and upgrades Sig's database tables from your application's own
migrations.

The migrations run on your application's repo, the same one Sig uses at
runtime (see `Sig.Repo`).

Sig's tables are versioned. Generate a migration in your app:

```bash
mix ecto.gen.migration add_sig_tables
```

and call `up/1` and `down/1` from it:

```elixir
defmodule MyApp.Repo.Migrations.AddSigTables do
  use Ecto.Migration

  def up, do: Sig.Migration.up(version: 1)

  # Passing version: 1 drops all of Sig's tables.
  def down, do: Sig.Migration.down(version: 1)
end
```

When a new version of Sig needs schema changes, its changelog will tell you
the new version number. Create another migration that upgrades to it, and
rolls back to the version you had before:

```elixir
defmodule MyApp.Repo.Migrations.UpgradeSigTablesToV2 do
  use Ecto.Migration

  def up, do: Sig.Migration.up(version: 2)
  def down, do: Sig.Migration.down(version: 2)
end
```

Migrations are idempotent: `up/1` only applies the versions that are not
yet in the database, and `down/1` only reverts the ones that are. The
current version is stored as a comment on the `workflows` table.

## Prefixes

Use the `:prefix` option to install the tables in a PostgreSQL schema other
than `public`. The schema is created if it does not exist:

```elixir
def up, do: Sig.Migration.up(version: 1, prefix: "sig")
def down, do: Sig.Migration.down(version: 1, prefix: "sig")
```

Then configure Sig to use the same prefix at runtime:

```elixir
config :sig, repo: MyApp.Repo, prefix: "sig"
```

# `current_version`

```elixir
@spec current_version() :: pos_integer()
```

Returns the latest migration version available in this release of Sig.

# `down`

```elixir
@spec down(keyword()) :: :ok
```

Reverts Sig's migrations down to, and including, `:version`.

`down(version: 1)` removes all of Sig's tables. `down(version: 2)` reverts
version 2 and every later one, leaving the database at version 1.

## Options

  * `:version` - the oldest version to revert. Defaults to `1`.
  * `:prefix` - the PostgreSQL schema holding the tables. Defaults to
    `"public"`.

# `migrated_version`

```elixir
@spec migrated_version(keyword() | map()) :: non_neg_integer()
```

Returns the version currently applied to the database, or `0` when Sig's
tables do not exist.

Must be called from within a migration.

## Options

  * `:prefix` - the PostgreSQL schema to inspect. Defaults to `"public"`.

# `up`

```elixir
@spec up(keyword()) :: :ok
```

Applies Sig's migrations up to `:version`.

## Options

  * `:version` - the version to migrate to. Defaults to the latest version
    (`1`). Pin it explicitly in your migrations, so that
    upgrading Sig never changes what an existing migration does.
  * `:prefix` - the PostgreSQL schema to create the tables in. Defaults to
    `"public"`.

---

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