SurrealDB server cache invalidation versus client SDK cache control

Answer

SurrealDB does not automatically purge cached query results when the underlying data changes; a server restart (or clearing the connection pool) is required to guarantee a fresh result. The client SDK has no cache‑control API, but you can force a cache miss by altering the query text (e.g., adding a changing placeholder).

Confirmed facts

• The CACHE clause stores query results in server memory for the lifetime of the connection or until the server process ends.
• The stable release provides no REFRESH or UNCACHE command and the SDK does not expose any cache‑control method; it merely forwards the query string to the server.

Likely explanation

In the current implementation cache entries are invalidated only when the server’s internal query plan cache is cleared, which effectively happens on a server restart or when the connection pool is flushed. Data mutations alone do not trigger eviction, so stale reads can persist until the server is restarted.

Steps to verify behavior

1. Start a SurrealDB instance with debug logging enabled for the cache subsystem (if available).
2. Run an identical CACHED query twice and note the log entries (first miss, second hit).
3. Insert or update a row that affects the query result.
4. Repeat the same query and check whether the log shows a hit (stale) or miss (invalidated).
5. Restart the server and run the query again; a miss after restart confirms that restart clears the cache.

To confirm whether a mutation triggers eviction, you need to enable server‑side cache‑level logging. Please let me know if you can activate those logs so the hit/miss behavior can be observed directly.