Caching with Redis in Node.js

Your database is running at 80% CPU and response times are slowing down. The fix is caching, but implementing it wrong — caching too long, not invalidating correctly, or caching the wrong data — makes performance worse instead of better. Redis is the most popular caching layer for Node.js applications because it is fast (sub-millisecond latency), versatile (multiple data structures), and persistent. This article covers the cache-aside pattern, cache invalidation strategies, rate limiting with Redis, and the production monitoring that tells you whether your cache is actually helping.

Why Redis? The Case for Caching in Node.js

In production Node.js applications, database queries and API calls are often the bottleneck. Redis provides an in-memory data store that can serve cached responses in microseconds, reducing latency and database load. Unlike simple in-memory caches, Redis offers persistence, replication, and data structures like sorted sets and streams. For Node.js, the ioredis library is the gold standard—it supports clustering, sentinel, and pipelining out of the box. Before you add caching, measure your hot paths: endpoints with high read frequency and low write frequency are prime candidates. Caching is not a silver bullet; it introduces complexity like cache invalidation and memory management. Start with a simple key-value pattern and evolve as needed.

const Redis = require('ioredis');
const redis = new Redis(); // defaults to localhost:6379

async function getUser(id) {
  const cacheKey = `user:${id}`;
  const cached = await redis.get(cacheKey);
  if (cached) return JSON.parse(cached);

  const user = await db.query('SELECT * FROM users WHERE id = ?', [id]);
  await redis.setex(cacheKey, 3600, JSON.stringify(user));
  return user;
}

Setting Up Redis with ioredis in Production

The ioredis library is preferred over redis because it supports modern features like Promise-based API, automatic reconnection, and cluster support. In production, never connect to Redis without a retry strategy. Use environment variables for connection details. For high availability, use Redis Sentinel or Cluster. Sentinel provides automatic failover; Cluster shards data across nodes. Configure connection pool limits to avoid exhausting file descriptors. Always handle connection errors gracefully—your app should not crash if Redis is down. Implement a circuit breaker pattern to fall back to the database when Redis is unreachable.

const Redis = require('ioredis');

const redis = new Redis({
  host: process.env.REDIS_HOST || 'localhost',
  port: process.env.REDIS_PORT || 6379,
  retryStrategy: (times) => Math.min(times * 50, 2000),
  maxRetriesPerRequest: null,
  enableReadyCheck: true,
});

redis.on('error', (err) => {
  console.error('Redis error:', err);
  // Optionally, switch to a fallback cache
});

module.exports = redis;

Cache-Aside Pattern: The Standard Approach

The cache-aside pattern is the most common caching strategy. On a read request, check the cache first. If found (cache hit), return the data. If not (cache miss), fetch from the database, store in cache, then return. This pattern is simple and effective for read-heavy workloads. However, it introduces a race condition: two concurrent requests for the same uncached data can both hit the database. Use a mutex or a 'lock' key to prevent thundering herd. Alternatively, use Redis SETNX to implement a distributed lock. For writes, always invalidate the cache (delete the key) rather than updating it, to avoid stale data.

async function getProduct(id) {
  const cacheKey = `product:${id}`;
  let product = await redis.get(cacheKey);
  if (product) return JSON.parse(product);

  // Thundering herd protection
  const lockKey = `lock:product:${id}`;
  const acquired = await redis.setnx(lockKey, '1', 'EX', 5);
  if (!acquired) {
    // Wait for the other request to populate cache
    await new Promise(resolve => setTimeout(resolve, 100));
    return getProduct(id);
  }

  try {
    product = await db.query('SELECT * FROM products WHERE id = ?', [id]);
    await redis.setex(cacheKey, 3600, JSON.stringify(product));
    return product;
  } finally {
    await redis.del(lockKey);
  }
}

Cache Invalidation: The Hardest Problem in Computer Science

