Anvil.Schema.Migration behaviour (Anvil v0.1.1)

Forward-only migrations between schema versions.

Provides utilities for migrating labels from one schema version to another using transform callbacks.

Summary

Callbacks

transform(old_label, from_version, to_version)

Transform callback behaviour for schema migrations.

Functions

freeze_schema_version(schema_version_id)

Freezes a schema version when the first label is submitted.

migrate_labels(labels, from_version, to_version, transformer, opts \\ [])

Migrates labels from one schema version to another.

validate_against_schema(label_values, schema_version)

Validates that a label payload conforms to a schema version.

Callbacks

transform(old_label, from_version, to_version)

@callback transform(
  old_label :: map(),
  from_version :: integer(),
  to_version :: integer()
) ::
  {:ok, new_label :: map()} | {:error, :incompatible}

Transform callback behaviour for schema migrations.

Transform modules must implement forward/3 to convert labels from one version to another.

Functions

freeze_schema_version(schema_version_id)

@spec freeze_schema_version(binary()) ::
  {:ok, Anvil.Schema.SchemaVersion.t()} | {:error, term()}

Freezes a schema version when the first label is submitted.

This is typically called automatically via a database trigger or application hook.

migrate_labels(labels, from_version, to_version, transformer, opts \\ [])

@spec migrate_labels(
  [Anvil.Schema.Label.t()],
  non_neg_integer(),
  non_neg_integer(),
  module(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Migrates labels from one schema version to another.

Options

:batch_size - Number of labels to process per batch (default: 100)
:dry_run - If true, only validates transformations without creating new labels
:transformer - Module implementing transform/3 callback

Examples

iex> migrate_labels(labels, 1, 2, MyApp.Transforms.V1ToV2)
{:ok, %{migrated: 150, failed: 0}}

iex> migrate_labels(labels, 1, 2, MyApp.Transforms.V1ToV2, dry_run: true)
{:ok, %{valid: 150, invalid: 0}}

validate_against_schema(label_values, schema_version)

@spec validate_against_schema(map(), Anvil.Schema.SchemaVersion.t()) ::
  {:ok, map()} | {:error, [term()]}

Validates that a label payload conforms to a schema version.

Returns {:ok, payload} if valid, {:error, errors} if invalid.