Skip to content
Cratis Cratis Cratis

Get Started

This guide takes you from an empty project to a running Chronicle client that appends and reads events.

Install

Section titled “Install”

Add the client to your mix.exs dependencies:

defp deps do
  [
    {:cratis_chronicle, "~> 0.1"}
  ]
end

Then fetch it:

Terminal window
mix deps.get

You also need a running Chronicle kernel. For local development, the kernel listens on localhost:35000 over TLS, serving an auto-generated self-signed certificate — the client trusts it out of the box, no configuration needed.

Define an event

Section titled “Define an event”
defmodule MyApp.Events.AccountOpened do
  use Chronicle.Events.EventType, id: "account-opened-v1"
  defstruct [:account_id, :owner_name, :initial_balance]
end

See Event Types for the full guide.

Start the client

Section titled “Start the client”

Add Chronicle.Client to your application’s supervision tree. With otp_app:, it discovers your event types, reactors, reducers, read models and seeders automatically:

defmodule MyApp.Application do
  use Application


  @impl true
  def start(_type, _args) do
    children = [
      {Chronicle.Client,
        connection_string: "chronicle://localhost:35000",
        event_store: "my-store",
        otp_app: :my_app}
    ]


    Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)
  end
end

The client connects in the background and recovers automatically if the connection drops. See Resilience and the Connection Lifecycle.

Append an event

Section titled “Append an event”
:ok =
  Chronicle.append("account-1", %MyApp.Events.AccountOpened{
    account_id: "account-1",
    owner_name: "Alice",
    initial_balance: 500
  })

Read it back

Section titled “Read it back”
{:ok, events} =
  Chronicle.EventSequences.EventLog.get_for_event_source("account-1")

Where to next

Section titled “Where to next”