Skip to content
Deedboxlatest

Inline or async projections

This page helps you choose a run mode for each projection. Each projection has exactly one mode, set when you register it: Projection<T>(name, Run.Inline) or Projection<T>(name, Run.Async).

Inline Async
Runs In the append’s transaction, before the commit In the background runner, after the commit
A read after a command Sees the command’s effect Can be behind by the lag, often milliseconds
A failing handler Fails the append; the command sees the exception. In catch-up, it retries and stalls as an async one does Retries, then stalls the projection; appends go on
Cost to the append The handler’s time, inside the stream lock None
Reads events One append at a time In batches of up to BatchSize; a BatchProjection gets the whole batch
Guarantee Exactly once: the writes commit with the events Exactly once: the writes commit with the checkpoint
Several app instances Every instance runs it in its own appends One instance at a time runs it; the others wait
Rebuild The runner replays it, then switches it back to inline The runner replays it

Inline handlers run before the position counter update, so they do not hold the counter lock. They do keep the stream locked, and the transaction open, while they run.

  • A user must see their own write at once, such as an editor’s screen right after a decision.
  • A rule in the read model must hold together with the events, such as a unique name.
  • The handler is quick, and it writes only to the same database.
  • The read model can be a little behind: public pages, dashboards, reports, search.
  • The handler is slow, or it rebuilds often, or it reads many events at once.
  • A failure must not stop writes. A stalled async projection waits for a fix; an inline one fails every append that it handles.
  • The work leaves the database. That is a subscription, which is always async.

One stream can feed several projections, each in its own mode. A common set is an inline projection for the screens that edit, and an async one for public reads or a search index. Each projection keeps its own checkpoint, so each one rebuilds on its own.

A projection whose mode changes stalls until you rebuild it, because its stored progress belongs to the other mode (rebuild a projection). To change the mode without a gap in the read model, register the new mode under a new name, and switch the reads when it catches up. See replace a read model without downtime.

An instance that does not run an inline projection cannot apply it to its own appends. That happens during a rolling deploy, when old and new versions run side by side, or after a rollback. Deedbox handles both, with a heartbeat that each instance writes: what it runs, and what event types it can append.

  • A new inline projection starts in catch-up. The runner applies events by position, whichever instance appended them. The projection switches to inline only when no live instance can append its events without running it, so it waits until the old instances stop.

  • An instance that starts without a running inline projection, but can append its events, first moves that projection back to catch-up from the current head. The instances that run the projection then apply the old instance’s appends by position, and switch it back to inline when the old instances stop.

  • A projection that handles StreamDeleted or SubjectErased counts every instance that registers a stream type, because each such instance can append those events. In a store that several apps share, register the projection inline in each app, or run it async.

  • An instance that registers the projection in another run mode stalls it as mode_changed, as a mode change does. Rebuild it when the deploy is complete.

While a projection waits, deedbox status shows it as rebuilding with a small lag, and the log names the instances it waits for. An instance that stops cleanly leaves at once. One that crashes counts as live for 30 seconds after its last heartbeat, so the switch to inline waits that long.

A paused process, or one whose connection pool is exhausted, can miss its heartbeat for 30 seconds and then append again. Deedbox stops such an append from skipping an inline projection:

  • The switch to inline, called the cut-over, removes the heartbeat row of each instance that is not live. Log event 44 names them.
  • Every append checks its own heartbeat row in the statement that takes the position counter. An append without a row writes nothing.
  • Deedbox then joins the instance again, which moves the projection back to catch-up, and repeats an append in a transaction that it owns.
  • An append in your transaction, through UseTransaction or UseDbContext with an open transaction, fails with DBX038. Run the transaction again.

The check covers instances on 0.5.0 or later. An older instance is covered only while its heartbeat is live. A process that appends without a started host joins on its first write.

When appends arrive faster than the catch-up applies them, the runner forces the cut-over after 20 polls without a smaller gap. A forced cut-over holds the position counter for at most 2 seconds. If it does not reach the head in that time, it keeps what it applied and the projection stays in catch-up. After 5 such attempts in a row, the health check reports the projection as degraded, and log event 45 records it. Make the handlers faster, or run the projection async.