Cache invalidation is notoriously difficult. The simplest strategy is time-to-live (TTL) expiration. Set a reasonable TTL based on how stale data can be. For dynamic data, use write-through or write-behind patterns. Write-through: update cache synchronously when writing to DB. Write-behind: update cache asynchronously after DB write. Both ensure cache consistency but add latency. Another approach is to use Redis keyspace notifications to listen for expiration events and trigger cache rebuilds. In microservices, consider using a message queue to broadcast invalidation events. Avoid caching data that changes frequently—it will cause more cache misses than hits.

async function updateUser(id, data) {
  // Write-through: update DB and cache atomically
  const result = await db.query('UPDATE users SET ? WHERE id = ?', [data, id]);
  if (result.affectedRows > 0) {
    const cacheKey = `user:${id}`;
    await redis.setex(cacheKey, 3600, JSON.stringify(data));
  }
  return result;
}

// Or use cache invalidation on write
async function deleteUser(id) {
  await db.query('DELETE FROM users WHERE id = ?', [id]);
  await redis.del(`user:${id}`);
}

Advanced Data Structures: Caching Complex Queries

Redis supports data structures beyond strings: hashes, sorted sets, lists, and hyperloglogs. For caching paginated API responses, use sorted sets to store IDs with a score (e.g., timestamp) and then fetch a slice. For caching aggregated data (e.g., top 10 products), use sorted sets with ZREVRANGE. Hashes are ideal for caching objects with multiple fields—you can update a single field without fetching the entire object. Use pipelining to batch multiple commands and reduce round trips. For large datasets, consider using Redis Streams for event sourcing or caching time-series data.

// Cache top 10 products by sales
async function getTopProducts() {
  const cacheKey = 'top:products';
  let products = await redis.zrevrange(cacheKey, 0, 9, 'WITHSCORES');
  if (products.length === 0) {
    // Fetch from DB and populate sorted set
    const rows = await db.query('SELECT id, sales FROM products ORDER BY sales DESC LIMIT 10');
    const pipeline = redis.pipeline();
    rows.forEach(row => {
      pipeline.zadd(cacheKey, row.sales, row.id);
    });
    pipeline.expire(cacheKey, 3600);
    await pipeline.exec();
    products = rows.map(r => [r.id, r.sales]);
  }
  return products;
}

Handling Cache Stampedes and Hot Keys

A cache stampede occurs when many requests simultaneously miss the cache and overload the database. Hot keys are keys that receive a disproportionate amount of traffic, causing a single Redis node to become a bottleneck. To mitigate stampedes, use the mutex pattern shown earlier, or use probabilistic early expiration: if a key is about to expire and is heavily requested, proactively refresh it. For hot keys, shard the key across multiple Redis nodes by appending a random suffix (e.g., user:123:0, user:123:1) and distribute reads. This spreads the load. Monitor cache hit rates and key access frequency to detect hot keys early.

// Shard a hot key across N replicas
const SHARD_COUNT = 10;

function getShardedKey(baseKey, shardId) {
  return `${baseKey}:${shardId}`;
}

async function getHotUser(id) {
  const shard = Math.floor(Math.random() * SHARD_COUNT);
  const cacheKey = getShardedKey(`user:${id}`, shard);
  let user = await redis.get(cacheKey);
  if (!user) {
    // Fetch from DB and populate all shards
    user = await db.query('SELECT * FROM users WHERE id = ?', [id]);
    const pipeline = redis.pipeline();
    for (let i = 0; i < SHARD_COUNT; i++) {
      pipeline.setex(getShardedKey(`user:${id}`, i), 3600, JSON.stringify(user));
    }
    await pipeline.exec();
  } else {
    user = JSON.parse(user);
  }
  return user;
}

Monitoring and Observability for Redis Caching

You can't fix what you can't see. Monitor Redis with INFO command, redis-cli --stat, or tools like RedisInsight. Track cache hit rate, memory usage, evicted keys, and command latency. In Node.js, instrument your cache calls with metrics (e.g., Prometheus counters). Log cache misses and slow commands. Set alerts for low hit rate (<80%) or high eviction rate. Use Redis slow log to identify expensive commands. For distributed tracing, add cache spans to your APM tool. Production insight: a sudden drop in hit rate often indicates a bug in cache key generation or invalidation logic.

const prometheus = require('prom-client');

