Read-your-writes consistency

Overview

Read-your-writes consistency guarantees that any read operation from a client will always reflect the effects of all previous write operations from that same client. This is especially important in globally distributed databases where replication lag can cause stale reads.

The problem: eventual consistency

Upstash Redis supports global read replicas for low-latency reads worldwide. However, replication takes time:

// Without read-your-writes
const redis = new Redis({ url, token, readYourWrites: false });

await redis.set("user:123:name", "Alice");

// This might return null or old value if reading from a replica
// that hasn't replicated the write yet
const name = await redis.get("user:123:name"); 
// Potentially: null (stale read)

This can lead to confusing application behavior:

User updates their profile name to “Alice”
Application writes to primary: SET user:123:name Alice
Application immediately reads from replica: GET user:123:name
Replica hasn’t replicated yet, returns old value: “Bob”
User sees their old name despite just updating it

The solution: sync tokens

Upstash implements read-your-writes using sync tokens. When enabled (the default), each write response includes a sync token that represents the replication state:

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
  readYourWrites: true, // enabled by default
});

await redis.set("user:123:name", "Alice");
// Response includes: upstash-sync-token: abc123

const name = await redis.get("user:123:name");
// Request includes: upstash-sync-token: abc123
// Server ensures replica has replicated at least to abc123
// Returns: "Alice" (guaranteed fresh)

How it works

Client tracks sync token: The SDK maintains a upstashSyncToken that’s updated after each write
Write operations: Server includes current sync token in response headers
Read operations: Client sends latest sync token in request headers
Server waits: If reading from replica, server waits until replica has caught up to the sync token
Consistent read: Client receives data reflecting all previous writes

Enabling read-your-writes

Read-your-writes is enabled by default:

// Explicitly enabled (default behavior)
const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
  readYourWrites: true,
});

To disable:

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
  readYourWrites: false,
});

Disabling read-your-writes can provide lower latency for read-heavy workloads where stale reads are acceptable.

Using sync tokens

Automatic sync token management

The SDK automatically manages sync tokens:

const redis = new Redis({ url, token, readYourWrites: true });

// Write - sync token updated automatically
await redis.set("counter", 0);

// Read - sync token sent automatically
const value = await redis.get("counter"); // Guaranteed to see 0

// Another write - sync token updated
await redis.incr("counter");

// Read reflects the increment
const newValue = await redis.get("counter"); // Guaranteed to see 1

Manual sync token management

For advanced use cases, you can manually access and set sync tokens:

const redis = new Redis({ url, token, readYourWrites: true });

await redis.set("key", "value");

// Get current sync token
const syncToken = redis.readYourWritesSyncToken;
console.log(syncToken); // "abc123..."

// Save sync token (e.g., to session, database, etc.)
await saveToSession(userId, syncToken);

// Later, restore sync token in a new request
const redis2 = new Redis({ url, token, readYourWrites: true });
const savedToken = await loadFromSession(userId);
redis2.readYourWritesSyncToken = savedToken;

// This read will reflect all writes from the previous session
const value = await redis2.get("key");

Cross-request consistency

In serverless environments, each request typically creates a new Redis client. To maintain consistency across requests:

Using session storage

import { Redis } from "@upstash/redis";

export async function handler(request: Request) {
  const redis = new Redis({ url, token, readYourWrites: true });
  const session = await getSession(request);
  
  // Restore sync token from previous request
  if (session.syncToken) {
    redis.readYourWritesSyncToken = session.syncToken;
  }
  
  // Perform operations
  await redis.set("user:profile", { name: "Alice" });
  const profile = await redis.get("user:profile"); // Consistent read
  
  // Save sync token for next request
  session.syncToken = redis.readYourWritesSyncToken;
  await saveSession(session);
  
  return new Response(JSON.stringify(profile));
}

Using cookies

import { Redis } from "@upstash/redis";

export async function handler(request: Request) {
  const redis = new Redis({ url, token, readYourWrites: true });
  
  // Restore from cookie
  const syncToken = request.headers.get("cookie")
    ?.match(/sync-token=([^;]+)/)?.[1];
  
  if (syncToken) {
    redis.readYourWritesSyncToken = decodeURIComponent(syncToken);
  }
  
  // Perform operations
  await redis.incr("visits");
  const visits = await redis.get("visits");
  
  // Return sync token in cookie
  return new Response(JSON.stringify({ visits }), {
    headers: {
      "Set-Cookie": `sync-token=${encodeURIComponent(redis.readYourWritesSyncToken!)}; Path=/; HttpOnly`,
    },
  });
}

Performance considerations

Latency impact

Read-your-writes can add latency to reads if replicas are behind:

// With read-your-writes (may wait for replication)
const start = Date.now();
const value = await redis.get("key");
const latency = Date.now() - start;
// Latency: 10-100ms (depends on replication lag)

// Without read-your-writes (immediate read from nearest replica)
const redis2 = new Redis({ url, token, readYourWrites: false });
const start2 = Date.now();
const value2 = await redis2.get("key");
const latency2 = Date.now() - start2;
// Latency: 5-20ms (faster, but may be stale)

