Ithibati.Migration (Ithibati v0.2.0)

Creates or removes Ithibati's versioned database schema from an application migration.

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

  def up, do: Ithibati.Migration.up(version: 1)
  def down, do: Ithibati.Migration.down(version: 1)
end

Create the account table and identifier column first. If invitations are configured, their table must also exist when up/1 validates the application tables.

Options

:version — required target schema version supported by the installed release.
:from — existing version, exclusive; defaults to 0. A later upgrade uses a new application migration with the original version as :from.

Keep versions pinned in applied migrations. current_version/0 reports the newest version this release supports. down/1 removes the changes covered by the matching range.

Table names and account foreign-key types come from the configured schemas. up/1 verifies required columns, key types and unique indexes before creating its tables. The application continues to own its account and invitation tables.

Getting started shows initial setup; Configuration and schemas covers index ownership and upgrades.

Summary

Functions

current_version()

The newest schema version this release knows.

down(opts)

Removes what the matching up/1 built.

invitation_columns(opts)

Adds the required invitation columns inside an application's create table block.

invitation_index(opts)

Creates or verifies the invitation table's unique token_hash index.

up(opts)

Builds Ithibati's tables. See the module documentation for options.

Functions

current_version()

The newest schema version this release knows.

down(opts)

Removes what the matching up/1 built.

invitation_columns(opts)

Adds the required invitation columns inside an application's create table block.

The configured invitation schema supplies the identifier field name. version: is required and must name a supported schema version.

create table(:invitations) do
  Ithibati.Migration.invitation_columns(version: 1)

  add :role, :string
  timestamps(type: :utc_datetime_usec)
end

Declare field :role, Ecto.Enum, values: [:admin, :author] in the application's Ecto schema when using that string column as an enum.

The helper adds exactly four columns:

the identifier, :string by default, null: false
:token_hash, :binary, null: false
:expires_at, :utc_datetime_usec, null: false
:accepted_at, :utc_datetime_usec, nullable for pending invitations

The schema's virtual :token is not stored. Add application-specific fields and timestamps separately. :type overrides only the identifier's database type and is passed to Ecto.Migration.add/3. For type: :citext, install the PostgreSQL extension first. See the invitation guide for setup and type choices. up/1 also validates existing invitation tables.

This function does not create the token index; use invitation_index/1 when adding invitations after Ithibati's initial migration.

invitation_index(opts)

Creates or verifies the invitation table's unique token_hash index.

Use this when adding invitations after Ithibati's initial migration has already run. version: is required, and the configured invitation table must exist.

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

  def change do
    create table(:invitations) do
      Ithibati.Migration.invitation_columns(version: 1)
      timestamps(type: :utc_datetime_usec)
    end

    Ithibati.Migration.invitation_index(version: 1)
  end
end

up/1 also maintains this index. Both paths create it only when absent and verify its uniqueness. If the schema uses unique_index: false, the application must create the index; this call checks it without creating it.

up(opts)

Builds Ithibati's tables. See the module documentation for options.