const cacheHits = new prometheus.Counter({
  name: 'redis_cache_hits_total',
  help: 'Total number of cache hits',
});

const cacheMisses = new prometheus.Counter({
  name: 'redis_cache_misses_total',
  help: 'Total number of cache misses',
});

async function getWithMetrics(key, fetchFn) {
  let value = await redis.get(key);
  if (value) {
    cacheHits.inc();
    return JSON.parse(value);
  }
  cacheMisses.inc();
  value = await fetchFn();
  await redis.setex(key, 3600, JSON.stringify(value));
  return value;
}

Production Pitfalls: Memory, Eviction, and Persistence

Redis runs in memory; if you exceed available RAM, it evicts keys based on the configured policy (e.g., allkeys-lru). Choose a policy that matches your use case. For caching, allkeys-lru is common. Monitor evicted_keys metric—high eviction means you need more memory or a smaller cache. Persistence (RDB snapshots or AOF logs) adds overhead. For caching, you can disable persistence to maximize performance, but then a restart empties the cache. If you need persistence, use AOF with appendfsync everysec. Never use blocking commands like KEYS in production—use SCAN instead. Also, avoid storing large values (>1MB) as they degrade performance.

# Recommended config for caching
maxmemory 2gb
maxmemory-policy allkeys-lru
save ""  # disable RDB persistence
appendonly no
# If persistence needed:
# appendonly yes
# appendfsync everysec

Testing Caching Logic: Unit and Integration Tests

Caching code is often undertested. Write unit tests that mock Redis to verify cache hit/miss logic. Use ioredis-mock for fast, in-memory testing. For integration tests, spin up a real Redis instance (e.g., using Docker or testcontainers). Test edge cases: cache expiration, connection failures, concurrent requests, and invalidation. Simulate thundering herd to ensure your mutex works. Test that cache keys are correctly namespaced to avoid collisions. Also test that your fallback to database works when Redis is down. Production insight: we once had a bug where cache keys included a trailing space, causing 100% cache misses. A simple test caught it.

const RedisMock = require('ioredis-mock');
const { getProduct } = require('./cache-aside');

jest.mock('ioredis', () => require('ioredis-mock'));

beforeEach(() => {
  redis = new RedisMock();
});

test('returns cached product on second call', async () => {
  const product = { id: 1, name: 'Widget' };
  db.query.mockResolvedValueOnce(product);

  const result1 = await getProduct(1);
  expect(result1).toEqual(product);
  expect(db.query).toHaveBeenCalledTimes(1);

  const result2 = await getProduct(1);
  expect(result2).toEqual(product);
  expect(db.query).toHaveBeenCalledTimes(1); // no extra DB call
});

Beyond Simple Caching: Redis as a Primary Data Store

Redis can serve as a primary database for certain use cases: session stores, real-time leaderboards, rate limiters, and message queues. For session storage, Redis with TTL is ideal because sessions expire naturally. For rate limiting, use the sliding window algorithm with sorted sets or the simpler INCR with TTL. For job queues, use Redis lists or streams with blocking pop. However, Redis is not ACID-compliant and data loss is possible without proper persistence. Use it as a primary store only when you can tolerate eventual consistency and have a backup strategy. Production insight: we used Redis as a primary store for a real-time analytics pipeline; a node failure caused data loss, so we added AOF persistence and regular backups.

// Sliding window rate limiter using sorted sets
async function isRateLimited(userId, maxRequests, windowMs) {
  const key = `ratelimit:${userId}`;
  const now = Date.now();
  const windowStart = now - windowMs;

  // Remove old entries
  await redis.zremrangebyscore(key, 0, windowStart);

  // Count current entries
  const count = await redis.zcard(key);
  if (count >= maxRequests) {
    return true;
  }

  // Add current request
  await redis.zadd(key, now, `${now}`);
  await redis.expire(key, Math.ceil(windowMs / 1000));
  return false;
}

Scaling Redis: Clustering and Replication

