CQRS Read Model Sync and Eventual Consistency
On this page
Learning Objective
Choose a synchronization mechanism between the write side and the read side, measure and monitor the resulting lag, and apply the established techniques for read-your-own-writes so that eventual consistency is invisible to the user who caused the change.
Concept Explanation
The moment read models live outside the write transaction, there is a window during which the two disagree, and the entire practical difficulty of CQRS lives in that window. It is not a defect to be eliminated; it is a property to be measured, bounded, monitored, and designed around at each user-facing surface.
Synchronization mechanisms sit on a spectrum. Updating the read model in the same transaction as the write gives no lag at all, but couples the write path to the read store's availability and latency and does not work across databases. Publishing an event after the commit is the naive approach and contains the dual-write bug that the next phase is devoted to: the write commits, the publish fails, and the read model never learns. The transactional outbox writes the event into the same database in the same transaction and a relay publishes it afterwards, which is the standard correct answer. Change data capture reads the database's own replication log and requires no application change at all. Polling for changed rows is the crude fallback, workable at small scale and unpleasant at large. The choice is essentially between coupling and lag, and most systems should accept a bounded lag.
What matters more than the mechanism is that lag is measured properly. The useful metric is not whether the projection process is alive but how far behind it is, expressed both in events and in time, per partition or per projection. Both numbers are needed: a backlog of 50,000 events may be seconds of work or hours depending on throughput, and a time lag of two minutes may be normal for a nightly rollup and an incident for an order status view. Every projection should carry a documented expected lag, an alert threshold, and a defined behavior for what the product does when the threshold is breached.
Read-your-own-writes is the specific consistency guarantee that users notice the absence of. A user who edits their profile and is immediately shown the old value concludes the save failed, and will save again, which is both a support ticket and sometimes a duplicate. Several techniques address it, and they are worth knowing as a set rather than a single answer. The write can return the new state directly so the client renders it without a read. The client can hold a version token from the write and require the read side to serve at least that version, waiting briefly or falling back if it cannot. The session can be pinned to read from the write side for a short period after a write. The interface can render optimistically from the submitted values. Or the specific screens that follow a write can read from the write side, accepting the cost on that narrow path only.
Finally, some lag is not lag at all but a stuck projection, and the two must be distinguished operationally. A projection failing on a poison event, deadlocking against another writer, or crash-looping will show a monotonically growing backlog that no amount of waiting fixes. Alerting should therefore cover the rate of change of lag as well as its absolute value, and every projection needs a dead letter path so that one unprocessable event does not halt the entire view. The product-level counterpart to all of this is choosing what the interface shows during the window: a provisional state with an honest label is nearly always better than a confidently displayed stale value.
| Technique for read-your-own-writes | How it works | Cost |
|---|---|---|
| Return the new state from the write | The command response carries what the client needs to render | The write path must assemble a view; not usable for other clients |
| Version token from write, waited for on read | Client passes the version; the read side waits until it has caught up | Requires version propagation end to end and a timeout policy |
| Sticky reads to the write side | For N seconds after a write, that session reads authoritative data | Load on the write store and session affinity to manage |
| Optimistic client rendering | The client shows what it submitted and reconciles later | Shows a state that may not have been accepted; needs rollback handling |
| Accept and label the staleness | The interface says processing rather than showing a stale value | A product decision, not a technical fix, but frequently the right one |
Worked Example: Lag Metrics and a Version-Aware Read
The read path below can be asked to guarantee it is at least as fresh as a specific write, and degrades honestly rather than silently serving stale data when it cannot.
// --- The write returns the position it committed at. ---
async function handlePlaceOrder(cmd) {
const { orderId, globalPosition } = await writeSide.place(cmd);
return { orderId, consistencyToken: globalPosition }; // client keeps this
}
// --- The read side can be asked to be at least as fresh as that position. ---
async function getOrderDetail(orderId, { minPosition = 0, waitMs = 250 } = {}) {
const deadline = Date.now() + waitMs;
while (true) {
const { position } = await db.checkpoints.get('rm_order_detail');
if (position >= minPosition) {
return db.one('SELECT * FROM rm_order_detail WHERE order_id = $1', [orderId]);
}
if (Date.now() >= deadline) {
// Do not silently serve stale data. Either read through to the write
// side for this one request, or tell the caller it is still catching up.
metrics.increment('read_model.wait_timeout', { model: 'rm_order_detail' });
return { ...(await writeSide.readOrderAuthoritative(orderId)), fresh: true };
}
await sleep(20);
}
}
// --- Lag measured in both dimensions, because one of them always lies. ---
setInterval(async () => {
const head = await store.headPosition();
for (const name of PROJECTIONS) {
const cp = await db.checkpoints.get(name);
metrics.gauge('projection.lag_events', head - cp.position, { projection: name });
metrics.gauge('projection.lag_seconds',
(Date.now() - cp.updated_at.getTime()) / 1000, { projection: name });
}
}, 5000);
// Alert on lag_seconds above the documented budget for each projection, and
// separately on lag_events increasing monotonically for N minutes, which is
// a stuck projection rather than a slow one and needs a different response.Real-World Examples
- Amazon S3 famously offered eventual consistency for overwrite PUTs and DELETEs for most of its history, and the read-after-write behavior was a permanent source of application bugs until AWS announced strong read-after-write consistency for all operations in December 2020. The long history of workarounds that developers built in the interim, retry loops, version tokens, waiting for propagation, is a catalogue of exactly the techniques this lesson describes, applied to a storage service rather than a read model.
- MongoDB's read concern and write concern settings, and its causal consistency sessions, expose the same tradeoff as an explicit API: a client can request that a read observe the effects of its own prior write within a session, which the driver implements using cluster time tokens passed between operations. It is the version token technique standardized into a database driver, and its existence in a mainstream database is a good indication that read-your-own-writes is a general problem rather than a CQRS-specific one.
Review Questions & Answers
A backlog measured in events says nothing about how long it will take to clear, since throughput varies enormously by event type and by projection: fifty thousand events might be six seconds of work or six hours. A lag measured in seconds says nothing about volume, and it misleads badly during quiet periods, because a projection that has processed nothing for ten minutes because nothing happened looks identical to one that has processed nothing because it is stuck. Together the two disambiguate: high events with low seconds is a burst being worked through, low events with high seconds is a quiet system, and both rising together is a projection falling behind.
It is attractive because it is simple, requires no version propagation or waiting, and solves the case that matters most: the user who just made the change seeing it reflected immediately. It is limited because it only helps that one client on that one response. Any other view the user navigates to, any other device, any other user looking at shared data, and any subsequent refresh all go to the read model and see the window again. It also pushes view assembly back into the write path, which is the coupling the separation was meant to remove, so it works best when the response is small and derived from what the command already had in hand.
A slow projection is making progress but not fast enough, so its checkpoint keeps advancing and its lag rises and falls with load; the response is to scale it, optimize its handlers, or increase its parallelism. A stuck projection is not advancing at all, usually because of a poison event, a deadlock, or a crash loop, so its lag grows monotonically and never recovers regardless of load; the response is to inspect the failing event, route it to a dead letter path, and resume. An alert on absolute lag alone will catch both eventually but cannot tell them apart, which sends responders down the wrong path, so the rate of change of the checkpoint should be an alert in its own right.
Because eliminating the window means putting the read model back inside the write transaction, which surrenders the availability, scalability, and store-choice benefits that the separation was adopted for, and it is often impossible anyway once the read store is a different technology. Telling the user that their order is being processed is truthful, costs nothing, sets an accurate expectation, and remains correct even when a consumer is backed up for minutes rather than milliseconds. Confidently displaying a stale value is the only genuinely bad option, because it is the one that makes the user believe something false and act on it.