Handling Schema Migrations for Cached Data

In this lesson, you will learn how to safely evolve the structure of your cached objects without triggering application-wide errors when your data schema changes.

When you update your Node.js application, you often modify the shape of the data stored in your cache. Unlike a database, which might have migration scripts, your cache often contains "stale" structures that no longer match your current code’s expectations. If you simply update your code to expect user.fullName instead of the old user.firstName and user.lastName, JSON.parse will succeed, but your application will crash when it attempts to access the missing fields.

To handle this, we implement versioned caching. By including a version field in the cached object itself, we can detect an outdated schema the moment we retrieve it from the store.

Implementing Versioned Schema Checks

The pattern involves wrapping your retrieval logic in a migration layer:

const CURRENT_SCHEMA_VERSION = 2;

async function getCachedUser(userId) {
  const rawData = await redis.get(`user:${userId}`);
  if (!rawData) return null;

  const user = JSON.parse(rawData);

  // If the version is outdated, perform an on-the-fly migration
  if (user.version !== CURRENT_SCHEMA_VERSION) {
    return migrateUserSchema(user);
  }

  return user;
}

function migrateUserSchema(oldUser) {
  // Transform the old structure to the new one
  const newUser = {
    id: oldUser.id,
    fullName: `${oldUser.firstName} ${oldUser.lastName}`,
    version: CURRENT_SCHEMA_VERSION
  };
  
  // Optionally update the cache with the new structure
  redis.set(`user:${oldUser.id}`, JSON.stringify(newUser));
  return newUser;
}

By using this approach, you treat the cache as "evolvable" rather than static. Instead of forcing a massive cache flush (which causes a performance spike as you repopulate data), the migration happens lazily—only for the specific records that are accessed. This allows you to deploy code changes smoothly without worrying about the incompatibility between your old cached entries and your new business logic.

Key Takeaway: Always tag cached objects with a version property to enable lazy migration, preventing runtime errors and avoiding the need for total cache flushes during schema updates.