Getting Started

Copy Markdown View Source

This guide walks you through installing AshClickhouse and running your first resource against a ClickHouse database.

AshClickhouse is an Ash Framework data layer for ClickHouse. It implements the Ash.DataLayer behaviour using the clickhouse client.

Note: This library is under active development, unstable, and the API may change.

Prerequisites

  • Elixir ~> 1.17
  • A reachable ClickHouse server (default http://localhost:8123)
  • An Ash application (domain + resources)

Installation

Add the dependency to mix.exs:

def deps do
  [
    {:ash, "~> 3.0"},
    {:ash_clickhouse, "~> 0.2.0"}
  ]
end

Then fetch it:

mix deps.get

1. Configure a Repo

A Repo holds the connection configuration for a ClickHouse database.

# lib/my_app/repo.ex
defmodule MyApp.Repo do
  use AshClickhouse.Repo, otp_app: :my_app
end
# config/config.exs
config :my_app, MyApp.Repo,
  url: "http://localhost:8123",
  database: "my_app_dev"

2. Add the Repo to your supervision tree

# lib/my_app/application.ex
children = [MyApp.Repo, ...]

3. Define a resource

defmodule MyApp.User do
  use Ash.Resource,
    data_layer: AshClickhouse.DataLayer,
    domain: MyApp.Domain

  import AshClickhouse.DataLayer.Dsl.Macros

  clickhouse do
    table "users"
    repo MyApp.Repo
    engine "MergeTree()"
    order_by "id"
  end

  attributes do
    uuid_primary_key :id
    attribute :name, :string
    attribute :email, :string
  end

  actions do
    defaults [:create, :read, :update, :destroy]
  end
end

Register it on a domain:

defmodule MyApp.Domain do
  use Ash.Domain

  resources do
    resource MyApp.User
  end
end

4. Create the database and tables

mix ash_clickhouse.setup    # CREATE DATABASE IF NOT EXISTS
mix ash_clickhouse.migrate  # CREATE TABLE IF NOT EXISTS ...

5. Use it

{:ok, user} = Ash.create(MyApp.User, %{name: "John", email: "john@example.com"})
users = Ash.read!(MyApp.User)

Next steps