Cache Invalidation Strategies - Learning Module

Loading content...

0/246

Cache Versioning

When the Shape of Data Changes

Imagine you've cached user data with this structure:

{ "id": "123", "name": "Alice", "email": "alice@example.com" }

Now you deploy a new version that expects:

{ "id": "123", "fullName": "Alice Smith", "email": "alice@example.com", "verified": true }

What happens to the old cached entries?

They're still valid data—but in the wrong format. Your new code tries to access fullName and gets undefined. It checks verified and crashes because Boolean logic on undefined behaves unexpectedly. Even worse, if you cache the new format, old instances of your service (still running during deployment) might write the old format back, corrupting your cache.

This is the cache versioning problem: how do you manage cached data when its structure changes, not just its values?

What You Will Learn

By the end of this page, you will understand how to design and implement cache versioning strategies. You'll learn version encoding approaches, migration patterns for gradual rollouts, and techniques for maintaining cache integrity across deployments.

Why Cache Versioning Matters

Cache versioning becomes critical when any of these conditions exist:

1. Rolling Deployments: During deployment, multiple versions of your service run simultaneously. Old and new versions read and write the same cache. Without versioning, they can corrupt each other's entries.

2. Schema Evolution: Business requirements change. Fields are added, renamed, removed, or restructured. Cached data in the old format must be handled gracefully.

3. Serialization Format Changes: Switching from JSON to Protocol Buffers, or changing compression algorithms, makes old cached data unreadable.

4. A/B Testing and Feature Flags: Different user groups might receive different data shapes. Caching without version awareness can serve wrong data to wrong groups.

5. Multi-Region Deployments: Regions update at different times. A cache warm-up in one region shouldn't break another region running older code.

Cache Corruption Scenarios Without Versioning
Scenario	Problem	User Impact
Rolling deployment	Old server reads new format, fails to parse	Errors, degraded experience
Schema field added	New server reads old format, missing required field	Logic errors, incorrect behavior
Schema field renamed	Both old and new servers write conflicting formats	Data inconsistency, flickering UI
Serialization change	New server can't deserialize old format	Complete cache miss, load on backend
Feature flag split	User A receives data cached by User B's code path	Wrong feature variant shown

The Deployment Window Problem

In a rolling deployment with 100 instances updating over 10 minutes, you have a 10-minute window where old and new code coexist. Any cache entry written by old code can be read by new code, and vice versa. Without versioning, every deployment is a potential cache corruption event.

Version Encoding Strategies

There are three primary approaches to encoding version information in cached data. Each has different tradeoffs for complexity, performance, and flexibility.

Key Prefix Versioning

Include the version in the cache key itself. Different versions use different key namespaces.

Pattern: {version}:{entity}:{id} → v2:user:123

Advantages:

Simple to implement
Complete isolation between versions (no read conflicts)
Easy to reason about
Cache inspection tools show version clearly

Disadvantages:

Doubles memory during transitions (both versions cached)
Cold cache on version change (all entries miss)
Must update all cache keys when version changes
No gradual migration—binary switch

key-prefix-versioning.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
/**
 * Key Prefix Versioning
 * 
 * Cache keys include a version prefix, ensuring complete
 * isolation between schema versions.
 */
 
// Version is typically a constant in your codebase
const CACHE_SCHEMA_VERSION = 'v3';
 
class KeyPrefixVersionedCache {
    constructor(
        private cache: CacheClient,
        private version: string = CACHE_SCHEMA_VERSION,
    ) {}
 
    /**
     * Build versioned cache key
     */
    private buildKey(baseKey: string): string {
        return `${this.version}:${baseKey}`;
    }
 
    async get<T>(key: string): Promise<T | null> {
        const versionedKey = this.buildKey(key);
        const raw = await this.cache.get(versionedKey);
        return raw ? JSON.parse(raw) : null;
    }
 
    async set<T>(key: string, value: T, ttlSeconds: number): Promise<void> {
        const versionedKey = this.buildKey(key);
        await this.cache.setex(versionedKey, ttlSeconds, JSON.stringify(value));
    }
 
