Redis caching tutorial in 45 minutes: cache-aside, write-through, write-behind

The bottom line

A working Redis cache plus three classic caching patterns (cache-aside, write-through, write-behind) implemented in Node.js is achievable in 45 minutes for a developer with Node.js 20+ installed and Docker or a local Redis install. This tutorial walks through installing Redis 8, connecting via redis-cli to confirm the server works, wiring up the official node-redis client (version 5.12.0 as of April 2026 ⁴ ), and implementing each of the three patterns with runnable code. Every command and code block traces to the official Redis documentation at redis.io/docs/latest. This is not a Redis Cluster or replication tutorial; the cache runs as a single instance on port 6379 ⁶ .

Redis is a single-threaded, in-memory key-value store; the official quick start uses SET, GET, HSET, and HGETALL as the canonical examples ² . The same primitives drive the three caching patterns this tutorial covers; the patterns differ only in WHEN the cache is read or written, not in which Redis commands are used.

Redis Cluster, Sentinel-based high availability, persistence-tuning (RDB vs AOF), and Pub/Sub are separate articles.

What you’ll build

The end state is a small Node.js application that talks to Redis as a cache in front of a slow data source (simulated with setTimeout to emulate a 200 ms database query). Three modules:

• cache-aside.js: read-through pattern; the application reads from cache, and on miss reads from the source, writes to cache, then returns.
• write-through.js: synchronous write pattern; the application writes to cache AND source in the same code path, source write blocking.
• write-behind.js: asynchronous write pattern; the application writes to cache immediately, and a background flush writes to the source.

Plus a small bench.js that compares cold and warm read latencies, demonstrating the cache hit ratio’s impact.

Prerequisites

Before starting, the reader needs:

• Node.js 20 or newer. Confirm with node --version. Node.js 22 LTS is the safer floor for greenfield projects in 2026.
• Redis 8 (or 7.x). Either a local install via Homebrew / apt, or a Docker container. Both paths covered in Step 1.
• A terminal. Terminal.app or iTerm on macOS, any Linux terminal, PowerShell or WSL on Windows.
• A code editor. VS Code, Cursor, or any editor with JavaScript syntax highlighting.

A Redis GUI (RedisInsight, Medis) is optional. This tutorial uses redis-cli because every Redis install ships it ⁷ .

Image: Redis official homepage (redis.io), used for editorial coverage of the Redis project this tutorial covers.

The mental model

A cache sits between an application and a slower source of truth (database, external API, computed result). The cache stores a subset of the source’s data in faster storage. Read requests check the cache first; a hit avoids the slow source. Write requests have to decide WHEN to update the cache relative to the source; that decision IS the caching pattern.

Three classic patterns describe the WHEN:

• Cache-aside (lazy loading): the application reads from the cache; on a miss, it reads from the source, populates the cache, and returns the value. Writes update the source and either invalidate the cache (delete the key) or update it in place. The cache and source can drift; the application explicitly manages the cache.
• Write-through: every write hits the cache AND the source synchronously, in the same code path. The cache and source are always consistent for written keys. Latency: the slow write blocks the application response. Most useful for write-heavy workloads where stale reads are unacceptable.
• Write-behind (write-back): writes go to the cache immediately; a background process flushes to the source asynchronously. Lowest write latency for the application; highest risk of data loss if the cache dies before the flush. Useful for high-throughput logging-style workloads where eventual durability is acceptable.

Redis’s primitives stay the same across all three: SET key value, GET key, DEL key, EXPIRE key seconds, plus the hash equivalents HSET, HGET, HGETALL ² . The pattern lives in the application code that calls them.

Step 1: Install Redis

Two paths; pick whichever fits the host machine. The official install docs cover all OS-specific paths ⁶ .

Docker (recommended for tutorials):

docker run -d --name redis-tutorial -p 6379:6379 redis:8

This pulls the official redis:8 image from Docker Hub and runs it in the background with port 6379 mapped to the host. Confirm:

docker ps | grep redis-tutorial

macOS (Homebrew):

brew install redis
brew services start redis

Ubuntu / Debian:

sudo apt update
sudo apt install redis-server
sudo systemctl enable --now redis-server

Confirm the server is reachable via redis-cli:

redis-cli ping

Expected response: PONG. If the response is Could not connect to Redis at 127.0.0.1:6379: Connection refused, the server isn’t running.

A second sanity check, mirroring the official quick start examples ² :

