Cache Monitoring
Monitor query cache performance and manage cached entries from the admin console.
Atlas caches query results in-memory so that identical queries return instantly within the TTL. Cache keys are scoped by SQL, connection, organization, and user claims — so RLS-filtered queries and multi-tenant deployments never leak cached data across boundaries.
Prerequisites
- Atlas server running (
bun run dev) - Caching is enabled by default — no configuration needed to start
- Admin role for cache management endpoints
How It Works
- When
executeSQLruns a query, Atlas builds a cache key from four components:- SQL text (trimmed)
- Connection ID (which datasource)
- Org ID (multi-tenant isolation)
- User claims (RLS context — e.g.,
role: "admin"vsrole: "member")
- The key is a SHA-256 hash of these components, so different orgs or RLS contexts never share cached results
- On a cache hit, the stored result is returned instantly (0ms query duration, marked
cached: truein audit logs) - On a cache miss, the query runs against the database, and the result is stored in the cache for the configured TTL
Cache Key Scoping
Cache keys include all four components, ensuring strict isolation:
| Component | Purpose |
|---|---|
| SQL text | Same query = same key |
| Connection ID | Different datasources never share cache |
| Org ID | Multi-tenant isolation (even for identical SQL) |
| User claims | RLS-aware — different claim sets produce different keys |
Claim keys are sorted alphabetically before hashing, so key insertion order doesn't affect the cache key.
A query like SELECT * FROM orders with role: "sales" produces a different cache key than the same query with role: "admin". This ensures RLS-filtered results are never served to users with different access levels.
Admin Cache Management
The admin console provides a cache management UI at /admin/cache with real-time stats and a flush button.
Stats Endpoint
GET /api/v1/admin/cache/statsReturns:
| Field | Description |
|---|---|
enabled | Whether caching is active |
hits | Total cache hits |
misses | Total cache misses |
hitRate | Hit rate (0–1) |
missRate | Miss rate (0–1) |
entryCount | Current cached entries |
maxSize | Maximum capacity |
ttl | TTL in milliseconds |
Flush Endpoint
POST /api/v1/admin/cache/flushClears all cached entries. Returns the count of flushed entries. The cache is also automatically flushed on config reload to prevent stale results from outdated settings.
Troubleshooting
Cache not reducing query latency
Cause: Cache keys include user claims. If every request has unique claims (e.g., a timestamp), every query is a cache miss.
Fix: Ensure RLS claims contain only stable values like org_id or role, not request-specific data.
Cache appears stale after schema changes
Cause: The cache is not automatically invalidated when the database schema changes — only when the Atlas config file changes.
Fix: Flush the cache via POST /api/v1/admin/cache/flush or the admin console after schema changes.
Hit rate is very low
Cause: The maxSize may be too small for your query diversity, or the TTL is too short.
Fix: Increase ATLAS_CACHE_MAX_SIZE and/or ATLAS_CACHE_TTL. Monitor stats via GET /api/v1/admin/cache/stats.
See Also
- Cache Configuration — Environment variables,
atlas.config.tssettings, and external cache backends - Configuration — Cache config options in
atlas.config.ts - Environment Variables —
ATLAS_CACHE_*variables - Admin Console — Cache stats and flush UI