@spec applied_versions(module()) :: [String.t()]

Returns the versions already applied for a repo, sorted.

@spec delete_applied(module(), String.t()) :: :ok | {:error, term()}

Removes a migration version from the tracking table (rollback).

@spec discover_migrations(String.t()) :: [%{version: String.t(), module: module()}]

Loads and sorts the migration files under a path.

Returns [%{version: String.t(), module: module()}] sorted by version, including only files that define at least one module. Modules whose version cannot be determined still appear (their version is the full filename).

@spec ensure_schema_migrations_table(module()) :: :ok | {:error, term()}

Creates the version-tracking table for a repo if it doesn't exist.

@spec migrate(
  module(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Runs pending migrations for a repo and returns a summary.

Creates the schema_migrations table if needed, skips versions already applied, executes change/0 for the rest, and records each applied version.

Options

• :migration_path — directory containing *.exs migrations (default "priv/repo/migrations")
• :dry_run — log statements without executing or recording
• :logger — emit output via Logger instead of Mix.shell() (for AshClickhouse.Release)

Returns {:ok, %{applied: [module()], skipped: [module()]}} or {:error, term()} — a {module(), term()} tuple when a specific migration failed, or a bare term() when the tracking table could not be created.

@spec record_applied(module(), String.t()) :: :ok | {:error, term()}

Records a migration version as applied.

@spec rollback(module(), String.t() | non_neg_integer() | :all | nil, keyword()) ::
  {:ok, map()} | {:error, term()}

Rolls back applied migrations for a repo down to (but not including) a target version.

Each rolled-back migration executes down/0 when exported, falling back to AshClickhouse.Migration.reverse_statement/1 over change/0 for files that predate down/0 support. Statements that cannot be reversed are skipped with a warning. :all (or nil/0) rolls back every applied migration.

Returns {:ok, %{rolled_back: [module()], skipped: [module()]}} or {:error, term()} — a {module(), term()} tuple when a specific migration failed, or a bare term() when the tracking table could not be created.

@spec run(
  module(),
  keyword()
) :: :ok

Runs pending migrations for a repo, Mix-style.

Equivalent to migrate/2 but prints through Mix.shell() and raises on failure, matching the behaviour of mix ash_clickhouse.migrate.

@spec schema_migrations_create_sql() :: String.t()

DDL used to create the version-tracking table.

@spec schema_migrations_table() :: String.t()

The name of the version-tracking table.