Replace a read model without downtime
This guide shows you how to change a read model’s tables or shape while the old read model keeps serving reads. An in-place rebuild is simpler, but the read model is empty or partial until it finishes. For a large read model, that gap can be long.
The method is often called a blue/green rebuild: the old projection is blue, the new one is green. Deedbox builds it from the events, so the new read model gets every change since the first event.
-
Write the new projection as a new class that writes to new tables, such as
cart_summary_v2. Create the tables. -
Register it under a new name, next to the old one. Keep the old one as it is: it serves reads until the switch.
services.AddDeedbox(es => es.UsePostgres(connStr).Stream<Cart>(s => s.Events<ItemAdded, CheckedOut>()).Projection<CartSummaryProjection>("cart_summary", Run.Inline) // serves reads until the switch.Projection<CartSummaryV2Projection>("cart_summary_v2", Run.Async)); // fills the new tables from the first eventThe new one can be async or inline. A new inline projection stays in catch-up until no instance of the old version is live, so it misses nothing during a rolling deploy; see inline or async projections.
-
Deploy. The runner applies every earlier event to the new projection, then keeps it current. Watch it with
deedbox status, or from code:var status = await admin.GetStatusAsync();var next = status.Consumers.Single(c => c.Name == "cart_summary_v2");var ready = next.Status == ConsumerState.Running && next.Lag == 0; // caught up with every eventThe health check stays healthy while the new projection catches up. If an inline projection cannot finish its catch-up, the check reports it as degraded; see rebuild a projection.
-
When the new projection is caught up, switch the reads to the new tables. Use a configuration flag or a deploy. Both read models stay current until the next step, so you can switch back.
-
Remove the old projection’s registration, and deploy.
-
Retire the old projection, then drop its tables:
Terminal window deedbox retire cart_summary --provider postgres --connection "$DEEDBOX_CONNECTION"Or from code, with
IEventStoreAdmin.RetireAsync("cart_summary"). Retiring refuses with DBX035 while a live instance still registers the name, and names those instances. A retired projection keeps its checkpoint, asretired. If an old version with the name starts again, as in a rollback, the projection stays idle and the health check reports it as degraded.RebuildAsync("cart_summary")brings it back.
Change the mode later
Section titled “Change the mode later”A projection’s mode is part of its checkpoint, and a projection whose mode changes stalls until it is rebuilt. To change the mode of the new read model without a gap in its reads, repeat this guide with a third name in the other mode.