    async delete(key: string): Promise<void> {
        const versionedKey = this.buildKey(key);
        await this.cache.del(versionedKey);
    }
 
    /**
     * Clear all entries for a specific version (useful for cleanup)
     */
    async clearVersion(version: string): Promise<void> {
        const pattern = `${version}:*`;
        const keys = await this.cache.keys(pattern);
        if (keys.length > 0) {
            await this.cache.del(...keys);
        }
    }
 
    /**
     * Migrate from old version: read from old, write to new
     * Useful for warming new version's cache
     */
    async migrateEntry<T>(
        key: string,
        oldVersion: string,
        transform: (old: unknown) => T,
        ttlSeconds: number,
    ): Promise<T | null> {
        const oldKey = `${oldVersion}:${key}`;
        const raw = await this.cache.get(oldKey);
        
        if (!raw) return null;
        
        const oldData = JSON.parse(raw);
        const newData = transform(oldData);
        
        await this.set(key, newData, ttlSeconds);
        return newData;
    }
}
 
// Usage across deployments:
// v1: { name: "Alice" }
// v2: { name: "Alice", verified: false }
// v3: { fullName: "Alice", verified: false }
 
const cache = new KeyPrefixVersionedCache(redis, 'v3');
 
// New code writes to v3 namespace
await cache.set('user:123', { fullName: 'Alice', verified: false }, 3600);
 
// Old code (v2) writes to v2 namespace - no conflict
// await v2Cache.set('user:123', { name: 'Alice', verified: false }, 3600);
 
// Each reads only their own namespace - no corruption

Version Encoding Strategy Comparison
Strategy	Key Isolation	Memory Efficiency	Migration Path	Complexity
Key Prefix	Complete	Low (doubles during transition)	Cold cache	Low
Envelope	None	High	Gradual	Medium
Type Discriminator	None	High	Gradual	Medium

Migration Patterns for Gradual Rollouts

Version changes in production rarely happen instantaneously. During rolling deployments, A/B tests, or canary releases, multiple versions coexist. Migration patterns help manage this transition period gracefully.

migration-patterns.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
/**
 * Cache Migration Patterns
 * 
 * Strategies for handling version transitions during
 * rolling deployments and gradual rollouts.
 */
 
// ============================================
// Pattern 1: Read-Migrate-Write
// ============================================
 
/**
 * On cache read, if old version detected:
 * 1. Migrate to current version
 * 2. Write migrated version back (async)
 * 3. Return migrated data
 * 
 * Gradually migrates cache as entries are accessed.
 */
class ReadMigrateWriteCache<T> {
    constructor(
        private cache: CacheClient,
        private currentVersion: number,
        private migrator: (data: unknown, version: number) => T,
    ) {}
 
    async get(key: string): Promise<T | null> {
        const raw = await this.cache.get(key);
        if (!raw) return null;
 
        const { version, data } = JSON.parse(raw);
 
        if (version === this.currentVersion) {
            return data as T;
        }
 
        // Migrate
        const migrated = this.migrator(data, version);
 
        // Write back asynchronously (fire-and-forget)
        this.writeVersion(key, migrated).catch(() => {});
 
        return migrated;
    }
 
    private async writeVersion(key: string, data: T): Promise<void> {
        const ttl = await this.cache.ttl(key);
        const remainingTtl = Math.max(60, ttl);
        await this.cache.setex(key, remainingTtl, JSON.stringify({
            version: this.currentVersion,
            data,
        }));
    }
}
 
// ============================================
// Pattern 2: Version Tolerance (Read Any, Write New)
// ============================================
 
/**
 * Accept reads from multiple versions (within tolerance window),
 * but always write in current version.
 * 
 * Useful when migration logic is complex or versions differ subtly.
 */
class VersionTolerantCache<T> {
    constructor(
        private cache: CacheClient,
        private currentVersion: number,
        private toleratedVersions: Set<number>,
        private normalizers: Map<number, (data: unknown) => T>,
    ) {}
 