redis-cli SET bike:1 "Process 134"
redis-cli GET bike:1

Expected output: OK then "Process 134". The cache is alive.

Step 2: Set up the Node.js project

Create a new project directory:

mkdir redis-caching-tutorial
cd redis-caching-tutorial
npm init -y
npm pkg set type=module
npm install redis

The npm install redis command installs the official node-redis client; per the official Node.js client docs ³ , npm install redis is the canonical install command, and redis@5.12.0 is the latest version as of April 2026 ⁴ . npm pkg set type=module switches the project to ESM so the import statements below work without a build step.

Create a small db.js that simulates a slow data source:

// db.js — simulates a slow database with 200ms latency

const seed = new Map([
  [1, { id: 1, name: 'Alice Singh',   email: 'alice@example.com' }],
  [2, { id: 2, name: 'Bob Pereira',   email: 'bob@example.com'   }],
  [3, { id: 3, name: 'Carol Lee',     email: 'carol@example.com' }],
]);

export async function dbGetUser(id) {
  await new Promise((r) => setTimeout(r, 200));
  return seed.get(Number(id)) ?? null;
}

export async function dbPutUser(user) {
  await new Promise((r) => setTimeout(r, 200));
  seed.set(user.id, user);
  return user;
}

The 200 ms latency simulates a real database query; the in-memory Map keeps the example self-contained.

Also create a shared Redis client at client.js:

// client.js — single shared node-redis client

import { createClient } from 'redis';

const client = await createClient({ url: 'redis://localhost:6379' })
  .on('error', (err) => console.error('Redis Client Error', err))
  .connect();

export default client;

Per the official node-redis README the connection pattern is createClient followed by .connect(); the example above mirrors the README verbatim ⁴ .

Step 3: Cache-aside

Create cache-aside.js:

// cache-aside.js — read-through with explicit cache management

import client from './client.js';
import { dbGetUser, dbPutUser } from './db.js';

const TTL_SECONDS = 60;
const key = (id) => `user:${id}`;

export async function getUser(id) {
  // 1. Try the cache.
  const cached = await client.get(key(id));
  if (cached) {
    return { value: JSON.parse(cached), source: 'cache' };
  }

  // 2. Cache miss → hit the source.
  const user = await dbGetUser(id);
  if (!user) return { value: null, source: 'source' };

  // 3. Populate the cache for next time, with a TTL.
  await client.set(key(id), JSON.stringify(user), { EX: TTL_SECONDS });
  return { value: user, source: 'source' };
}

export async function updateUser(user) {
  // Write to source first; invalidate the cache afterwards.
  // Order matters: invalidating BEFORE the source write opens
  // a race where a concurrent reader can re-populate the cache
  // with the OLD value during the source write.
  const written = await dbPutUser(user);
  await client.del(key(user.id));
  return written;
}

Three deliberate choices worth flagging:

• TTL on every cache write. EX: 60 sets a 60-second expiration via the SET command’s expiration option. Without a TTL, stale entries can live forever in the cache; the application is one bug away from serving 2025 data in 2026.
• JSON serialisation. Redis stores strings; JavaScript objects need to be JSON.stringify-ed on write and JSON.parse-d on read. For deeply structured data, consider Redis hashes (HSET) instead; for simple key-value caches, strings are fine.
• Write order: source first, then invalidate. A common bug: invalidate the cache, then write the source. Between those two steps, a concurrent reader can fetch the OLD source value (the source write hasn’t landed yet) and re-populate the cache with the stale value. Invalidating AFTER the source write narrows the race window but doesn’t close it entirely; Redis’s own docs on caching patterns are worth reading for the full discussion of race conditions.

A small test driver test-cache-aside.js:

import { getUser, updateUser } from './cache-aside.js';
import client from './client.js';

await client.flushDb(); // start clean

const t0 = performance.now();
console.log(await getUser(1));   // cold: source
console.log('cold ms:', (performance.now() - t0).toFixed(0));

const t1 = performance.now();
console.log(await getUser(1));   // warm: cache
console.log('warm ms:', (performance.now() - t1).toFixed(0));

await updateUser({ id: 1, name: 'Alice S.', email: 'alice@example.com' });
console.log(await getUser(1));   // miss after invalidate

await client.quit();

Run it:

node test-cache-aside.js

