# `Steward.Migrations`
[🔗](https://github.com/marko-ding/steward/blob/v0.1.0/lib/steward/migrations.ex#L3)

Migrations for Steward's database tables.

Steward's resources table is versioned: `up/1` migrates it to the given version, `down/1`
rolls it back. The version is stored as a comment on the table, so `up/1` only applies
versions newer than the table's. The version is required, so that a migration does the same
whichever Steward release runs it. Generate a migration in your application:

    defmodule MyApp.Repo.Migrations.AddSteward do
      use Ecto.Migration

      def up, do: Steward.Migrations.up(version: 1)
      def down, do: Steward.Migrations.down(version: 1)
    end

Steward additionally benefits from an index on Oban's `oban_jobs` table for performant lookups
of jobs it manages. Add it with `add_index_to_oban_jobs/1` and `remove_index_from_oban_jobs/1`
from another migration, creating it concurrently on a large table:

    defmodule MyApp.Repo.Migrations.AddStewardIndexToObanJobs do
      use Ecto.Migration

      @disable_ddl_transaction true
      @disable_migration_lock true

      def up, do: Steward.Migrations.add_index_to_oban_jobs(concurrently: true)
      def down, do: Steward.Migrations.remove_index_from_oban_jobs(concurrently: true)
    end

# `add_index_to_oban_jobs`
*since 0.1.0* 

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

Adds the index Steward needs to look up a resource's jobs to Oban's `oban_jobs` table.

Oban's own GIN index on `meta` only serves `@>` containment queries and is too slow for
Steward's lookups. Must run after Oban's migration created the table.

## Options

  * `:prefix` - prefix of the `oban_jobs` table, defaults to the migration's prefix
  * `:concurrently` - creates the index concurrently (requires `@disable_ddl_transaction` and
    `@disable_migration_lock`)

# `current_version`
*since 0.1.0* 

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

Returns the latest version of the resources table.

# `down`
*since 0.1.0* 

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

Rolls the resources table back to before the given version. Version 1 drops the table.

## Options

  * `:version` - the earliest version to roll back, between 1 and `current_version/0`.
    Required.
  * `:table` - table name, defaults to `"steward_resources"`
  * `:prefix` - prefix, defaults to `"public"`

# `migrated_version`
*since 0.1.0* 

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

Returns the version the resources table is migrated to, or `0` if it doesn't exist.

## Options

  * `:repo` - the repo to query, defaults to the migration's repo
  * `:table` - table name, defaults to `"steward_resources"`
  * `:prefix` - prefix, defaults to `"public"`

# `remove_index_from_oban_jobs`
*since 0.1.0* 

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

Removes the index added by `add_index_to_oban_jobs/1`. Accepts the same options.

# `up`
*since 0.1.0* 

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

Migrates the resources table up to the given version.

The table and prefix must match the `:table` and `:prefix` options of `Steward.Config`.

## Options

  * `:version` - the version to migrate to, between 1 and `current_version/0`. Required.
  * `:table` - table name, defaults to `"steward_resources"`
  * `:prefix` - prefix, defaults to `"public"`
  * `:index_meta` - whether to create a GIN index on the `:meta` column, which speeds up
    `Steward.Controller.list_resources_by_meta/2`. Disable it if you don't look up resources
    by meta, to save its storage and write overhead. Only applies when the table is created.
    Defaults to `true`.

---

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