Redis

When to Use Redis vs. Database

USE REDIS:
  - Data that changes frequently and is read often (cache)
  - Temporary data with TTL (sessions, OTP codes, rate limits)
  - Real-time features (pub/sub, presence, typing indicators)
  - Counters and aggregations (view counts, rate limits)
  - Distributed locks (prevent concurrent operations)

USE DATABASE:
  - Source of truth (orders, users, products)
  - Complex queries (joins, aggregations, full-text search)
  - Data that must survive restarts without rebuild
  - Relational data with integrity constraints

Patterns

Client Setup

// lib/redis.ts (ioredis)
import Redis from 'ioredis';

export const redis = new Redis(process.env.REDIS_URL!, {
  maxRetriesPerRequest: 3,
  retryStrategy(times) {
    const delay = Math.min(times * 50, 2000);
    return delay;
  },
  lazyConnect: true,
});

// Upstash (serverless-compatible)
import { Redis } from '@upstash/redis';
export const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
});

Cache-Aside Pattern

async function getCachedProduct(id: string): Promise<Product> {
  const cacheKey = `product:${id}`;

  // Try cache first
  const cached = await redis.get(cacheKey);
  if (cached) return JSON.parse(cached);

  // Cache miss: fetch from database
  const product = await db.product.findUnique({ where: { id } });
  if (!product) throw new NotFoundError('Product', id);

  // Store in cache with TTL
  await redis.set(cacheKey, JSON.stringify(product), 'EX', 3600); // 1 hour

  return product;
}

// Invalidate on update
async function updateProduct(id: string, data: Partial<Product>) {
  const product = await db.product.update({ where: { id }, data });
  await redis.del(`product:${id}`);
  return product;
}

Rate Limiter (Sliding Window)

async function rateLimit(
  key: string,
  limit: number,
  windowSeconds: number,
): Promise<{ allowed: boolean; remaining: number; resetAt: number }> {
  const now = Date.now();
  const windowStart = now - windowSeconds * 1000;
  const redisKey = `rate:${key}`;

  // Use sorted set: score = timestamp, member = unique request ID
  const pipe = redis.pipeline();
  pipe.zremrangebyscore(redisKey, 0, windowStart);  // Remove expired
  pipe.zadd(redisKey, now, `${now}:${Math.random()}`);  // Add current
  pipe.zcard(redisKey);  // Count in window
  pipe.expire(redisKey, windowSeconds);  // Set TTL

  const results = await pipe.exec();
  const count = results![2][1] as number;

  return {
    allowed: count <= limit,
    remaining: Math.max(0, limit - count),
    resetAt: now + windowSeconds * 1000,
  };
}

// Usage in middleware
const { allowed, remaining, resetAt } = await rateLimit(
  `api:${userId}`,
  100,  // 100 requests
  60,   // per 60 seconds
);

if (!allowed) {
  return new Response('Rate limit exceeded', {
    status: 429,
    headers: {
      'X-RateLimit-Limit': '100',
      'X-RateLimit-Remaining': String(remaining),
      'X-RateLimit-Reset': String(Math.ceil(resetAt / 1000)),
      'Retry-After': String(Math.ceil((resetAt - Date.now()) / 1000)),
    },
  });
}

Distributed Lock

async function acquireLock(
  key: string,
  ttlMs: number = 10_000,
): Promise<string | null> {
  const lockId = crypto.randomUUID();
  const acquired = await redis.set(
    `lock:${key}`,
    lockId,
    'PX', ttlMs,
    'NX',  // Only set if not exists
  );
  return acquired ? lockId : null;
}

async function releaseLock(key: string, lockId: string): Promise<boolean> {
  // Lua script ensures atomicity: only delete if we own the lock
  const script = `
    if redis.call("get", KEYS[1]) == ARGV[1] then
      return redis.call("del", KEYS[1])
    else
      return 0
    end
  `;
  const result = await redis.eval(script, 1, `lock:${key}`, lockId);
  return result === 1;
}

// Usage
const lockId = await acquireLock(`order:${orderId}`);
if (!lockId) throw new Error('Could not acquire lock');
try {
  await processOrder(orderId);
} finally {
  await releaseLock(`order:${orderId}`, lockId);
}

Pub/Sub

// Publisher
await redis.publish('notifications', JSON.stringify({
  type: 'order.shipped',
  userId: 'user_123',
  orderId: 'order_456',
}));

// Subscriber (separate connection required)
const subscriber = new Redis(process.env.REDIS_URL!);
subscriber.subscribe('notifications', (err) => {
  if (err) console.error('Subscribe error:', err);
});

subscriber.on('message', (channel, message) => {
  const event = JSON.parse(message);
  console.log(`[${channel}]`, event);
});

Best Practices

1. Always set TTL on cache keys -- keys without expiry grow forever and fill memory
2. Use pipelines for multiple commands -- reduces round trips from N to 1
3. Separate connections for pub/sub -- subscriber connections are blocked; use a dedicated client
4. Use Lua scripts for atomic operations -- multi-step operations must be atomic
5. Namespace your keys -- product:123, rate:user:456, session:abc not just 123
6. Handle connection failures -- Redis may be temporarily unavailable; degrade gracefully
7. Monitor memory usage -- set maxmemory and maxmemory-policy (e.g., allkeys-lru)
8. Use JSON.stringify/parse consistently -- Redis stores strings; serialize and deserialize carefully
9. Do not store large objects -- Redis is fast for small values; large blobs belong in object storage
10. Use Upstash for serverless -- traditional Redis connections do not work well with serverless functions

Common Pitfalls