§Learn

Learn the model. Then build.

Read them top to bottom the first time. Each one ends where the next begins, and by the last you will have a service that commits state and events together, handles those events, and can be deployed. Looking something up rather than learning it? The reference is the whole documentation tree.

01

Getting started

Start here. Follow one wallet change through the dual-write problem, model events, action staging, and what the executor commits.

02

The dual-write trap

Why writing to a database and to a broker separately creates silent drift, and why the event has to be stored with the state that caused it.

03

The outbox

How domain rows and event rows commit together, so the database holds both the state and the fact that produced it, and the ways to use the events afterwards.

04

Models and entities

Models emit events when they change; entities do not. Which to use, why both are immutable, and what the #[model] and #[entity] macros write for you.

05

Actions

Build the new state first, then let the executor commit domain rows and event rows in one transaction. Retries, errors, and what an action may not do.

06

Your first action

Build a wallet deposit end to end: the event, the model, the action, the call that runs it, and the event row you never wrote.

07

Blocking or async?

Two APIs over one engine: ekbatan::blocking and ekbatan::aio. How to pick, what is the same in both, and the one mistake to avoid.

08

Wiring a service

Every object a service needs, built from one config file and closed in the right order, with a separate connection pool for each kind of work.

09

Consuming events

Use committed events after the fact: handle them in the same service with the local event handler, or stream them out. Every path is at least once.

10

Adding a shard

Take a single-database service to two shards. Actions, queries and endpoints stay the same; the model's id carries its shard.

11

Sagas

Split a multi-step workflow into committed actions chained by events, with a compensation when a later step fails and nothing to roll back.

12

Going to production

Migrations at deploy, TLS, pools, shutdown, what to watch in traces and metrics, and what ekbatan does not do for you yet.