AshClickhouse.Release (AshClickhouse v0.6.2)

Release task helpers for running AshClickhouse migrations in production without Mix installed.

Usage

Add a module like this to your project:

defmodule MyApp.Release do
  @app :my_app

  def migrate do
    load_app()

    for repo <- repos() do
      AshClickhouse.Release.migrate(repo, repos())
    end
  end

  def rollback(repo, version) do
    load_app()
    AshClickhouse.Release.rollback(repo, version, repos())
  end

  defp repos do
    Application.fetch_env!(@app, :ash_clickhouse_repos)
  end

  defp load_app do
    Application.load(@app)
  end
end

Then run it from your release:

bin/my_app eval "MyApp.Release.migrate"

Configuration

In your config:

config :my_app, :ash_clickhouse_repos, [MyApp.Repo]

Or configure per-repo:

config :my_app, MyApp.Repo,
  url: "http://clickhouse:8123",
  database: "my_app_prod"

Migration Flow

migrate/3 runs the generated migration files under priv/repo/migrations (overridable via the :migration_path option) through AshClickhouse.MigrationRunner. Each migration is tracked in a schema_migrations table, so already-applied files are skipped. Supports :dry_run, :create_database, and :migration_path options.

Rollback

rollback/3 rolls applied migrations back to a target version using the down/0 statements generated for each migration. For migration files that predate down/0 support, AshClickhouse.Migration.reverse_statement/1 derives inverse statements from change/0; statements that cannot be reversed are skipped with a warning.

Summary

Functions

create_database(repo, opts \\ [])

Creates the database for a repo if it doesn't exist.

find_resources(all_repos, opts)

Returns the AshClickhouse resources for the given repos.

migrate(repo, all_repos, opts \\ [])

Runs pending migrations for a repo.

rollback(repo, version, all_repos, opts \\ [])

Rolls back applied migrations to a specific version.

Functions

create_database(repo, opts \\ [])

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

Creates the database for a repo if it doesn't exist.

Examples

AshClickhouse.Release.create_database(MyApp.Repo)

find_resources(all_repos, opts)

@spec find_resources(
  [module()],
  keyword()
) :: [module()]

Returns the AshClickhouse resources for the given repos.

Uses the :resources option when provided, otherwise scans loaded applications for modules that export __ash_clickhouse__/1.

migrate(repo, all_repos, opts \\ [])

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

Runs pending migrations for a repo.

Options

:migration_path - directory containing *.exs migrations (default: the repo app's priv/repo/migrations)
:create_database - create the database before migrating (default true)
:dry_run - if true, only log statements without executing

Examples

AshClickhouse.Release.migrate(MyApp.Repo, [MyApp.Repo])

AshClickhouse.Release.migrate(MyApp.Repo, [MyApp.Repo], dry_run: true)

rollback(repo, version, all_repos, opts \\ [])

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

Rolls back applied migrations to a specific version.

version is the target version to roll back to — migrations applied after it are rolled back. Pass :all, nil, or 0 to roll back every applied migration. Each rolled-back migration executes its down/0 statements and is removed from the schema_migrations table.

Examples

AshClickhouse.Release.rollback(MyApp.Repo, 20240101000000, [MyApp.Repo])

AshClickhouse.Release.rollback(MyApp.Repo, :all, [MyApp.Repo])