Ithibati.Migration (Ithibati v0.6.2)

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: 2)
  def down, do: Ithibati.Migration.down(version: 2)
end

Use explicit up/0 and down/0, not change/0: catalogue checks flush queued DDL and cannot be reversed automatically by Ecto.

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.

Version 3 adds the operator-code digest table used by protected first claims. 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.

invitation_inviter_column(opts)

Adds the inviter column to an invitation table that was created before version 4.

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:

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.

invitation_inviter_column(opts)

Adds the inviter column to an invitation table that was created before version 4.

For an application that turned invitations on earlier. A table created with invitation_columns(version: 4) already has it. The column type follows users_key_type, which is why this exists rather than a line in the guide: an application that guessed :binary_id against a :id account table would only find out at the first invitation.

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

  def change do
    alter table(:invitations) do
      Ithibati.Migration.invitation_inviter_column(version: 4)
    end
  end
end

Nullable, and Ithibati writes no foreign key: rows written before the column existed have no inviter, and whether one is enforced is the application's to decide about its own table.

up(opts)

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