    async get(key: string): Promise<T | null> {
        const raw = await this.cache.get(key);
        if (!raw) return null;
 
        const { version, data } = JSON.parse(raw);
 
        // Reject unknown versions
        if (!this.toleratedVersions.has(version)) {
            console.warn(`Rejecting cache entry with unknown version ${version}`);
            await this.cache.del(key); // Remove corrupt entry
            return null;
        }
 
        // Normalize to current format
        const normalizer = this.normalizers.get(version);
        return normalizer ? normalizer(data) : data as T;
    }
 
    async set(key: string, data: T, ttlSeconds: number): Promise<void> {
        await this.cache.setex(key, ttlSeconds, JSON.stringify({
            version: this.currentVersion,
            data,
        }));
    }
}
 
// Setup for version 3, tolerating 2 and 3
const userCache = new VersionTolerantCache<User>(
    cache,
    3,                          // Current version
    new Set([2, 3]),            // Tolerated versions
    new Map([
        [2, (data: unknown) => migrateV2ToV3(data as UserV2)],
        [3, (data: unknown) => data as User],
    ]),
);
 
// ============================================
// Pattern 3: Write-Behind Migration
// ============================================
 
/**
 * Actively migrate cache entries in background,
 * independent of user requests.
 * 
 * Useful for large caches or when you want
 * migration complete before old code is fully removed.
 */
class BackgroundCacheMigrator {
    constructor(
        private cache: CacheClient,
        private fromVersion: number,
        private toVersion: number,
        private migrator: (data: unknown) => unknown,
    ) {}
 
    async migrateAllEntries(keyPattern: string, batchSize: number = 100): Promise<MigrationStats> {
        const stats: MigrationStats = {
            scanned: 0,
            migrated: 0,
            skipped: 0,
            failed: 0,
        };
 
        let cursor = '0';
        do {
            // Scan for matching keys
            const [nextCursor, keys] = await this.cache.scan(
                cursor,
                'MATCH', keyPattern,
                'COUNT', batchSize.toString()
            );
            cursor = nextCursor;
 
            // Process batch
            await Promise.all(keys.map(async (key) => {
                stats.scanned++;
                try {
                    const migrated = await this.migrateEntry(key);
                    if (migrated) {
                        stats.migrated++;
                    } else {
                        stats.skipped++;
                    }
                } catch (error) {
                    stats.failed++;
                    console.error(`Failed to migrate ${key}:`, error);
                }
            }));
 
            // Rate limit to avoid overloading cache
            await this.sleep(100);
        } while (cursor !== '0');
 
        return stats;
    }
 
    private async migrateEntry(key: string): Promise<boolean> {
        const raw = await this.cache.get(key);
        if (!raw) return false;
 
        const { version, data } = JSON.parse(raw);
 
        // Skip if already migrated
        if (version >= this.toVersion) {
            return false;
        }
 
        // Skip if too old (not supported)
        if (version < this.fromVersion) {
            await this.cache.del(key);
            return false;
        }
 
        // Migrate and write back
        const migrated = this.migrator(data);
        const ttl = await this.cache.ttl(key);
        
        await this.cache.setex(key, Math.max(60, ttl), JSON.stringify({
            version: this.toVersion,
            data: migrated,
        }));
 
        return true;
    }
 
    private sleep(ms: number): Promise<void> {
        return new Promise(resolve => setTimeout(resolve, ms));
    }
}
 
interface MigrationStats {
    scanned: number;
    migrated: number;
    skipped: number;
    failed: number;
}
 
// ============================================
// Pattern 4: Dual-Write During Transition
// ============================================
 
/**
 * Write to both old and new version keys during transition.
 * Old code reads old key, new code reads new key.
 * Removed after deployment complete.
 */
class DualWriteCache {
    constructor(
        private cache: CacheClient,
        private oldVersion: string,
        private newVersion: string,
        private inTransition: boolean = true,
    ) {}
 
