Redis + Node.js Integration Guide

Redis has been the standard for caching for years. It works great until it doesn't, and then you're debugging at 2am wondering why your app is throwing weird connection errors.

The node-redis client has improved a lot, especially since v4. The Redis documentation covers the basics but somehow misses all the stuff that breaks in production.

Basic connection setup

I'm running node-redis v4.something - way better than the callback nightmare of v3. Still has its moments though.

import { createClient } from 'redis';

const client = createClient({
  url: process.env.REDIS_URL || 'redis://localhost:6379',
  socket: {
    connectTimeout: 10000,   // Default timeout killed us in AWS
    keepAlive: true,         
    family: 4               // Docker + IPv6 = bad time
  }
});

client.on('error', (err) => {
  console.error('Redis connection failed:', err);
});

client.on('reconnecting', () => {
  console.log('Redis reconnecting...');
});

await client.connect();

That 10 second timeout saved me during our last deployment. All connections were timing out with the default setting - network was just slightly slower than expected. Bumped it up and the errors stopped. Might have been coincidence but I'm not changing it back.

But getting one connection to work is just the beginning. Once you have multiple users hitting your app simultaneously, that single connection becomes a bottleneck. Connection pooling becomes critical.

Connection pools (because one connection isn't enough)

Connection pools sound optional until you get real traffic and everything falls apart. One connection works fine for local development, but we started getting ECONNRESET errors once we had like 30 concurrent users.

// This kills performance under load
const sharedClient = createClient({ url: process.env.REDIS_URL });

// Better - use a proper pool library like generic-pool
import genericPool from 'generic-pool';

const pool = genericPool.createPool({
  create: () => {
    const client = createClient({ url: process.env.REDIS_URL });
    return client.connect().then(() => client);
  },
  destroy: (client) => client.quit()
}, {
  min: 2,
  max: 8
});

// Get a connection when needed
const client = await pool.acquire();
try {
  const result = await client.get('some-key');
  return result;
} finally {
  pool.release(client);
}

Without pooling, you're creating new connections for every request. Works fine until traffic picks up. Generic-pool is what I use for this.

Security basics

Redis security was terrible in early versions - no auth by default. Now you can use ACLs and TLS, but lots of people still run Redis with default settings. The Redis security checklist covers the basics.

const secureClient = createClient({
  username: 'app-user',    
  password: process.env.REDIS_PASSWORD,
  socket: {
    tls: true,             
    rejectUnauthorized: true
  }
});

Create a dedicated user for your app with minimal permissions. The default Redis user has admin access which you don't want.

Security matters, but so does availability. If your single Redis instance can't handle the load, you'll need to think about horizontal scaling.

Clustering (when one Redis isn't enough)

Redis clustering splits your data across multiple Redis instances. Sounds great until you realize it's eventually consistent, which means your data might be slightly out of sync between nodes.

const cluster = createCluster({
  rootNodes: [
    { host: 'redis-1.internal', port: 6379 },
    { host: 'redis-2.internal', port: 6379 },
    { host: 'redis-3.internal', port: 6379 }
  ]
});

cluster.on('nodeError', (error, address) => {
  console.error(`Node ${address} is being a problem:`, error);
});

Redis cluster doesn't guarantee strong consistency. Data might be slightly different between nodes, especially during network partitions. Spent one late night debugging disappearing user sessions - turned out the cluster was rebalancing during a network issue. Session got written to one node but another node didn't see it for 30+ seconds.

Pipelining

Node-redis v4+ does automatic pipelining, which batches commands sent in the same tick. Actually works well and makes things faster.

// These get batched automatically
const [user, session] = await Promise.all([
  client.get('user:123'),
  client.hGetAll('session:abc')
]);

One of those features that actually works as advertised.

Handling Redis failures

Redis will fail. Network issues happen. When Redis is down, don't let it take your entire app with it.

async function getCachedData(key) {
  try {
    return await client.get(key);
  } catch (error) {
    console.warn('Redis is being difficult, falling back to database');
    return await database.get(key);  // Slower but reliable
  }
}

Always have a fallback. Cache failures should slow things down, not break everything.

Beyond basic caching, Redis has some advanced features that can be really useful or cause headaches. Here's what matters in production.

Distributed locking

Distributed locking prevents race conditions when multiple app instances are running. Without it, you might process payments twice or send duplicate emails. Happens more than you'd think.

// Simple lock that works
async function withLock(key, callback, timeout = 10000) {
  const lockKey = `lock:${key}`;
  const acquired = await client.set(lockKey, '1', { NX: true, PX: timeout });
  
  if (acquired !== 'OK') {
    throw new Error('Could not acquire lock');
  }
  
  try {
    return await callback();
  } finally {
    await client.del(lockKey);
  }
}

// Use it like this
await withLock('payment:123', async () => {
  // Only one server can run this at a time
  return processPayment(123);
});

That timeout is crucial. Without it, crashed processes leave locks forever. Found this out the hard way when our payment processor died and left a bunch of orders stuck because the lock never expired. Customer support was not happy. There's fancier stuff like Redlock but honestly I've never needed it.

Pub/Sub messaging

Redis pub/sub works well for simple messaging between services. Just remember that if a service is down when you send a message, that message disappears forever. Messages get lost if nobody's listening.

// Publisher (sends messages)
await publisher.publish('user-events', JSON.stringify({
  type: 'user_registered',
  userId: 123,
  email: 'user@example.com'
}));

// Subscriber (receives messages) - needs separate connection
subscriber.on('message', (channel, message) => {
  const event = JSON.parse(message);
  if (event.type === 'user_registered') {
    sendWelcomeEmail(event.email);
  }
});

await subscriber.subscribe('user-events');

Keep it simple. If you need guaranteed delivery, use Redis Streams instead of pub/sub, or consider message queues like RabbitMQ or Apache Kafka.

Redis Streams

Redis Streams are like pub/sub but messages don't disappear if nobody's listening. More reliable but more complex to set up. Similar to Apache Kafka but built into Redis.

// Add to stream
await client.xAdd('events', '*', {
  userId: '123',
  action: 'login',
  timestamp: Date.now().toString()
});

// Read from stream (consumer group)
const messages = await client.xReadGroup(
  'mygroup', 'consumer1',
  [{ key: 'events', id: '>' }],
  { COUNT: 10, BLOCK: 1000 }
);

Streams are worth it if you need guaranteed message processing, but the setup is more involved than pub/sub. The Redis Streams tutorial explains the concepts better than most documentation.

Session storage

Redis works well for session storage - it's fast and all your app instances can access the same session data. Better than storing sessions in a database.

// Simple session storage
const sessionId = crypto.randomUUID();

// Store session data with 24 hour expiration
await client.hSet(`session:${sessionId}`, {
  userId: '123',
  createdAt: Date.now().toString(),
  lastSeen: Date.now().toString()
});
await client.expire(`session:${sessionId}`, 86400);

// Get session data
const session = await client.hGetAll(`session:${sessionId}`);

Use Redis hashes for sessions - you can store multiple fields and update them individually. More efficient than storing JSON strings.

That covers the main Redis features you'll actually use in production.