Week 11: Caching & Performance

1. Why Cache & the Cache-Aside Pattern

A database query that takes 40ms is fine for one request and disastrous at 2,000 requests per second against the same row — the database, not your Express process, becomes the bottleneck. Caching sidesteps this by keeping a copy of expensive-to-compute data somewhere much faster to read than a database round trip, most commonly Redis, an in-memory data store that answers a key lookup in well under a millisecond.

The most common caching strategy for a REST API is cache-aside (also called lazy loading): your application code, not the database, owns the caching logic. On a read, check the cache first; on a hit, return the cached value and skip the database entirely; on a miss, query the database, write the result into the cache with an expiration, and return it. On a write, invalidate (delete) the cache key rather than trying to keep it in sync — the next read repopulates it.

GET /products/42
  -> cache.get("product:42")
     -> HIT:  return cached value                (fast path, no DB)
     -> MISS: value = db.query(...)
              cache.set("product:42", value, ttl)
              return value

PUT /products/42
  -> db.update(...)
  -> cache.delete("product:42")                  (never write-through the cache here)

The trade-off is a bounded staleness window: between a write and the next read that repopulates the cache, a client could theoretically read data that was just deleted, never written — but never stale, since the delete happens before the response is returned. A short TTL (time to live) also bounds how long any cache entry can drift from the database even if an invalidation is ever missed, which makes cache-aside forgiving of bugs in a way that keeping the cache perpetually in sync is not.

2. Caching with Redis in Express

ioredis is the most widely used Redis client for Node — it has solid TypeScript types and is also what BullMQ (Week 12) uses under the hood, so the connection you build this week is one you'll reuse next week. As with Prisma, create a single shared client rather than a new connection per request:

npm install ioredis
npm install -D @types/node

import { Redis } from "ioredis";

// One shared connection for the whole process, exactly like the
// PrismaClient singleton pattern from Week 4 -- creating a new
// Redis instance per request exhausts connections under load.
export const redis = new Redis(process.env.REDIS_URL ?? "redis://localhost:6379", {
  maxRetriesPerRequest: 3,
});

redis.on("error", (err) => {
  console.error("Redis connection error:", err);
});

With the client in place, a small helper wraps the cache-aside logic once so every route reuses it instead of re-implementing the get/miss/set dance by hand:

import { redis } from "./redis.js";

/**
 * Cache-aside helper: returns the cached value if present, otherwise
 * calls `loadFresh`, caches the result for `ttlSeconds`, and returns it.
 */
export async function getOrSetCache<T>(
  key: string,
  ttlSeconds: number,
  loadFresh: () => Promise<T>
): Promise<T> {
  const cached = await redis.get(key);
  if (cached !== null) {
    return JSON.parse(cached) as T;
  }

  const fresh = await loadFresh();
  // "EX" sets the TTL in seconds atomically with the write.
  await redis.set(key, JSON.stringify(fresh), "EX", ttlSeconds);
  return fresh;
}

export async function invalidateCache(key: string): Promise<void> {
  await redis.del(key);
}

import { Router } from "express";
import { prisma } from "../lib/prisma.js";
import { getOrSetCache, invalidateCache } from "../lib/cache.js";

export const productsRouter = Router();

productsRouter.get("/:id", async (req, res, next) => {
  try {
    const id = req.params.id;
    const product = await getOrSetCache(`product:${id}`, 60, () =>
      prisma.product.findUniqueOrThrow({ where: { id } })
    );
    res.json(product);
  } catch (err) {
    next(err);
  }
});

productsRouter.put("/:id", async (req, res, next) => {
  try {
    const id = req.params.id;
    const updated = await prisma.product.update({
      where: { id },
      data: req.body,
    });
    await invalidateCache(`product:${id}`); // never let a write leave a stale cache entry
    res.json(updated);
  } catch (err) {
    next(err);
  }
});

3. Connection Pooling for Prisma