    async set<T>(key: string, data: T, ttlSeconds: number): Promise<void> {
        const promises = [];
 
        // Always write to new format
        promises.push(
            this.cache.setex(
                `${this.newVersion}:${key}`,
                ttlSeconds,
                JSON.stringify(data)
            )
        );
 
        // During transition, also write old format
        if (this.inTransition) {
            const oldFormatData = this.convertToOldFormat(data);
            promises.push(
                this.cache.setex(
                    `${this.oldVersion}:${key}`,
                    ttlSeconds,
                    JSON.stringify(oldFormatData)
                )
            );
        }
 
        await Promise.all(promises);
    }
 
    private convertToOldFormat<T>(data: T): unknown {
        // Convert new format to old format for backward compatibility
        // Implementation depends on your schema differences
        return data;
    }
}

Choosing a Migration Pattern

•Read-Migrate-Write — Best for hot data with high read frequency. Migration happens naturally as data is accessed. Cold entries stay in old format until accessed or expired.
•Version Tolerance — Best when you want strict control over which versions are allowed. Good for security-sensitive data where old formats might have vulnerabilities.
•Write-Behind Migration — Best for complete migration before removing old code paths. Ensures no old-format entries remain after transition period.
•Dual-Write — Best for zero-downtime transitions where old and new code must coexist with zero coordination. Memory-expensive but safest.

Schema Design for Forward-Compatible Caching

The best way to handle version migrations is to avoid breaking changes in the first place. By designing cached data schemas with forward compatibility in mind, many version transitions become seamless.

Principles for Forward-Compatible Schemas:

•New fields should be optional with defaults — Adding a field shouldn't break old readers. Old code ignores unknown fields; new code provides defaults for missing fields.
•Never rename fields, only add aliases — Keep old field, add new field pointing to same data. Deprecate old field in future version.
•Use extensible enums with unknown handling — New enum values shouldn't crash old code. Include 'UNKNOWN' handling in switch statements.
•Avoid removing fields without deprecation period — Mark fields deprecated in version N, remove in version N+2, giving time and warnings.
•Prefer additive changes over transformative — Add new representations alongside old ones, don't transform in place.

forward-compatible-schema.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
/**
 * Forward-Compatible Schema Design
 * 
 * Example of designing cached schemas that gracefully
 * handle version evolution without breaking changes.
 */
 
// ============================================
// BAD: Breaking change requiring migration
// ============================================
 
// Version 1
interface UserBadV1 {
    name: string;  // Full name
    email: string;
}
 
// Version 2 - BREAKING: renamed field
interface UserBadV2 {
    fullName: string;  // Renamed from 'name'
    email: string;
}
// This BREAKS old code that expects 'name'
// This BREAKS new code reading old entries with 'name'
 
 
// ============================================
// GOOD: Non-breaking evolution
// ============================================
 
// Version 1
interface UserGoodV1 {
    name: string;
    email: string;
}
 
// Version 2 - COMPATIBLE: added fields
interface UserGoodV2 {
    name: string;      // Keep for backward compatibility
    fullName?: string; // Optional new field (alias for richness)
    email: string;
    verified?: boolean; // Optional with implicit default (false)
}
 
// Version 3 - COMPATIBLE: more fields, deprecation notice
interface UserGoodV3 {
    /** @deprecated Use fullName instead */
    name: string;      // Still present but deprecated
    fullName?: string;
    email: string;
    verified?: boolean;
    /** 
     * Added in V3. Old entries won't have this.
     * Default: 'en-US'
     */
    locale?: string;
}
 
/**
 * Reader that handles all versions gracefully
 */
class ForwardCompatibleReader {
    read(raw: unknown): NormalizedUser {
        const data = raw as Record<string, unknown>;
        
        return {
            fullName: (data.fullName as string) || (data.name as string) || 'Unknown',
            email: (data.email as string) || '',
            verified: (data.verified as boolean) ?? false,  // Default false
            locale: (data.locale as string) ?? 'en-US',     // Default en-US
        };
    }
}
 
