Eventual consistency: designing for it instead of fighting it

A distributed system has nodes that replicate asynchronously. Users see stale data after writes, and code that assumes strong consistency produces bugs.

Design your application to embrace eventual consistency:

// 1. Read-your-writes: route reads to the primary after writes
const db = {
  primary: createClient({ host: 'primary.db' }),
  replica: createClient({ host: 'replica.db' }),
};

async function createPost(userId, data) {
  const post = await db.primary.query('INSERT INTO posts ...', [data]);
  // Store token indicating this user has a recent write
  await redis.setEx(`wrote:${userId}`, 60, '1');
  return post;
}

async function getPosts(userId) {
  const hasRecentWrite = await redis.get(`wrote:${userId}`);
  // Read from primary if user just wrote, otherwise use replica
  const client = hasRecentWrite ? db.primary : db.replica;
  return client.query('SELECT * FROM posts WHERE user_id = $1', [userId]);
}

// 2. Optimistic UI: show the expected state immediately
// Client renders the new comment before server confirms
// Rollback on error with user notification

// 3. For counts and aggregates: accept slight staleness
// Exact counts: always read from primary
// Display counts: read from replica or cache

Read replicas improve read throughput but have replication lag. Knowing which queries need strong consistency (payment totals) vs. can tolerate staleness (view counts) lets you use replicas safely.