When a single Redis instance isn't enough, scale out with Redis Cluster or replication. Cluster automatically shards data across multiple nodes, providing linear scalability. Use ioredis Cluster client which handles routing and failover. For read-heavy workloads, use replication with a master for writes and replicas for reads. Be aware of eventual consistency: replicas may lag behind the master. In Cluster, cross-slot operations (e.g., multi-key commands) are limited to keys in the same hash slot. Use hash tags to force related keys into the same slot. Monitor cluster health with CLUSTER INFO and CLUSTER NODES.

const Redis = require('ioredis');

const cluster = new Redis.Cluster([
  { host: '127.0.0.1', port: 7000 },
  { host: '127.0.0.1', port: 7001 },
  { host: '127.0.0.1', port: 7002 },
], {
  scaleReads: 'slave', // read from replicas
  redisOptions: {
    retryStrategy: (times) => Math.min(times * 50, 2000),
  },
});

// Use hash tags to co-locate keys
await cluster.set('user:{123}:profile', 'data');
await cluster.set('user:{123}:settings', 'data'); // same slot

Security: Securing Your Redis Instance

Redis is often deployed without authentication, which is a security risk. Always set a strong password using requirepass in redis.conf. Use TLS for encryption in transit, especially if Redis is accessed over the network. Bind Redis to localhost or a private network, never expose it to the internet. Use rename-command to disable dangerous commands like FLUSHALL, CONFIG, and KEYS in production. In Node.js, never hardcode credentials; use environment variables or a secrets manager. Regularly audit Redis access logs. Production insight: a developer accidentally exposed Redis on a public IP without password; within minutes, an attacker ran FLUSHALL and deleted all cache. We added firewall rules and authentication immediately.

# redis.conf security settings
requirepass SuperSecret123
bind 127.0.0.1
rename-command FLUSHALL ""
rename-command CONFIG ""
rename-command KEYS ""
# Enable TLS (if needed)
port 0
tls-port 6379
tls-cert-file /path/to/redis.crt
tls-key-file /path/to/redis.key

Memory Caching Alternatives: node-cache vs Redis

Redis is powerful, but for single-process Node.js apps, node-cache offers a simpler in-memory alternative. node-cache stores data in the Node process heap, with zero network overhead. It supports TTL, keys, and stats. However, it's not shared across processes or machines, so it's unsuitable for clustered or serverless deployments. Use node-cache for small, ephemeral caches (e.g., rate-limiting counters, session data) where Redis would be overkill. For production, Redis remains the standard for distributed caching, but node-cache can reduce latency and complexity in single-server scenarios. Always benchmark: node-cache hits are microseconds, Redis hits are milliseconds. Choose based on your scaling needs.

const NodeCache = require('node-cache');
const cache = new NodeCache({ stdTTL: 60, checkperiod: 120 });

function getCachedData(key, fetchFn) {
  const value = cache.get(key);
  if (value) return Promise.resolve(value);
  return fetchFn().then(data => {
    cache.set(key, data);
    return data;
  });
}

// Usage
const data = await getCachedData('user:123', () => fetchUserFromDB(123));

Express Caching Middleware: Drop-in Response Caching

For REST APIs, caching entire responses can drastically reduce load. Express middleware like apicache or express-cache-controller can cache responses based on URL or custom keys. apicache stores responses in memory (or Redis) and serves them without hitting your route handlers. Configure TTL per route. This is ideal for GET endpoints with infrequent updates. Be careful with authenticated routes: cache only public data or vary by user. Example: cache a /api/products endpoint for 5 minutes. The middleware checks cache before the handler, reducing DB queries. For Redis-backed caching, use apicache with ioredis adapter. This pattern is simple but lacks fine-grained invalidation—use it for coarse-grained caching.

const express = require('express');
const apicache = require('apicache');
const app = express();

// Use Redis as cache store
const cache = apicache.options({ redisClient: redisClient }).middleware;

app.get('/api/products', cache('5 minutes'), async (req, res) => {
  const products = await Product.find();
  res.json(products);
});

app.listen(3000);

Redis OM: Object Mapping for Node.js

