DEV Community: Tochukwu Amaechina

Redis Caching Strategies for High-Performance APIs

Tochukwu Amaechina — Mon, 31 Aug 2026 16:12:29 +0000

When I first started thinking seriously about API performance, my instinct was simple:

If the database is slow, optimize the database.

Add indexes. Improve the query. Tune the connection pool.

And sometimes, that's exactly what you should do.

But eventually, you run into a different problem.

The database isn't necessarily slow.

You're just asking it the same question too many times.

Imagine an endpoint that returns product information.

GET /api/products/123

The product changes once every few hours, but the endpoint gets thousands of requests every minute.

Without caching, every request goes straight to PostgreSQL:

Request
   ↓
  API
   ↓
PostgreSQL
   ↓
Response

The database is doing the same work over and over again.

That's where Redis comes in.

The Simple Idea Behind Caching

Instead of asking the database every time, we store frequently requested data temporarily.

Request
   ↓
Redis
   ↓
  HIT ─────→ Response
   │
  MISS
   ↓
Database
   ↓
Redis
   ↓
Response

The first request pays the database cost.

The next requests don't.

In a Node.js API, a simple cache-aside implementation looks like this:

const key = `product:${productId}`;

const cached = await redis.get(key);

if (cached) {
  return JSON.parse(cached);
}

const product = await prisma.product.findUnique({
  where: { id: productId },
});

if (!product) {
  throw new Error("Product not found");
}

await redis.set(
  key,
  JSON.stringify(product),
  { EX: 300 }
);

return product;

That's the basic pattern:

Check Redis → cache miss → query database → store result → return.

Simple.

But this is where caching stops being just a performance optimization.

Because now we have two copies of the data.

And they can disagree.

The Stale Data Problem

Suppose Redis contains:

product:123
price: ₦45,000

Then someone updates the product:

Database
price: ₦50,000

Redis still contains:

₦45,000

If the cache has a five-minute TTL, users could receive the old price for another five minutes.

This is the real challenge with caching.

Making data fast to access is easy. Keeping it correct is harder.

That's why TTL alone isn't enough.

TTL vs Invalidation

TTL answers:

"How long should this cache entry exist?"

Invalidation answers:

"When should I remove it because the underlying data changed?"

For example:

await prisma.product.update({
  where: { id: productId },
  data: updateData,
});

await redis.del(`product:${productId}`);

Now the next request becomes a cache miss and retrieves the latest value from the database.

For many APIs, cache-aside + TTL + delete-on-write is a very practical starting point.

You don't need a complicated caching architecture on day one.

Then There's the Cache Stampede

Here's where things get interesting.

Imagine a popular cache entry expires:

product:123

At the exact same time, 1,000 requests arrive.

They all check Redis:

MISS
MISS
MISS
MISS
...

And suddenly all 1,000 requests hit PostgreSQL.

The cache that was supposed to protect the database has just created a database traffic spike.

This is commonly called a cache stampede or thundering herd.

For extremely hot keys, you can prevent this by allowing only one request to rebuild the cache while the others wait.

Redis can help here through distributed locking.

But you wouldn't want to introduce locking everywhere.

If a query takes 10ms, the complexity may not be worth it.

If rebuilding the cache takes several seconds under heavy traffic, it's a different conversation.

Optimize for the workload you actually have.

What Should You Cache?

This is probably the most important question.

I wouldn't cache something simply because Redis is available.

Good candidates usually have three characteristics:

Frequently requested
+
Expensive to retrieve
+
Safe to be slightly stale

For example:

Product details
Public profiles
Search results
Configuration
Reference data
Expensive aggregations

I'd be much more careful with:

Account balances
Payment state
Authorization decisions
Inventory
Transaction state

Especially in financial systems.

If a wallet contains ₦100,000 and Redis says ₦100,000 while the database says ₦70,000 after a transaction, using that cached value for a financial decision is dangerous.

Fast wrong data is still wrong data.

For critical state, the database should remain authoritative.

Your Cache Key Is Part of Your Architecture

A cache key isn't just a random string.

This:

is a terrible cache key.

This is better:

user:123

And in a multi-tenant system:

tenant:456:user:123

For filtered results:

products:category:phones:page:1

Every parameter that changes the response needs to be represented appropriately in the key.

Otherwise, you can end up returning the wrong cached response to the right request.

That's a correctness bug—not a performance bug.

Redis Should Accelerate Your System, Not Become Your System

One of the most important design decisions is what happens when Redis fails.

For a cache-aside architecture, I'd rather have:

Redis available
    ↓
Use cache

Redis unavailable
    ↓
Use database

The API might become slower.

But it remains functional.

That's a much better failure mode than:

Redis unavailable
    ↓
Entire API unavailable

If your application completely depends on Redis just to retrieve data that already exists in PostgreSQL, you've accidentally turned your cache into a critical dependency.

