Caching in Wheels 4.0: Actions, Queries, Partials, and Invalidation

[bpamiri]

Your blog's home page runs eight queries. One of them — the "most popular posts this month" sidebar — is a GROUP BY that takes 400ms and hasn't changed in three weeks. Every visitor pays for it again. That's the caching problem, and Wheels 4.0 has four tools for it.

The catch: they're four different tools, not one cache with four front doors. This post is a source-grounded field guide to all of them, and to the part nobody likes — invalidation.

Read: https://blog.wheels.dev/posts/caching-in-wheels-4

What the post covers

The thing that breaks everyone first. cacheActions, cachePages, cachePartials, cacheQueries, and cacheImages all default to false in development and true everywhere else. So caches(), includePartial(cache=...), renderView(cache=...), and findAll(cache=...) silently do nothing on your laptop — then behave differently in production. The one exception is cacheQueriesDuringRequest, which is request-scoped and on even in dev.

Action caching. caches(actions="index,show", time=30) in config() caches the rendered response. static=true caches the whole page via cfcache and aborts the request before your before/after filters run on a hit — fast for public pages, dangerous for anything behind auth. appendToKey="session.userId" varies the key by a runtime value (and throws Wheels.KeyNotFound if that var is missing).

Query caching — the two-cache problem. This is where most confusion lives:

• Request-level (cacheQueriesDuringRequest, in request.wheels[ModelName]) dedupes identical queries within one request. Always on. Bypass with reload=true.
• Cross-request (findAll(cache=N) + cacheQueries) hands a native cachedWithin timespan to the DB adapter — real engine-level query caching keyed on the SQL.

reload=true defeats the request-level one. It has nothing to do with cache=N. People mix these up constantly.

Partial + page caching. includePartial(cache=20) from a view, renderPartial(cache=...) / renderView(cache=...) from the controller — both gated on their settings, both using a double-checked lock so a cold cache doesn't trigger a thundering herd.

Invalidation reality. There is no public clearCache(key). clearCachableActions() only unregisters cachability — it does not evict already-cached content. Real invalidation is (1) expiry on the time you set and (2) a full ?reload=true, which re-inits the cache and flushes cfcache. Design your time values like they're the only invalidation you have, because they nearly are.

Sharp edges, all cited from source:

• Cache times are MINUTES, not seconds (cacheDatePart default "n"). cache=true is 60.
• The shared cache is bounded at maximumItemsToCache=5000 across all categories, with expired-only culling — when full and nothing's expired, new items are silently dropped. High-cardinality keys can quietly stop caching.
• Static page caching is a silent no-op on engines without cfcache (RustCFML).
• Cached non-simple values are deep-copied (Duplicate) on every read and write (simple values like rendered HTML are returned directly).

The post ties it together with a worked blog home-page example: action cache as the outer skin, findAll(cache=60) and includePartial(cache=20) speeding up the cold render underneath it.

For discussion

• How are you handling per-user content on otherwise-cacheable pages? Pull it client-side, or eat the per-user cache budget with appendToKey?
• Has anyone hit the 5000-item silent-drop ceiling in production, and how did you notice?
• Would a targeted clearCache(key) / model-callback-driven invalidation change how you cache? What would you want the API to look like?

Read the full post and let me know what's missing: https://blog.wheels.dev/posts/caching-in-wheels-4