Redis OM (Object Mapping) simplifies working with Redis hashes and JSON. It provides a declarative schema, automatic serialization, and querying. Instead of manually converting objects to Redis hashes, define a schema and use RedisOMRepository methods like save, findById, and search. It supports indexing and full-text search via RediSearch. This is useful for caching complex objects (e.g., user profiles) without writing boilerplate. However, Redis OM adds overhead and is best for applications that treat Redis as a primary data store or need rich queries. For simple key-value caching, raw ioredis is lighter. Use Redis OM when you need structured data with search capabilities.

import { Client, Entity, Schema, Repository } from 'redis-om';

const client = new Client();
await client.open('redis://localhost:6379');

class User extends Entity {}
const schema = new Schema(User, {
  name: { type: 'string' },
  email: { type: 'string' },
  age: { type: 'number' },
});

const repository = new Repository(schema, client);

const user = await repository.save({ name: 'Alice', email: 'alice@example.com', age: 30 });
const found = await repository.fetch(user.entityId);
console.log(found.name); // 'Alice'

node-redis vs ioredis: Choosing the Right Client

Both node-redis (official) and ioredis are mature Redis clients. node-redis v4+ is a complete rewrite with promise support, built-in cluster, and sentinel. ioredis is community-driven, battle-tested, and offers a richer API (e.g., pipelining, transactions, Lua scripting). Performance is similar. Choose ioredis if you need advanced features like auto-reconnection, custom commands, or cluster/sentinel with minimal config. Choose node-redis if you prefer official support and simpler API. For most production apps, ioredis is the go-to due to its robustness. Both support TLS, authentication, and connection pooling. Test both with your workload; the difference is marginal.

// ioredis
const Redis = require('ioredis');
const redis = new Redis({ host: 'localhost', port: 6379 });

// node-redis
const { createClient } = require('redis');
const client = createClient({ url: 'redis://localhost:6379' });
await client.connect();

// Both support async/await
await redis.set('key', 'value');
await client.set('key', 'value');

Read-Through and Write-Through Cache Patterns

Read-through and write-through patterns shift cache management to the data layer. In read-through, the cache loads data from the database on miss and returns it. In write-through, writes go to both cache and database synchronously. These patterns ensure cache consistency but add latency on writes. Implement read-through with a cache-aside wrapper that fetches from DB on miss. Write-through requires atomic updates: write to cache first, then DB (or vice versa with compensation). Use write-through for data that must be immediately consistent (e.g., user sessions). For high-write scenarios, consider write-behind (async) to avoid blocking. Both patterns simplify application code but require careful error handling.

class CacheThrough {
  constructor(cache, db) {
    this.cache = cache;
    this.db = db;
  }

  async get(key) {
    let value = await this.cache.get(key);
    if (!value) {
      value = await this.db.find(key);
      if (value) await this.cache.set(key, value);
    }
    return value;
  }

  async set(key, value) {
    await this.cache.set(key, value);
    await this.db.save(key, value);
  }
}

// Usage
const through = new CacheThrough(redis, db);
await through.set('user:1', { name: 'Bob' });
const user = await through.get('user:1');

Redis Stack: JSON and Search Capabilities

Redis Stack extends Redis with modules: RedisJSON, RediSearch, RedisTimeSeries, and RedisBloom. RedisJSON allows storing and querying JSON documents natively, with commands like JSON.GET, JSON.SET, and JSON.ARRAPPEND. RediSearch enables full-text search, faceted search, and aggregation. This is powerful for caching complex objects with search requirements. For example, cache product catalog as JSON and search by name or category. Redis Stack is ideal when you need both caching and search without a separate search engine. However, it adds memory overhead and complexity. Use it when your caching layer also needs query capabilities beyond key-value.

import { createClient } from 'redis';

const client = createClient();
await client.connect();

// Store JSON
await client.json.set('product:1', '$', {
  name: 'Widget',
  price: 9.99,
  tags: ['gadget', 'tool']
});

// Retrieve
const product = await client.json.get('product:1', { path: '$.name' });
console.log(product); // ['Widget']

// Search (requires RediSearch index)
await client.ft.create('idx:products', {
  '$.name': { type: 'TEXT' },
  '$.price': { type: 'NUMERIC' }
});
const results = await client.ft.search('idx:products', 'Widget');