Implementation:Promptfoo Promptfoo Cache Migration
| Knowledge Sources | |
|---|---|
| Domains | Caching, Migration |
| Last Updated | 2026-02-14 07:45 GMT |
Overview
Concrete tool for migrating the promptfoo on-disk cache from the legacy cache-manager v4 format (multiple JSON files in diskstore directories) to the new keyv-file v7 format (single JSON file).
Description
⚠️ DEPRECATION WARNING: This entire module is scheduled for removal after 2026-04-01. See Heuristic:Promptfoo_Promptfoo_Warning_Deprecated_Cache_Migration for details.
The Cache_Migration module handles the one-time migration of cached API responses when users upgrade promptfoo. The old format stored entries as individual JSON files in diskstore-* directories, each containing expireTime, key, and val fields. The new format uses a single JSON file with a cache array of key-value pairs and an expires timestamp. The module includes a sunset date (2026-04-01) after which migration is skipped entirely and users start with a fresh cache.
Usage
This module is invoked automatically during application startup when the cache subsystem initializes. It should not typically be called directly by users.
Code Reference
Source Location
- Repository: Promptfoo_Promptfoo
- File: src/cacheMigration.ts
- Lines: 1-801
Signature
export async function migrateCacheIfNeeded(
cacheDir: string,
newCachePath: string,
): Promise<void>
Import
import { migrateCacheIfNeeded } from './cacheMigration';
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| cacheDir | string | Yes | Path to the cache directory containing old diskstore-* directories |
| newCachePath | string | Yes | Path where the new keyv-file cache will be written |
Outputs
| Name | Type | Description |
|---|---|---|
| (void) | Promise<void> | Resolves when migration completes or is skipped |
Usage Examples
import { migrateCacheIfNeeded } from './cacheMigration';
import { getConfigDirectoryPath } from './util/config/manage';
import path from 'path';
// Automatic migration during cache init
const configDir = getConfigDirectoryPath();
const cacheDir = path.join(configDir, 'cache');
const newCachePath = path.join(cacheDir, 'cache.json');
await migrateCacheIfNeeded(cacheDir, newCachePath);