diff --git a/docs/02-overview.md b/docs/02-overview.md index 37a40325..b6cdbee3 100644 --- a/docs/02-overview.md +++ b/docs/02-overview.md @@ -10,7 +10,7 @@ Serverpod is an open-source backend framework for Flutter applications written i - **Automatic code generation:** Serverpod analyzes your server code and automatically generates the client-side Dart API and data classes. Calling a remote endpoint becomes as simple as calling a local method. - **World-class logging:** Built-in logging and monitoring tools allow you to pinpoint exceptions and slow database queries through an easy-to-use interface. -- **Built-in caching:** High-performance, distributed caching is included. Any serializable model can be cached in memory on the server or distributed using Redis. +- **Built-in caching:** High-performance, distributed caching is included. Any object can be cached (primitives, lists, maps, and serializable models) in memory on the server or distributed using Redis. - **Easy-to-use ORM:** Serverpod provides an ORM that uses native Dart types and null-safety for database queries. You write Dart code instead of SQL, and Serverpod builds your PostgreSQL queries under the hood. The ORM has an intuitive Dart-first API for relations and joins. - **Database migrations:** A built-in migration system helps keep your database schema in sync as your project evolves. You can version schema changes and apply them easily during deployment. - **File uploads:** First-class support for file uploads to cloud storage or the database. Files can be stored in Amazon S3, Google Cloud Storage, or even in your PostgreSQL database. diff --git a/docs/06-concepts/08-caching.md b/docs/06-concepts/08-caching.md index 2fe38e6d..89c3ffff 100644 --- a/docs/06-concepts/08-caching.md +++ b/docs/06-concepts/08-caching.md @@ -1,6 +1,12 @@ # 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 serializable object can be cached. 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. +::: + +## Caching objects Caches can be accessed through the `Session` object. This is an example of an endpoint method for requesting data about a user: @@ -28,6 +34,39 @@ In total, there are three caches where you can store your objects. Two caches ar 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. +### 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: + +```dart +await session.caches.local.put('userCount', 17, lifetime: Duration(minutes: 5)); + +var count = await session.caches.local.get('userCount'); +``` + +For `DateTime` objects, it is recommended to always cache them as UTC. Otherwise, you may get unexpected results when retrieving the object from the cache. + +```dart +var lastUpdate = DateTime.now().toUtc(); + +await session.caches.local.put('lastUpdate', lastUpdate); + +// Retrieved `DateTime` object will always be in UTC. +var cached = await session.caches.local.get('lastUpdate'); +``` + +### Caching lists and collections + +Lists and collections can also be cached directly: + +```dart +var users = [UserData(name: 'Alice'), UserData(name: 'Bob')]; + +await session.caches.local.put('users', users); + +var cachedUsers = await session.caches.local.get>('users'); +``` + ### Cache miss handler If you want to handle cache misses in a specific way, you can pass in a `CacheMissHandler` to the `get` method. The `CacheMissHandler` makes it possible to store an object in the cache when a cache miss occurs.