Every database connection costs memory and setup time on the Postgres side, and Postgres caps the total it will accept (max_connections, often 100 by default). Prisma's client opens and manages its own pool of connections rather than opening one per query, and you control the pool size directly in the connection string:

DATABASE_URL="postgresql://user:pass@localhost:5432/mydb?connection_limit=10&pool_timeout=10"

connection_limit caps how many connections this single Prisma client will open; pool_timeout is how long a query waits for a free connection before throwing, in seconds. The right number isn't "as high as possible" — Prisma's own guidance is roughly num_physical_cpus * 2 + 1 per instance of your app as a starting point, then measure. If you run multiple instances of your API (which you will, starting in Week 14), each one opens its own pool of that size, so five instances at connection_limit=10 means up to 50 connections hitting Postgres — easy to exceed max_connections without realizing it.

import { PrismaClient } from "@prisma/client";

// A single shared client for the whole process -- this is the pool.
// Never call `new PrismaClient()` inside a request handler; each
// instance opens its own connection pool independently.
export const prisma = new PrismaClient({
  log: process.env.NODE_ENV === "development" ? ["query", "warn", "error"] : ["error"],
});

For serverless or high-instance-count deployments where dozens of short-lived processes would otherwise each open their own pool, the standard fix is a connection pooler like PgBouncer sitting between your app and Postgres, multiplexing many logical client connections onto a much smaller number of real database connections. This course's deployments (Week 14 onward) run a small, fixed number of long-lived Node processes, so a direct pool with a sane connection_limit is enough — but knowing PgBouncer exists is what saves you the day you scale past that.

4. Profiling & Fixing a Slow Endpoint

Never optimize a hunch — measure first. A simple timing middleware gives you a baseline for every route without touching route logic:

import type { Request, Response, NextFunction } from "express";

export function timing(req: Request, res: Response, next: NextFunction): void {
  const start = process.hrtime.bigint();

  res.on("finish", () => {
    const ms = Number(process.hrtime.bigint() - start) / 1_000_000;
    console.log(`${req.method} ${req.originalUrl} ${res.statusCode} ${ms.toFixed(1)}ms`);
  });

  next();
}

For load rather than single-request timing, a tool like autocannon hammers an endpoint with concurrent requests and reports latency percentiles:

npx autocannon -c 50 -d 10 http://localhost:3000/api/reports/summary

# Before any fix, on an endpoint that runs an unindexed aggregate query:
# Latency:   avg 412ms   p50 380ms   p99 610ms
# Req/sec:   avg 118

Once a route is confirmed slow, find out why before reaching for Redis. Postgres's EXPLAIN ANALYZE shows the actual query plan and where time is spent:

EXPLAIN ANALYZE
SELECT * FROM "Order" WHERE "customerId" = 'cus_123' ORDER BY "createdAt" DESC;

-- Before: Seq Scan on "Order"  (cost=0.00..8420.00 rows=50000)
--         Planning Time: 0.4 ms   Execution Time: 344.8 ms

A sequential scan across the whole table for a query that filters on customerId is the classic sign of a missing index. Adding one is usually a one-line Prisma schema change, and the improvement is dramatic because it turns an O(n) table scan into an O(log n) index lookup:

model Order {
  id         String   @id @default(cuid())
  customerId String
  createdAt  DateTime @default(now())
  // ...

  @@index([customerId, createdAt])
}

npx prisma migrate dev --name add_order_customer_index

# After adding the index and re-running EXPLAIN ANALYZE:
# Index Scan using Order_customerId_createdAt_idx
#         Execution Time: 3.1 ms

# Re-running autocannon against the same endpoint:
# Latency:   avg 24ms   p50 19ms   p99 61ms
# Req/sec:   avg 1,890

Only after the query itself is efficient does caching earn its keep — an index fix made every request faster and cheaper for the database; a cache on top of the same indexed query removes the database round trip entirely for repeat reads. Reaching for Redis first on an unindexed query hides the real problem behind a TTL instead of fixing it.

5. Hands-on Exercise

6. Knowledge Check

Four quick questions. Expand each to check your answer.