Chronicle Elixir client
cratis_chronicle is the Elixir client for Chronicle. You declare events, read models, reactors, reducers and seeders as modules with use macros, start Chronicle.Client in your supervision tree, and append and query with plain functions that return :ok, {:ok, value} or {:error, reason}.
Shared Chronicle concepts and workflows live in the main Chronicle docs and show an Elixir tab where the code differs by client. This section covers what is specific to Elixir: Mix setup, supervision, connections, process-scoped context, and Elixir-only APIs.
New here? Start with Get started. It takes you from mix new to a projected read model in a few minutes.
Requirements and compatibility
Section titled “Requirements and compatibility”| Requirement | Details |
|---|---|
| Package | cratis_chronicle on Hex. |
| Elixir | 1.18 or later. CI uses Elixir 1.19.5 on Erlang/OTP 28.5. |
| Dependencies | grpc ~> 1.0, Mint 1.11 or later, opentelemetry_api ~> 1.4, and cratis_chronicle_contracts ~> 19.56. |
| Kernel | A kernel whose gRPC contracts match the cratis_chronicle_contracts version in your mix.lock. A mismatch returns {:error, {:incompatible_server, ...}}; see Get started. |
| API reference | HexDocs |
Known limitations
Section titled “Known limitations”See Limits and gaps for the kernel limits, the consistency guarantees and what the Elixir client does not do yet.
- The client doesn’t validate the kernel’s TLS certificate unless you set
skipTlsValidation=false. See Connection strings. - Version 3.5.0 had defects in read model mappings, reducer registration, constraint registration, seeding, read model paging, and sequence number lookups. Upgrade to 3.5.1 or later.
Shared Chronicle topics
Section titled “Shared Chronicle topics”- Get started
- Events and event logs
- Appending events
- Read models
- Projections
- Reactors
- Reducers
- Constraints
- Event seeding
- Compliance
- Transactions and unit of work
- Event evolution
Elixir-specific pages
Section titled “Elixir-specific pages”- Get started: install the client, connect to a development kernel, append an event and read a read model
- Connections: connection strings, credentials, TLS, and how the client recovers from dropped connections
- Context management: process-scoped correlation ids, identities, and causation chains
- Concepts: strongly typed values and PII classification with
Chronicle.Concept - Seeding: seeders and when seed data is appended
- Sinks: choosing where read models are stored, and running several clients
- Event store discovery: listing event stores and namespaces
- Event store subscriptions: importing events between event stores
- Jobs: inspecting and controlling Chronicle jobs
- Webhooks: registering webhooks from Elixir
- External services: registering HTTP and database external services
- Failed partitions: inspecting observers whose partitions have failed
- Observers: listing observers and removing one whose declaring code is gone
- Captures: declaring captures that turn external input into events
- Dynamic Consistency Boundary: decision reads that guard a unit of work against concurrent appends
- Behavior patterns: asking what a scope usually does at a given moment
- Discovery and identity drift: the discovery report, identity drift policies and
mix chronicle.discover - Observability: OpenTelemetry spans,
:telemetryevents and trace propagation - Testing: the in-memory kernel, assertions and isolated integration helpers