When to disable

Consider disabling read-your-writes for:

Analytics and metrics: Stale data is acceptable
Caching scenarios: Eventual consistency is fine
Read-heavy workloads: Lower latency is more important than consistency
Public data: Data that doesn’t change frequently

const redis = new Redis({
  url,
  token,
  readYourWrites: false, // Accept stale reads for lower latency
});

// These reads are fast but may be slightly stale
const pageViews = await redis.get("stats:page-views");
const popularPosts = await redis.zrange("posts:popular", 0, 10);

When to keep enabled

User-facing data: Profile updates, settings, etc.
After write operations: Immediately reading what you just wrote
Financial operations: Ensuring consistency is critical
Default choice: When in doubt, keep it enabled

Consistency guarantees

What read-your-writes guarantees

✅ Your reads reflect your own writes

await redis.set("key", "value");
const result = await redis.get("key");
// Guaranteed: result === "value"

✅ Monotonic reads (won’t see older data after newer data)

await redis.set("counter", 1);
const value1 = await redis.get("counter"); // 1
await redis.set("counter", 2);
const value2 = await redis.get("counter"); // 2 (never goes back to 1)

What it doesn’t guarantee

❌ Reading other clients’ writes immediately

// Client A
await redisA.set("shared-key", "from-A");

// Client B (different instance, different sync token)
const value = await redisB.get("shared-key");
// May still see old value - read-your-writes only applies to same client

❌ Strong consistency across all clients

// This is eventual consistency, not strong consistency
// Other clients may see different values temporarily

Best practices

Keep read-your-writes enabled by default

const redis = new Redis({
  url,
  token,
  readYourWrites: true, // default, recommended
});

Persist sync tokens for cross-request consistency

// Save to session, cookie, or database
session.syncToken = redis.readYourWritesSyncToken;

Disable only when appropriate

// Only for analytics, caching, or read-heavy public data
const redis = new Redis({ url, token, readYourWrites: false });

Don’t share Redis instances across users

// Bad - sync tokens from different users mix
const globalRedis = new Redis({ url, token });

// Good - each request gets its own instance
app.get("/api/user", async (req) => {
  const redis = new Redis({ url, token });
  // ...
});

Example: user profile update

import { Redis } from "@upstash/redis";

// User updates profile
export async function updateProfile(userId: string, name: string) {
  const redis = new Redis({
    url: process.env.UPSTASH_REDIS_REST_URL!,
    token: process.env.UPSTASH_REDIS_REST_TOKEN!,
    readYourWrites: true, // Ensure user sees their update
  });
  
  // Write profile
  await redis.hset(`user:${userId}`, { name, updatedAt: Date.now() });
  
  // Immediately read back - guaranteed to see the update
  const profile = await redis.hgetall(`user:${userId}`);
  
  return profile; // User sees their updated name immediately
}

// User views profile in another request
export async function getProfile(userId: string, syncToken?: string) {
  const redis = new Redis({
    url: process.env.UPSTASH_REDIS_REST_URL!,
    token: process.env.UPSTASH_REDIS_REST_TOKEN!,
    readYourWrites: true,
  });
  
  // Restore sync token from previous request
  if (syncToken) {
    redis.readYourWritesSyncToken = syncToken;
  }
  
  // Read profile - reflects all previous writes from this user's session
  const profile = await redis.hgetall(`user:${userId}`);
  
  return {
    profile,
    syncToken: redis.readYourWritesSyncToken, // Return for next request
  };
}

Getting Started

Core Concepts

Platform Guides

Advanced Features

Examples

Read-your-writes consistency

Overview

The problem: eventual consistency

The solution: sync tokens

How it works

Enabling read-your-writes

Using sync tokens

Automatic sync token management

Manual sync token management

Cross-request consistency

Using session storage

Using cookies

Performance considerations

Latency impact

When to disable

When to keep enabled

Consistency guarantees

What read-your-writes guarantees

What it doesn’t guarantee

Best practices

Example: user profile update

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Platform Guides

Advanced Features

Examples

​Overview

​The problem: eventual consistency

​The solution: sync tokens

​How it works

​Enabling read-your-writes

​Using sync tokens

​Automatic sync token management

​Manual sync token management

​Cross-request consistency

​Using session storage

​Using cookies

​Performance considerations

​Latency impact

​When to disable

​When to keep enabled

​Consistency guarantees

​What read-your-writes guarantees

​What it doesn’t guarantee

​Best practices

​Example: user profile update

Build docs developers (and LLMs) love

Overview

The problem: eventual consistency

The solution: sync tokens

How it works

Enabling read-your-writes

Using sync tokens

Automatic sync token management

Manual sync token management

Cross-request consistency

Using session storage

Using cookies

Performance considerations

Latency impact

When to disable

When to keep enabled

Consistency guarantees

What read-your-writes guarantees

What it doesn’t guarantee

Best practices

Example: user profile update