interface NormalizedUser {
    fullName: string;
    email: string;
    verified: boolean;
    locale: string;
}
 
 
// ============================================
// Extensible Enums with Unknown Handling
// ============================================
 
enum UserStatusBad {
    ACTIVE = 'ACTIVE',
    SUSPENDED = 'SUSPENDED',
}
// Adding DELETED in new version breaks old code!
 
enum UserStatusGood {
    ACTIVE = 'ACTIVE',
    SUSPENDED = 'SUSPENDED',
    DELETED = 'DELETED',     // Added in V2
    ARCHIVED = 'ARCHIVED',   // Added in V3
}
 
function handleUserStatus(status: string): void {
    const knownStatus = status as UserStatusGood;
    
    switch (knownStatus) {
        case UserStatusGood.ACTIVE:
            // Handle active
            break;
        case UserStatusGood.SUSPENDED:
            // Handle suspended
            break;
        case UserStatusGood.DELETED:
            // Handle deleted
            break;
        case UserStatusGood.ARCHIVED:
            // Handle archived
            break;
        default:
            // IMPORTANT: Handle unknown statuses gracefully
            // This allows old code to handle new status values
            console.warn(`Unknown status: ${status}, treating as ACTIVE`);
            // Handle as default case
            break;
    }
}
 
 
// ============================================
// Versioned Writer with Compatibility Markers
// ============================================
 
const SCHEMA_VERSION = 3;
 
interface VersionedEntry<T> {
    schemaVersion: number;
    writtenBy: string;  // Service/version that wrote this
    data: T;
}
 
function writeWithVersion<T>(data: T): VersionedEntry<T> {
    return {
        schemaVersion: SCHEMA_VERSION,  // Current schema version
        writtenBy: `user-service-v2.3.1`, // Helps debugging
        data,
    };
}
 
// When reading, check schemaVersion to decide handling
function readVersioned<T>(entry: VersionedEntry<unknown>): T {
    if (entry.schemaVersion > SCHEMA_VERSION) {
        // Entry from future version - be cautious
        console.warn(`Reading entry from newer schema ${entry.schemaVersion}`);
        // Try to read anyway, forward-compat design should allow it
    }
    
    return entry.data as T;
}

Protocol Buffers and Avro

For schemas that require strict forward and backward compatibility, consider using Protocol Buffers or Apache Avro. These formats encode schema evolution rules directly and reject incompatible changes at compile time. The upfront investment pays off for long-lived systems with complex schemas.

Version Cleanup and Maintenance

Version management isn't complete without cleanup. Old version code paths, migration logic, and stale cached data accumulate as tech debt. A deliberate cleanup strategy keeps your caching system maintainable.

Version Cleanup Checklist

•Define deprecation timeline — When you add version N+1, schedule removal of version N-1 handling (skip one version for safety).
•Monitor old version reads — Instrument your cache to count reads of each version. When old version reads drop to zero, it's safe to remove handling.
•Run background purge jobs — Periodically scan for entries in deprecated versions and delete them. Better: let TTL naturally expire them.
•Remove migration code after transition — The read-migrate-write code for V1→V2 can be removed once V1 entries are gone.
•Document version history — Maintain a changelog of cache schema versions, what changed, and when deprecated. Essential for debugging.
•Test version compatibility in CI — Verify that current code can read old versions and that new writes are in expected format.

version-monitoring.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
/**
 * Version Monitoring and Cleanup
 */
 
class VersionMonitoringCache {
    private versionReadCounts = new Map<number, number>();
    
    constructor(
        private cache: CacheClient,
        private metrics: MetricsClient,
    ) {}
 
    async get<T>(key: string): Promise<T | null> {
        const raw = await this.cache.get(key);
        if (!raw) return null;
 
        const { version, data } = JSON.parse(raw);
        
        // Track version reads
        this.trackVersionRead(version);
        
        return data as T;
    }
 
    private trackVersionRead(version: number): void {
        // Increment local counter
        const current = this.versionReadCounts.get(version) || 0;
        this.versionReadCounts.set(version, current + 1);
        
        // Emit metric for monitoring/alerting
        this.metrics.increment('cache.version.read', {
            version: version.toString(),
        });
    }
 