Expected output: cold read ~200 ms (the simulated DB latency), warm read 1–5 ms (Redis on the loopback), and the post-update read shows a fresh source fetch.

Image: redis/redis official GitHub repository (github.com/redis/redis), used for editorial coverage of the Redis server project this tutorial installs.

Step 4: Write-through

Create write-through.js:

// write-through.js — synchronous cache + source writes

import client from './client.js';
import { dbGetUser, dbPutUser } from './db.js';

const TTL_SECONDS = 60;
const key = (id) => `user:${id}`;

export async function getUser(id) {
  // Same read path as cache-aside; nothing changes here.
  const cached = await client.get(key(id));
  if (cached) return { value: JSON.parse(cached), source: 'cache' };

  const user = await dbGetUser(id);
  if (!user) return { value: null, source: 'source' };
  await client.set(key(id), JSON.stringify(user), { EX: TTL_SECONDS });
  return { value: user, source: 'source' };
}

export async function putUser(user) {
  // Write-through: write to source AND cache in the same call.
  // The caller's promise only resolves after BOTH succeed.
  await dbPutUser(user);
  await client.set(key(user.id), JSON.stringify(user), { EX: TTL_SECONDS });
  return user;
}

The single line that turns cache-aside into write-through: instead of invalidating the cache after a source write, the application populates the cache with the new value. The cache and source stay in lockstep for any key the application has ever written.

Cost: every write pays the source’s latency before the application can move on. In this tutorial that’s 200 ms; in production it might be a 5 ms Postgres write or a 50 ms cross-region replication. The application’s write throughput is bounded by the source’s write throughput.

Use case fit: configuration data, user-profile updates, anything where a consistent read after write is required and write rate is moderate.

Step 5: Write-behind

Create write-behind.js:

// write-behind.js — async background flush to the source

import client from './client.js';
import { dbGetUser, dbPutUser } from './db.js';

const TTL_SECONDS = 60;
const FLUSH_QUEUE = 'flush:users';
const key = (id) => `user:${id}`;

export async function getUser(id) {
  const cached = await client.get(key(id));
  if (cached) return { value: JSON.parse(cached), source: 'cache' };
  const user = await dbGetUser(id);
  if (!user) return { value: null, source: 'source' };
  await client.set(key(id), JSON.stringify(user), { EX: TTL_SECONDS });
  return { value: user, source: 'source' };
}

export async function putUser(user) {
  // Write to cache immediately.
  await client.set(key(user.id), JSON.stringify(user), { EX: TTL_SECONDS });
  // Push the pending write onto a Redis list; a worker drains it.
  await client.rPush(FLUSH_QUEUE, JSON.stringify(user));
  return user;
}

// Background flusher. Run as a separate process in production.
export async function startFlusher({ batchSize = 10, idleMs = 500 } = {}) {
  // eslint-disable-next-line no-constant-condition
  while (true) {
    const items = [];
    for (let i = 0; i < batchSize; i++) {
      const item = await client.lPop(FLUSH_QUEUE);
      if (!item) break;
      items.push(JSON.parse(item));
    }
    if (items.length === 0) {
      await new Promise((r) => setTimeout(r, idleMs));
      continue;
    }
    for (const user of items) {
      try {
        await dbPutUser(user);
      } catch (err) {
        console.error('flush failed; re-queueing', err);
        await client.rPush(FLUSH_QUEUE, JSON.stringify(user));
      }
    }
  }
}

Two Redis primitives carry the pattern: RPUSH appends to a list, LPOP removes from the head. The combination implements a FIFO queue inside Redis; the flusher is a worker that drains the queue.

The trade-off is explicit. The application’s write returns almost immediately (a single Redis SET + RPUSH, both microsecond-scale on loopback). But if Redis crashes between the cache write and the source flush, the pending writes vanish (unless Redis is configured with AOF persistence at appendfsync always, which negates much of the latency win).

Production write-behind setups usually pair Redis with a durable queue (RabbitMQ, Kafka, AWS SQS) for the pending-writes log, leaving Redis for the cache itself. The single-process Redis-queue pattern above is fine for a tutorial; it is not the production shape.

Step 6: Measure cache hit impact

Create bench.js to compare cold vs warm reads with the cache-aside module:

import { getUser } from './cache-aside.js';
import client from './client.js';

await client.flushDb();

async function timed(label, fn) {
  const t0 = performance.now();
  const result = await fn();
  const ms = performance.now() - t0;
  console.log(`${label.padEnd(20)} ${ms.toFixed(1).padStart(7)} ms  (${result.source})`);
}

