In a CQRS architecture, why must the query side never mutate state, even indirectly (e.g. lazy-computing and caching a value inside a query handler)?

## The rule and where it comes from **Command-Query Separation (CQS)**, a principle articulated by Bertrand Meyer and adopted as one of the founding ideas behind CQRS, says that every method should either be a command that changes state and returns nothing meaningful, or a query that returns data and changes nothing — never both. On the read/query side of a CQRS system, this means a query handler is allowed to read from a read model (or any store) and shape a response, but it must not, as part of executing that read, write to the write model, mutate the read model outside of the normal event-driven projection path, increment counters, or trigger side effects like sending emails or kicking off workflows. Common violations look innocuous in isolation: - a query handler that notices a cached value is missing and computes-and-stores it right there in the request path - an endpoint that increments a 'view count' column inline while fetching an article - a 'get or create' query that silently inserts a default record the first time it's called for a new user ## What the word 'query' promises The reason this matters is that 'query' carries an implicit contract with everyone downstream of it: - it's safe to call repeatedly - safe to call in parallel - safe to retry after a timeout - safe to route to any read replica - safe to run against a point-in-time snapshot without changing what that snapshot means Load balancers and API gateways route 'read' traffic (`GET` requests, query buses) differently from 'write' traffic — often to read-only replicas, edge caches, or CDNs — precisely because they assume queries don't need write access and can be freely duplicated, retried, or served from a stale copy. The moment a query mutates state, all of those assumptions break: a request that times out and gets retried by a client library can double-apply the side effect; a query fired twice by an over-eager frontend (double-click, race condition) does the mutation twice; a load test or crawler that hammers a 'read' endpoint accidentally generates real writes; and a read replica that isn't supposed to accept writes either fails outright or silently diverges from the primary. ## The legitimate exception There are legitimate cases where reading triggers computing something new — **lazy cache population** and **read-time materialization** are real, useful patterns — but the correct implementation keeps the mutation out of the query's contract. A cache-aside read can compute a value and write it into a cache, as long as that write is: - provably **idempotent** (writing the same value twice is harmless) - invisible to the caller's correctness (the response is correct whether or not the cache write succeeds) - ideally routed through the same event-driven or asynchronous path the rest of the read model uses, rather than a bespoke write buried inside the query handler The anti-pattern isn't 'a read ever causes a write anywhere in the system' — it's a query whose correctness or observable behavior depends on that write succeeding, or that treats the mutation as part of what 'querying' means. ## Failure modes Failure modes in production tend to show up as concurrency bugs and infrastructure mismatches rather than obvious crashes. 1. **Contention.** Under load, many concurrent requests hitting a 'helpful' mutating query can race to write the same computed value, causing lock contention, duplicate rows, or lost-update bugs if the write isn't upsert-safe. 2. **Replicas.** Systems that scale reads horizontally by adding read replicas discover that mutating queries either can't run there at all (replicas are often read-only at the database level) or, if they can, cause replication conflicts. 3. **Retry.** Retried requests — extremely common in distributed systems, where a client can't tell a timeout apart from a lost response — silently double-apply whatever the query mutated, and because it's 'just a GET,' nobody built idempotency keys for it the way they would for a payment command. 4. **Confusing dashboards.** Observability gets confusing too: write-path dashboards (write latency, lock waits, replication lag) start showing traffic correlated with GET request volume, and nobody can explain why until someone finds the inline write in the query handler. ## Seeing it break, and the fix A concrete example: a reporting dashboard's `GET /reports/monthly-summary` endpoint recomputes an aggregate over recent orders and writes the result into a summary table directly in the request handler, so subsequent requests are fast. Under normal traffic this works fine. During a traffic spike or a bot crawling the API, dozens of concurrent requests for the same report all miss the 'cache' simultaneously, all recompute the aggregate, and all try to write it back at once — the summary table sees lock contention, some requests time out, and the endpoint that was supposed to be a cheap read becomes the slowest, most write-contended path in the system. The fix is to move the aggregation into the write side: a background job or event-driven projector recomputes and stores the summary whenever the underlying orders change, and the GET handler only ever reads whatever is currently there, even if that means occasionally serving a summary that's a few seconds stale.