Cache Configuration

Atlas caches query results in-memory with tenant-isolated, claim-scoped cache keys. This page covers operator-level configuration: environment variables, config file settings, and plugging in an external cache backend.

For cache monitoring, stats, and flush operations, see Cache Monitoring.

Configuration

Environment Variables

Config File

// atlas.config.ts
export default defineConfig({
  cache: {
    enabled: true,       // default: true
    ttl: 300_000,        // 5 minutes in ms
    maxSize: 1000,       // max cached entries
  },
});

See Configuration for full details.

External Cache Backend (Redis)

Plugins can replace the default in-memory LRU cache with an external backend (e.g., Redis) by implementing the PluginCacheBackend interface from @useatlas/plugin-sdk:

import type { PluginCacheBackend, PluginCacheEntry } from "@useatlas/plugin-sdk";

const redisCacheBackend: PluginCacheBackend = {
  get(key: string): PluginCacheEntry | null { /* ... */ },
  set(key: string, entry: PluginCacheEntry): void { /* ... */ },
  delete(key: string): boolean { /* ... */ },
  flush(): void { /* ... */ },
  stats() { /* return { hits, misses, entryCount, maxSize, ttl } */ },
};

Return cacheBackend from your plugin object and Atlas will use it instead of the built-in LRU. Only one plugin cache backend is supported per server — the first plugin with a cacheBackend wins.

If the plugin backend fails to initialize at startup, Atlas logs the error and continues with the built-in LRU cache.

See Plugin Authoring Guide for building custom plugins.

Troubleshooting

Cache disabled but queries still appear cached

Cause: A plugin is providing a cache backend that ignores the enabled flag.

Fix: Check your plugin configuration. Remove or disable the cache backend plugin.

External backend connection failures

Cause: The Redis (or other external) cache backend is unreachable.

Fix: Atlas falls back to the built-in LRU cache when the plugin backend fails to initialize. Check your Redis connection string and network connectivity. Review server logs for cache backend initialization errors.

See Also

• Cache Monitoring — Admin console stats, flush operations, and cache key scoping details
• Configuration — Cache config options in atlas.config.ts
• Environment Variables — ATLAS_CACHE_* variables
• Plugin Authoring Guide — Building a custom cache backend plugin