liveBook · Manning

Read replica

As explained in Clean Applications with Hexagonal Architecture

A copy of data maintained from a source system and used to serve reads.

A query may need data owned by another service, such as an author’s display name, without a join across the two stores. A read replica is a consumer-owned local copy of selected data from the source’s published contract. The source remains authoritative, and the copy is only as fresh as its latest replication update. section 11.6 section 11.7

Use a replica when several reads need a relatively broad set of published data, can tolerate lag, and can meet their response-time targets using the local representation. Map contract fields at the boundary into the consumer’s read model; do not mirror the source’s private database schema. section 11.6 section 11.7

Compare the alternatives for each query:

  • Ask the source when the answer must be current. There is no local copy to reconcile, but the query inherits the source’s latency and availability. section 11.6
  • Read a replica when a broader local representation serves the query within its response-time target and the consumer can operate the copy. section 11.7
  • Consider a projected view when repeated filtering, joining, aggregation, or ordering makes request-time work too slow or complex. It stores a query-shaped result, but also requires updates and drift management. section 11.7
Table 11.3 Choosing a “read” strategy
Strategy
Model shape
Freshness
Coupling
Who owns the copy
Consistency
Ask the source context
The author service’s model, returned through its API; WriteFlow keeps no copy
Current at the moment of the call
Your query inherits the source context’s availability and latency
The source context holds the only copy
Source context’s response at call time; no shared transaction or snapshot with WriteFlow’s data.
Read a replica
A broader local copy of selected data from the author service’s published contract, mapped into WriteFlow’s read model.
As fresh as the last replication update
You run the replication and depend on the source context for updates
The consumer holds the copy; the source context holds the truth
Eventually consistent; the copy can drift
Project a view
A WriteFlow-owned, query-shaped view with only the fields the query needs; it may combine data from multiple source contexts if the query requires it
As fresh as the last projection event
You own the projection and depend on the source context’s events
The consumer owns the view; each source context owns its data
Eventually consistent; updates can arrive twice or out of order

Compare the read strategies by model shape, freshness, coupling, ownership, and consistency. section 11.7

A replica needs operational care. Updates can be duplicated, arrive out of order, or be missed; deletes and partial updates can also leave the copy inconsistent. The consumer must update it, check for drift, and be able to rebuild or reconcile it. section 11.6 section 11.9

An article query

An article stores an author identifier but needs the author’s display name. If the query tolerates lag, it can read a local replica of published author data. An output port lets the handler use consumer-owned types while an adapter hides whether the answer comes from the replica, the source API, or a projected view. This read choice does not replace author validation before approval: stale read-side data must not decide whether an action is allowed. section 11.6 section 11.7 section 11.9

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Explains selection, boundary mapping, update failure modes, and operational duties without detailing a replication implementation.
Examples
Uses an article query that reads an author’s display name from data owned by an author service.
What you can do after
Evaluate read strategies per query against freshness, response time, coupling, and the cost of maintaining a local copy.
How it connects
Connects replicas to output ports, adapters, projected views, eventual consistency, and source ownership.

Also explained in

Compare how 3 books explain read replica →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Clean Applications with Hexagonal Architecture. The section links point to the parts of the book it draws on.