From 8e2bf60fa76b91de6d80a4dc6720ff7f7b5f0880 Mon Sep 17 00:00:00 2001 From: Marcelo Soares Date: Mon, 18 May 2026 22:35:20 -0300 Subject: [PATCH] feat: Document the global cache fallback during development --- docs/06-concepts/08-caching.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/06-concepts/08-caching.md b/docs/06-concepts/08-caching.md index 89c3ffff..71bc4281 100644 --- a/docs/06-concepts/08-caching.md +++ b/docs/06-concepts/08-caching.md @@ -1,6 +1,6 @@ # Caching -Accessing the database can be expensive for complex queries or if you need to run many different queries for a specific task. Serverpod makes it easy to cache frequently requested objects in the memory of your server. Any object can be cached, including primitive types (int, String, DateTime, Duration, ByteData, UuidValue), lists, maps, and serializable models. Objects can be stored in the Redis cache if your Serverpod is hosted across multiple servers in a cluster. +Accessing the database can be expensive for complex queries or if you need to run many different queries for a specific task. Serverpod makes it easy to cache frequently requested objects in the memory of your server. Any object can be cached, including primitive types (`int`, `String`, `DateTime`, `Duration`, `ByteData`, `UuidValue`), lists, maps, and serializable models. Objects can be stored in the Redis cache if your Serverpod is hosted across multiple servers in a cluster. :::info Objects must be serializable to be cached. Non-serializable objects will throw an error when attempting to cache them. Most Dart types are serializable, including primitives, collections, and custom objects with `toJson`/`fromJson` methods. All objects that can be used with endpoints or the database are supported. @@ -30,10 +30,14 @@ Future getUserData(Session session, int userId) async { } ``` -In total, there are three caches where you can store your objects. Two caches are local to the server handling the current session, and one is distributed across the server cluster through Redis. There are two variants for the local cache, one regular cache, and a priority cache. Place objects that are frequently accessed in the priority cache. +In total, there are three caches where you can store your objects. Two caches are local to the server handling the current session, and one is distributed across the server cluster through Redis. There are two variants for the local cache: one regular cache, and a priority cache. Place objects that are frequently accessed in the priority cache. Depending on the type and number of objects that are cached in the global cache, you may want to specify custom caching rules in Redis. This is currently not handled automatically by Serverpod. +:::info +During development, you can run and test uses of the global cache on your code without depending on a running Redis server. If the server runs on `development`/`test` run mode and the Redis cache is configured, but not available, the global cache will fall back to an isolated in-memory cache. +::: + ### Caching primitive objects To cache primitive objects, simply call the `put` method with the object. For the `get`, specify the object type as the generic parameter, just like for `SerializableModel` objects: