- Book: Event-Driven Architecture Pocket Guide
- My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
- Me: xgabriel.com | GitHub
You opened a pull request that splits your Order entity into OrderWriteModel and OrderReadModel. The reviewer asks why. You answer: "CQRS." The reviewer asks why again, and this time the answer takes 40 minutes, three Miro diagrams, and an apology to the standup that started without you.
You have probably seen the version that goes wrong. A team ships CQRS into a 12-table CRUD app because someone read about it. Eighteen months later they have two databases that disagree, a projection rebuild script nobody trusts, and a "consistency dashboard" with three orange tiles that have been orange since launch. The system works. It works the same way the pre-CQRS version worked, except now there are two of everything.
Greg Young (who coined the term in 2010) was clear from the start: CQRS is a pattern, not an architecture. Martin Fowler puts it more bluntly on his bliki: "for most systems CQRS adds risky complexity." Chris Richardson lists CQRS under the data-management patterns on microservices.io precisely because the problem it solves only appears once you have multiple services and multiple databases.
Most apps are not those apps. Read and write in the same model. Use a normal repository. Ship.
Here are the four cases where CQRS actually earns the cost.
Case 1: read scale dwarfs write scale by 2+ orders of magnitude
The textbook scenario. Picture a pricing service that writes 50 updates per minute and serves 800,000 reads per minute, or a product catalog that edits 200 items a day and is queried 10 million times. Those are illustrative thresholds, not measured benchmarks. The shape is asymmetric, and you cannot index your way out of it because the indexes themselves contend with writes.
CQRS lets you scale the read side independently. The write model lives behind your normal transactional database, sized for writes. The read model is a denormalized projection: Redis, Elasticsearch, or a separate Postgres replica with materialized views. Size it for reads, and replicate it wherever your traffic lives.
# Write side — small, normalized, transactional.
class PricingCommandHandler:
def __init__(self, db, events):
self.db = db
self.events = events
def update_price(self, sku: str, price: Decimal) -> None:
with self.db.transaction() as tx:
tx.execute(
"UPDATE prices SET amount = %s WHERE sku = %s",
(price, sku),
)
self.events.publish(
PriceUpdated(sku=sku, amount=price, ts=now()),
)
# Read side — denormalized projection, eventually consistent.
class PriceProjection:
def __init__(self, redis):
self.redis = redis
def on_price_updated(self, e: PriceUpdated) -> None:
self.redis.set(
f"price:{e.sku}",
json.dumps({"amount": str(e.amount), "ts": e.ts}),
)
def get(self, sku: str) -> dict | None:
raw = self.redis.get(f"price:{sku}")
return json.loads(raw) if raw else None
The write side stays small and correct. The read side stays fast and disposable. If your read traffic is 10× write traffic, do not do this. Add a replica and an index. My rule of thumb is two orders of magnitude. Treat that as an illustrative threshold, not a benchmark, and only at that point does the projection earn its operational tax.
Case 2: reads have different consistency requirements
A trading platform shows you your portfolio balance on the dashboard and the same balance on the trade-confirmation screen. The dashboard can be 200ms stale. The confirmation screen cannot — it has to reflect the order you just placed.
A single model forces you to pick one consistency level for both. Either the dashboard reads through the slow path that confirmation needs, or the confirmation screen reads through the fast path that the dashboard tolerates and gets a stale balance at the worst possible moment.
CQRS lets you serve each read with its own model. Strong-consistency reads hit the write store directly (read-your-writes within the aggregate). Eventually-consistent reads hit a projection optimized for the query — pre-joined, pre-aggregated, pre-paginated.
class PortfolioReads:
def __init__(self, write_db, read_store):
self.write_db = write_db # source of truth
self.read_store = read_store # projection
def balance_for_confirmation(self, account_id: str) -> Decimal:
# Strong: read through the write model.
row = self.write_db.fetchone(
"SELECT balance FROM accounts WHERE id = %s",
(account_id,),
)
return row["balance"]
def balance_for_dashboard(self, account_id: str) -> Decimal:
# Eventual: pre-aggregated projection, fast.
return self.read_store.get_balance(account_id)
The two methods are honest about what they offer. The dashboard does not pay for strong consistency it does not need. The confirmation screen does not get fooled by a stale projection.
Case 3: queries cross aggregate or service boundaries
Once you split a system into services with database-per-service, joining across services becomes a runtime problem instead of a JOIN. "Show me all orders by customers in the EU placed in the last hour" now spans three services, and there is no SQL planner to help you.
You can answer this with API composition (call all three services, join in the app) or with CQRS — a read-side projection that subscribes to the events from each service and maintains a denormalized view shaped exactly for the query.
# Subscribes to OrderPlaced, CustomerUpdated, RegionAssigned.
class EuOrdersProjection:
def __init__(self, read_db):
self.read_db = read_db
def on_order_placed(self, e: OrderPlaced) -> None:
cust = self.read_db.get_customer(e.customer_id)
if not cust or cust["region"] != "EU":
return
self.read_db.insert_order_view({
"order_id": e.order_id,
"customer_id": e.customer_id,
"region": cust["region"],
"amount": e.amount,
"placed_at": e.ts,
})
def on_customer_region_changed(self, e: RegionChanged) -> None:
self.read_db.update_orders_for_customer(
e.customer_id, region=e.region,
)
This is the case where CQRS pays for itself fastest in microservice systems. The projection is a small focused service. The query goes from "fan out three calls and merge in app code" to "one indexed read." API composition stops scaling somewhere around a handful of participating services and a few hundred queries per second. Take that as an illustrative ceiling, not a hard one; your mileage will depend on payload size and tail latency.
Case 4: audit and temporal queries demand event sourcing
If your business requires answers to "what did we know at 14:32 on Tuesday" (regulated finance, healthcare, anything where an auditor will ask later), you end up at event sourcing. The append-only log of events becomes the source of truth. The current state of any aggregate is a fold over its events.
Event sourcing without CQRS is technically possible and practically miserable. Querying "all orders over $1k from EU customers" by replaying every order event is not a query, it is a batch job. So you build a read model. At which point you are doing CQRS, whether you call it that or not.
class OrderEventStore:
def append(self, stream_id: str, events: list[Event]) -> None:
with self.db.transaction() as tx:
for e in events:
tx.execute(
"INSERT INTO events (stream, type, payload, ts)"
" VALUES (%s, %s, %s, %s)",
(stream_id, e.type, json.dumps(e.data), e.ts),
)
self.bus.publish(e)
def load(self, stream_id: str) -> list[Event]:
rows = self.db.fetchall(
"SELECT type, payload, ts FROM events"
" WHERE stream = %s ORDER BY ts",
(stream_id,),
)
return [Event.from_row(r) for r in rows]
class OrderSearchProjection:
"""Denormalized table for analyst queries."""
def on_order_placed(self, e: OrderPlaced) -> None:
self.db.execute(
"INSERT INTO orders_search "
"(order_id, customer_id, total, region, placed_at) "
"VALUES (%s, %s, %s, %s, %s)",
(e.order_id, e.customer_id, e.total,
e.region, e.ts),
)
The event store answers "what happened, in order." The projection answers "what is the current shape." If you do not need temporal queries (most systems do not), do not start here.
The bill comes due
Pick CQRS for the right reason and you still pay. Two models means two schemas to evolve, two stores to back up, two failure modes during deploys. Eventual consistency means the user who just hit "save" can refresh and not see their change for an illustrative 80ms of replication lag. That sounds fine until your support inbox tells you it does not.
The big one is projection rebuilds. The first time you change the shape of a read model, you have to rebuild it from the source. If your write store is the source, that is a long-running migration. If your event store is the source, it is a long-running replay. Either way the rebuild script becomes a load-bearing piece of code that nobody wants to own. Plan for it on day one or it will plan for you on day three hundred.
Other costs that show up later: idempotent event handlers (the bus will redeliver), out-of-order events (timestamps lie), schema versioning on events (you will edit a payload and break a five-month-old projection). None of this is unsolvable. All of it is work you would not be doing if read and write shared a model.
The default position
A CRUD app is not a CQRS app. A small service with a normal request/response API is not a CQRS app. A microservice that owns its own data and serves a handful of queries is not a CQRS app. Most of what gets called "CQRS" in code reviews is just command-query separation (the much older idea that methods either change state or return data, never both), which costs nothing and is good practice everywhere.
CQRS, the architecture, is the version with two models, two stores, and an eventual-consistency window between them. Reach for it later than you think. The complexity is real. The cases above are when it pays back.
If you find yourself reaching for CQRS because the architecture diagram looks more impressive with two boxes, close the laptop. Go for a walk. Come back and add an index.
If this was useful
The Event-Driven Architecture Pocket Guide walks through CQRS, sagas, the outbox pattern, and the failure modes that show up six months in — projection rebuilds, out-of-order events, the consistency-window bugs that only the support team sees. If you are evaluating whether to split read and write, it is the chapter-by-chapter version of this post.
Top comments (0)