console.log('--- cold ---');
await timed('user 1', () => getUser(1));
await timed('user 2', () => getUser(2));
await timed('user 3', () => getUser(3));

console.log('--- warm ---');
await timed('user 1', () => getUser(1));
await timed('user 2', () => getUser(2));
await timed('user 3', () => getUser(3));

await client.quit();

Run with node bench.js. Typical output on a developer laptop:

--- cold ---
user 1                 203.4 ms  (source)
user 2                 201.8 ms  (source)
user 3                 202.1 ms  (source)
--- warm ---
user 1                   1.2 ms  (cache)
user 2                   0.9 ms  (cache)
user 3                   0.9 ms  (cache)

Two-hundred-fold improvement on warm reads. The number is artificial (the simulated 200 ms source dominates), but the ratio matches real-world deployments where a 30 ms Postgres query is cached behind a 0.3 ms Redis lookup.

Pattern selection

A short comparison table to consolidate:

Pattern	Consistency	Write latency	Failure mode
Cache-aside	Eventual; race window on concurrent reads	Cache invalidate only; source write is separate	Cache miss → degraded read latency; data safe
Write-through	Strong for written keys	Source latency + cache latency	Source down → write fails; cache stays warm
Write-behind	Eventual; depends on flush cadence	Cache write only; source flushed later	Redis down between write and flush → pending writes lost

Default to cache-aside for read-heavy workloads with moderate update frequency; switch to write-through when stale reads aren’t acceptable; reach for write-behind only when write throughput is the bottleneck and eventual durability is genuinely acceptable.

Image: redis/node-redis official GitHub repository (github.com/redis/node-redis), used for editorial coverage of the Node.js client this tutorial uses.

Things that commonly go wrong

A short list of issues that bite first-time Redis users:

• Connection refused on 6379: the server isn’t running. docker ps (Docker), brew services list (macOS), or systemctl status redis-server (Linux) confirms. Start the service.
• OOM command not allowed when used memory > 'maxmemory': Redis has hit its memory cap. Either increase maxmemory in redis.conf or set an eviction policy (maxmemory-policy allkeys-lru is a sensible default for cache use).
• Cache + source drift after a deploy: deploys often change the data schema. Cache keys carry no schema version; old serialised objects deserialise into the new app shape and crash. Solution: include a version prefix in keys (v2:user:1), and flush the previous version on deploy.
• MOVED errors: the connection landed on a Redis Cluster node that doesn’t own the key. Either use a cluster-aware client (node-redis supports cluster mode) or, for tutorials, stay on a single-node instance.
• Massive KEYS * in production: KEYS is O(N) and blocks Redis’s single thread. Use SCAN for any production key enumeration. Per the official redis-cli reference, the --scan flag is the safe way to enumerate keys from the CLI ⁷ .
• JSON parsing errors after a hot-reload: stale entries serialised with an old schema. FLUSHDB clears the current database; FLUSHALL clears all databases on the instance. Both are destructive; never run either in production.

What was deliberately skipped

This tutorial covers the smallest meaningful caching loop. A production Redis deployment also wires connection pooling (the official node-redis client handles this internally; other clients may not), persistence configuration (RDB snapshots, AOF append-only file), eviction policies aligned with the workload (allkeys-lru for cache, noeviction for queue), replication (Sentinel for HA, Cluster for sharding), memory budgeting (maxmemory and maxmemory-samples), and observability (INFO memory, INFO stats, SLOWLOG).

Pub/Sub, Streams, Lua scripting, server-side caching with client-side invalidation, RedisJSON / RediSearch modules, and Redis Cluster topology are separate articles.

Image: Redis official blog (redis.io/blog/), used for editorial coverage of the Redis project’s release announcements this tutorial cross-references.

Recap

Three caching patterns in three Node.js files, sharing the same Redis primitives. The mental model: cache-aside puts the cache-management logic in the application’s read path, write-through pays source latency on every write to keep cache and source in lockstep, write-behind pushes the source flush to a background worker for lowest write latency at the cost of durability. Redis’s SET, GET, DEL, RPUSH, and LPOP cover all three patterns; the official Redis data-structure-store quick start ² and the node-redis client docs ³ are the canonical companions; the node-redis repository ⁴ confirms redis@5.12.0 as the current release at writer-time.