    /**
     * Get version distribution statistics
     */
    getVersionStats(): Map<number, number> {
        return new Map(this.versionReadCounts);
    }
 
    /**
     * Check if it's safe to remove handling for a version
     */
    async isVersionDeprecatable(version: number): Promise<{
        safe: boolean;
        readsLastDay: number;
        recommendation: string;
    }> {
        // Query metrics backend for recent reads
        const readsLastDay = await this.metrics.querySum(
            'cache.version.read',
            { version: version.toString() },
            '24h'
        );
 
        if (readsLastDay === 0) {
            return {
                safe: true,
                readsLastDay: 0,
                recommendation: `Version ${version} has had 0 reads in 24h. Safe to remove.`,
            };
        }
 
        if (readsLastDay < 10) {
            return {
                safe: false,
                readsLastDay,
                recommendation: `Version ${version} has ${readsLastDay} reads. Consider waiting for natural TTL expiration.`,
            };
        }
 
        return {
            safe: false,
            readsLastDay,
            recommendation: `Version ${version} still has ${readsLastDay} reads. Not safe to remove yet.`,
        };
    }
}
 
/**
 * Automated cleanup job for deprecated versions
 */
async function runVersionCleanupJob(
    cache: CacheClient,
    deprecatedVersions: number[],
    keyPattern: string,
): Promise<CleanupResult> {
    const result: CleanupResult = {
        scanned: 0,
        deleted: 0,
        preserved: 0,
        errors: 0,
    };
 
    const deprecatedSet = new Set(deprecatedVersions);
    let cursor = '0';
 
    do {
        const [nextCursor, keys] = await cache.scan(cursor, 'MATCH', keyPattern, 'COUNT', '100');
        cursor = nextCursor;
 
        for (const key of keys) {
            result.scanned++;
            try {
                const raw = await cache.get(key);
                if (!raw) continue;
 
                const { version } = JSON.parse(raw);
 
                if (deprecatedSet.has(version)) {
                    await cache.del(key);
                    result.deleted++;
                } else {
                    result.preserved++;
                }
            } catch (error) {
                result.errors++;
            }
        }
    } while (cursor !== '0');
 
    console.log(`Cleanup complete: ${result.deleted} deleted, ${result.preserved} preserved`);
    return result;
}
 
interface CleanupResult {
    scanned: number;
    deleted: number;
    preserved: number;
    errors: number;
}
 
interface MetricsClient {
    increment(metric: string, tags: Record<string, string>): void;
    querySum(metric: string, tags: Record<string, string>, window: string): Promise<number>;
}

Summary: Cache Versioning

Cache versioning is essential for maintaining cache integrity across schema changes, deployments, and gradual rollouts. The right versioning strategy depends on your deployment model, migration needs, and tolerance for complexity.

Key Takeaways

•Version encoding matters — Key prefix gives isolation, envelope allows gradual migration, and type discriminators provide type safety. Choose based on your migration needs.
•Migration patterns enable smooth transitions — Read-migrate-write, version tolerance, write-behind, and dual-write each suit different deployment scenarios.
•Design for forward compatibility — Optional new fields with defaults, avoiding renames, and handling unknown values prevent most breaking changes.
•Monitor version distribution — Track which versions are being read to know when it's safe to remove old handling code.
•Plan for cleanup — Set deprecation timelines, run purge jobs, and remove migration code once transitions complete.
•Test version compatibility — Include version compatibility tests in CI to catch breaking changes before deployment.

What's next:

We've covered the three main cache invalidation strategies: time-based expiration, event-based invalidation, and cache versioning. The final page addresses what happens despite our best efforts—dealing with stale data. How do you detect, measure, and mitigate the impact of stale cached data in production?

Page Complete

You now understand cache versioning: the encoding strategies, migration patterns, forward-compatible schema design, and cleanup practices. These techniques ensure your cache remains consistent and correct as your data schemas evolve.