The Inner Workings of the CQRS Pattern

CQRS works by routing state-changing commands and data-reading queries to two independently designed models: the write model validates a command and appends the resulting state change, and a separate projector asynchronously consumes those changes to rebuild a read-optimized view — so the read side trails the write side by a small, bounded lag rather than sharing its tables.

The mechanism, precisely

The name only tells you what is separated (Command Responsibility from Query Responsibility). The engineering payload is how the two halves talk. They do not share a schema and they do not call each other synchronously. Instead:

• The command side owns a normalized, consistency-enforcing model. A command handler loads the current state, checks invariants, and commits a change. That commit produces a durable record of what changed — a domain event such as UserAddressUpdated.
• A projector (a background subscriber) reads that event and writes a denormalized row into the read side — a table or document shaped exactly for one screen, so a query is a single indexed lookup with no joins.

The critical, often-fumbled point: the read model is updated after the write commits, on a separate thread or process. Between the two there is a window where the read side is stale. CQRS gives you eventual consistency, not synchronized state. Any design that claims the two sides are "always in sync" has quietly reintroduced a distributed transaction and thrown away the scalability CQRS exists to buy.

Event Sourcing is optional — do not conflate it

A common confusion (and the one this page previously made) is to say "Event Sourcing keeps the two sides in sync." Two independent decisions are hiding in that sentence:

• How the write side stores state. You can store the current row in a normal table (state-oriented) or store the full append-only log of events and fold them to reconstruct state (event sourcing). CQRS does not require the second.
• How the read side learns about changes. This is the projection — a subscriber that transforms change notifications into read rows.

Event sourcing is one convenient source of the change stream a projector consumes, but you can equally feed the projector from a transactional outbox, change-data-capture on the write DB, or an explicitly published integration event. Sync is the job of the projection mechanism; event sourcing is merely one storage choice underneath it.

Worked trace: user changes their shipping address

User u-42 currently has address "12 Old St". They submit a new one. Follow the two paths and the lag between them.

A query issued at t=20 would have returned the old address even though the write already committed at t=3. That 31 ms gap is the eventual-consistency window. Note the v:7 version stamp — the projector uses it to reject or reorder out-of-order events, and a UI can compare the version it wrote against the version it reads back to detect "my change hasn't landed yet."

A correct minimal projector

The projector is where correctness lives or dies. The naive version below looks fine and is subtly broken.

// NAIVE — do not ship
function onAddressChanged(e) {
  readDb.upsert('address_view', { userId: e.user, address: e.line, zip: e.zip });
}

Why the naive version is wrong: message buses deliver at least once and can deliver out of order. If v:7 arrives after a retried v:6, the projector overwrites the newer address with the older one. The read view silently regresses and no error is ever logged.

// CORRECT — version-guarded, idempotent upsert
function onAddressChanged(e) {
  // only apply if this event is newer than what we already stored
  readDb.exec(
    `INSERT INTO address_view(user_id, address, zip, version)
     VALUES ($1, $2, $3, $4)
     ON CONFLICT (user_id) DO UPDATE
       SET address = EXCLUDED.address,
           zip     = EXCLUDED.zip,
           version = EXCLUDED.version
     WHERE address_view.version < EXCLUDED.version`,
    [e.user, e.line, e.zip, e.version]
  );
}

The WHERE version < EXCLUDED.version clause makes the write both idempotent (re-delivering v:7 is a no-op) and order-tolerant (a late v:6 loses to the stored v:7). Every projector needs a monotonic version or sequence per aggregate for exactly this reason.

Pitfalls

• Reading your own write. A user saves their address, the UI immediately re-fetches, and sees the old value because the projection hasn't caught up. Fix by having the command return the new state (or its version), and either render optimistically or poll the read side until read.version >= written.version.
• Silent projector lag. If the projector crashes or falls behind, queries keep succeeding — they just return increasingly stale data with no error. You must monitor projection lag (newest write version minus newest projected version) and alarm on it; it is the health metric CQRS quietly demands.
• Non-idempotent projectors. As shown above, at-least-once + out-of-order delivery corrupts the read model unless every apply is version-guarded and idempotent.
• Rebuild cost. When you change a read view's shape, you must re-run the projector over history. Without event sourcing or a replayable log you may have no way to rebuild — plan the change stream to be replayable from day one.
• Dual-write trap. Writing to the DB and publishing the event as two separate operations can lose the event on a crash between them. Use a transactional outbox or CDC so the event is committed atomically with the state change.
• Applying it everywhere. CQRS per aggregate is fine; CQRS as a blanket architecture doubles your models, storage, and failure modes for CRUD that never needed it.

When to use it — and when not to

Reach for CQRS when concrete signals appear: reads and writes scale independently (e.g. 100:1 read/write ratio) and you want to scale or cache the read side without touching write consistency; the write model enforces rich invariants but queries want wildly different denormalized shapes; several read views (search index, dashboard, mobile summary) must be fed from one source of truth; or you already emit domain events and a projection is nearly free.

Alternatives and the trade you are making:

• vs. a single shared model (plain CRUD + an ORM). CRUD gives you read-your-writes for free, one schema, trivial mental model. CQRS costs you a second model, a projector, eventual-consistency handling in the UI, and lag monitoring. Choose CRUD when the read shape is close to the write shape and load is modest — most admin tools and internal apps. Choose CQRS when the read/write shapes or scaling needs genuinely diverge.
• vs. read replicas / materialized views. A DB read replica also offloads reads and is eventually consistent, but it mirrors the write schema — you still query the normalized shape and pay the joins. CQRS lets the read model be a different shape optimized per query. Prefer a read replica when you only need read scale, not a different shape; prefer CQRS when the query shape itself is the bottleneck.
• vs. caching in front of CRUD. A cache is cheaper and needs no projector, but invalidation is its own hard problem and it doesn't give you multiple bespoke views. Prefer a cache for hot-key read amplification on an otherwise-fine model; prefer CQRS when you need durable, queryable, multiply-shaped read models.

Crisp rule: choose CQRS when the write side's job (enforce invariants) and the read side's job (serve many shapes fast) have pulled far enough apart that one model serves both badly — and you can tolerate a bounded staleness window. Prefer a single CRUD model otherwise.

Takeaways

• Commands validate and change state; queries read a separately-shaped, denormalized view — the two models never share a schema.
• The bridge is an asynchronous projection, so consistency is eventual with bounded lag, never "always in sync." Design the UI and monitoring around that window.
• Event sourcing is an optional storage choice for the write side; the projection, not event sourcing, is what synchronizes the read model — don't conflate them.
• Every projector must be idempotent and version-ordered, and projection lag must be monitored, or the read model corrupts or rots silently.

Re-authored and deepened for this guide. Sources: Greg Young, "CQRS Documents" (2010) and his talks distinguishing CQRS from event sourcing; Martin Fowler, "CQRS" (martinfowler.com); Microsoft, "CQRS pattern" and "Transactional Outbox" in the Azure Architecture Center; Chris Richardson, Microservices Patterns (Manning, 2018), chapters on CQRS and event-driven data management; Vaughn Vernon, Implementing Domain-Driven Design. The original page's claim that Event Sourcing keeps the sides "always in sync" was corrected to eventual consistency via an asynchronous projection.