Measure the Difference

Finally, don't add Redis and declare victory.

Measure it.

Before caching:

Average latency: 400ms
P95 latency:     800ms
DB queries/sec:  2,000

After caching:

Average latency: 70ms
P95 latency:     150ms
DB queries/sec:  500
Cache hit rate:  85%

Now you have evidence.

The goal isn't to make Redis busy.

The goal is to make the entire system do less unnecessary work.

The Bigger Lesson

Redis isn't what makes an API fast.

Avoiding unnecessary work makes an API fast.

Redis is simply one of the tools that helps you do that.

The moment you introduce a cache, you're making a trade:

More memory
+
More complexity
+
Potentially stale data

in exchange for:

Lower latency
+
Less database load
+
Higher throughput
+
Better scalability

The best caching strategy isn't the one that puts the most data into Redis.

It's the one that eliminates the most unnecessary work while keeping the system correct.

That's the difference between simply using Redis and actually designing with Redis.

How I Stopped a Race Condition from Creating Free Money in My Wallet System

Tochukwu Amaechina — Wed, 03 Jun 2026 21:57:40 +0000

The Bug That Doesn't Show Up in Testing.
When I set out to build a production-grade wallet system, I expected the hard parts to be the database schema, the transaction logic, or the authentication layer.

What I didn't expect was that the most dangerous bug in the system would have nothing to do with wrong code - it would be about timing.

This is the story of a race condition that lets users spend money they don't have, why it's invisible until it hits production, and how Redis turned it into a non-issue.

What a Wallet System Actually Does
Before we get to the bug, a quick picture of the system. A wallet holds a balance. Users can:

Credit - add funds
Debit - spend funds
Transfer - move funds to another user
Reverse - undo a transaction
Every operation reads the current balance, validates it, and writes a new transaction record. Simple enough. The problem hides in that gap between reading and writing.

The Race Condition
Here's the scenario. A user has ₦5,000 in their wallet. They're on a slow connection, so they tap "Pay" twice. Two HTTP requests hit the server within milliseconds of each other. Both are trying to debit ₦3,000.

Without any concurrency protection, this is what happens:

Request A → reads balance: ₦5,000
Request B → reads balance: ₦5,000

Request A → ₦5,000 - ₦3,000 = ₦2,000 ✓ writes transaction
Request B → ₦5,000 - ₦3,000 = ₦2,000 ✓ writes transaction
Both requests read ₦5,000. Both pass the balance check. Both write a successful debit. The user just spent ₦6,000 from a ₦5,000 wallet - and the system called both transactions successful.

This isn't a theoretical edge case. Under any real concurrent load, this happens. And the worst part: it never shows up in testing, because your test runner doesn't fire two real HTTP requests at the same millisecond.

Why a Database Transaction Doesn't Save You
The instinct here is to reach for a database transaction. Wrap the whole thing in BEGIN / COMMIT and let Postgres sort it out.

The problem is that the race happens before the database transaction begins. Both requests read the balance from the database (or worse, from a cache), both pass the validation check in application code, and then both open their database transactions. The damage is already done.

You need a lock at the application layer, before the read even happens.

The Fix: Distributed Locking with Redis
The solution is to ensure that no two operations on the same wallet can run at the same time. Before any balance operation begins, it must claim exclusive access. If another operation already holds the claim, it retries until the lock is free, or gives up after a timeout.

This is a distributed lock, and Redis is the right tool for it. Here's the implementation:

// src/utils/lock.utils.ts
import { randomUUID } from "crypto";
import redisClient from "../services/redis.service";

const LOCK_TTL_MS = 10_000;
const LOCK_RETRY_COUNT = 50;
const LOCK_RETRY_DELAY_MS = 100;

const RELEASE_SCRIPT = `
  if redis.call("GET", KEYS[1]) == ARGV[1] then
    return redis.call("DEL", KEYS[1])
  else
    return 0
  end
`;

const acquireLock = async (key: string): Promise<string | null> => {
  const token = randomUUID();
  const result = await redisClient.set(key, token, "PX", LOCK_TTL_MS, "NX");
  return result === "OK" ? token : null;
};

export const withLock = async <T>(userId: string, fn: () => Promise<T>): Promise<T> => {
  const key = `wallet:lock:${userId}`;
  let token: string | null = null;

  for (let attempt = 0; attempt <= LOCK_RETRY_COUNT; attempt++) {
    token = await acquireLock(key);
    if (token) break;
    await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS));
  }

  if (!token) throw new Error("Could not acquire lock — resource is busy");

  try {
    return await fn();
  } finally {
    await redisClient.eval(RELEASE_SCRIPT, 1, key, token);
  }
};

Let's break down each decision.

SET key token PX 10000 NX
This is a single atomic Redis command that does three things at once:

NX — only set the key if it does not already exist
PX 10000 — expire the key after 10 seconds
The value is a unique token (UUID), not just 1 or "locked"
The atomicity of SET NX is the core guarantee. There is no gap between "check if key exists" and "set the key" — it's one operation. Two requests racing to acquire the same lock cannot both succeed.

Retry logic
Rather than immediately rejecting a request when the lock is held, the implementation retries up to 50 times with a 100ms delay between each attempt - giving it up to 5 seconds to acquire the lock before giving up. This handles brief overlaps gracefully without dropping legitimate requests.

The TTL
The 10-second expiry is a safety net. If the application crashes mid-operation and fails to release the lock, it will expire automatically. Without this, one crash would lock that user's wallet forever.

The Lua script on release
This is where most implementations get it wrong. A naive release looks like this:

await redisClient.del(key); // ❌ dangerous
Here's why that's broken: imagine a slow operation acquires the lock, but takes longer than 10 seconds. The TTL expires. A second operation acquires the lock. Now the first operation finishes and calls del - it just released the second operation's lock, not its own. The guarantee is broken.

The Lua script fixes this by checking the token before deleting:

if redis.call("GET", KEYS[1]) == ARGV[1] then
  return redis.call("DEL", KEYS[1])
else
  return 0
end

Because Lua scripts execute atomically in Redis, the check-and-delete is a single uninterruptible operation. You can only release a lock you actually own.

The withLock wrapper
Rather than exposing raw acquireLock / releaseLock functions and trusting every caller to use them correctly, the implementation wraps the entire pattern in a higher-order function:

// src/services/wallet.service.ts
export const debitWallet = async (userId: string, amount: number): Promise<Transaction> => {
  return await withLock(userId, async () => {
    const wallet = await prisma.wallet.findUnique({ where: { userId } });

    if (!wallet || wallet.balance.lessThan(amount)) {
      throw new Error("Insufficient balance");
    }

    // create transaction, update balance...
    return transaction;
  });
};

The finally block inside withLock ensures the lock is always released, even if the operation throws. A lock that leaks on error is as bad as no lock at all.

Preventing Deadlocks on Transfers
A transfer touches two wallets - sender and receiver. If two transfers run simultaneously in opposite directions (A→B and B→A), they can deadlock: each holds one lock and waits for the other indefinitely.

The fix is to always acquire locks in the same order, regardless of who is sending to whom. We sort the user IDs before acquiring:

export const withMultiLock = async <T>(userIds: string[], fn: () => Promise<T>): Promise<T> => {
  const sortedIds = [...new Set(userIds)].sort();
  const keys = sortedIds.map((id) => `wallet:lock:${id}`);
  const tokens: string[] = [];

  try {
    for (const key of keys) {
      let token: string | null = null;
      for (let attempt = 0; attempt <= LOCK_RETRY_COUNT; attempt++) {
        token = await acquireLock(key);
        if (token) break;
        await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS));
      }
      if (!token) throw new Error("Could not acquire lock — resource is busy");
      tokens.push(token);
    }
    return await fn();
  } finally {
    await Promise.all(keys.map((key, i) => releaseLock(key, tokens[i])));
  }
};

// In transfer service:
const result = await withMultiLock([senderId, receiver.id], async () => {
  // both wallets locked — safe to proceed
});

If A→B and B→A both arrive at the same time, both will sort to [A, B] and try to acquire A's lock first. One wins, the other waits. No deadlock.

The Full System
The distributed lock is one layer in a larger stack. The complete wallet engine includes:

Idempotency - Idempotency-Key header on credit and debit prevents duplicate transactions on network retries, backed by a 24-hour Redis TTL
Webhook delivery with retry - BullMQ queue, 4 attempts, exponential backoff (2s base), per-attempt audit trail
Balance caching - 60-second Redis TTL, invalidated on every write
Token blacklisting - SHA-256 hashed JWTs stored in Redis with matching expiry, making logout actually secure
Cursor-based pagination - transaction history that scales
Full test suite - 103 tests, all mocked, no database required to run.
Built with TypeScript, Express, Prisma, PostgreSQL, and Redis (ioredis). Deployed on Render with a GitHub Actions CI/CD pipeline.

Why This Matters
Race conditions in financial systems are not exotic. They're the default outcome when you don't explicitly prevent them. Most wallet tutorials never mention it. Most wallet implementations in production have it.

The fix isn't complicated - but you have to know to look for it.

If you're building anything that touches money, check your balance reads. If there's no lock between the read and the write, the race condition is already there.

Open for Collaboration
This project is open source and actively welcoming contributors. Whether you want to add a feature, improve test coverage, or spot something that could be done better - PRs are open.

Check out the CONTRIBUTING.md for how to get set up and where to send your changes.

GitHub: https://github.com/tochi27/Wallet_System.git

Live API + Swagger: https://wallet-system-api-16cv.onrender.com/api-docs