Eventual Consistency

Eventual consistency guarantees that replicas converge if updates stop, without promising when a read sees the latest write. Applications must handle stale reads and conflicts explicitly.

data-integrity

Definition

Eventual consistency is a consistency model in which, if no new updates are made, all replicas eventually converge to the same value. It does not guarantee that any particular read returns the latest write, nor a bound on convergence time unless the system adds one. It is common in replicated stores, caches, and multi-region systems that prioritize availability and low latency over immediate global agreement.

Context and scope

Eventual consistency appears in distributed databases, CDNs, search indexes, and event-driven projections. Some systems provide stronger session guarantees such as read-your-writes or monotonic reads on top of eventual convergence. The application must decide which guarantees a user task needs and design around the rest.

Common misconceptions

Eventually consistent means data is usually consistent — it means convergence is guaranteed only after updates stop
Eventual consistency is always acceptable — account balances, permissions, and uniqueness constraints may require stronger guarantees
Conflicts resolve themselves — the system needs a defined conflict-resolution rule such as last-write-wins or application merge

Anti-patterns

Reading from an eventually consistent store immediately after a write and treating a miss as failure
Using last-write-wins for data where lost updates are unacceptable
Showing a global total from independently updated replicas without a freshness indicator

Related concepts

Related examples

Authoritative source

https://www.allthingsdistributed.com/2008/12/eventually_consistent.html

What is guaranteed

If writes stop, replicas eventually agree. That is the whole guarantee. It says nothing about how long convergence takes unless the system publishes an SLA or a read-your-writes mechanism.

Designing for it

Identify tasks that require read-your-writes and route them to a primary or a caught-up replica.
Make conflicts explicit with version vectors, timestamps, or domain-specific merges.
Show freshness when displaying aggregated or delayed data.
Use idempotent consumers so repeated events converge without duplicate effects.

// A projection is eventually consistent; retries must be idempotent.
async function applyEvent(event) {
  await db.upsert('projection', {
    key: event.aggregateId,
    version: event.version,
    value: event.payload,
  }, { onConflict: 'version < excluded.version' });
}

When to use it

Use eventual consistency for feeds, search indexes, analytics, and cross-region reads where bounded staleness is acceptable. Compared to strong consistency, it usually improves availability and latency. Compared to caching, it is a property of the data store rather than a temporary copy, but it still requires conflict and freshness handling.

Pitfalls

Last-write-wins can silently discard a concurrent update. A retry can apply an event twice unless consumers are idempotent. A read immediately after a write may legitimately miss the write; the UI should not treat that as data loss. Test convergence under duplicate and out-of-order events, not only the happy path.