Steward.Migrations (Steward v0.1.0)

Copy Markdown View Source

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

Summary

Functions

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

Returns the latest version of the resources table.

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

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

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

Migrates the resources table up to the given version.

Functions

add_index_to_oban_jobs(opts \\ [])

(since 0.1.0)
@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)
@spec current_version() :: pos_integer()

Returns the latest version of the resources table.

down(opts)

(since 0.1.0)
@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(opts \\ [])

(since 0.1.0)
@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(opts \\ [])

(since 0.1.0)
@spec remove_index_from_oban_jobs(keyword()) :: :ok

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

up(opts)

(since 0.1.0)
@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.