| 1 |
:tocdepth: 4 |
| 2 |
|
| 3 |
Stores |
| 4 |
====== |
| 5 |
|
| 6 |
.. py:currentmodule:: litestar.stores |
| 7 |
|
| 8 |
|
| 9 |
When developing applications, oftentimes a simply storage mechanism is needed, for example when |
| 10 |
:doc:`caching response data</usage/caching>` or storing data for |
| 11 |
:ref:`server-side sessions <usage/middleware/builtin-middleware:Server-side sessions>`. In cases like these a |
| 12 |
traditional database is often not needed, and a simple key/value store suffices. |
| 13 |
|
| 14 |
Litestar provides several low level key value stores, offering an asynchronous interface to store data in a |
| 15 |
thread- and process-safe manner. These stores are centrally managed via a |
| 16 |
:class:`registry <litestar.stores.registry.StoreRegistry>`, allowing easy access throughout the whole application and |
| 17 |
third party integration (for example plugins). |
| 18 |
|
| 19 |
|
| 20 |
Built-in stores |
| 21 |
--------------- |
| 22 |
|
| 23 |
:class:`MemoryStore <litestar.stores.memory.MemoryStore>` |
| 24 |
A simple in-memory store, using a dictionary to hold data. This store offers no persistence and is not thread or multiprocess safe, |
| 25 |
but it is suitable for basic applications such as caching and has generally the lowest overhead. This is the default store used by |
| 26 |
Litestar internally. If you plan to enable :doc:`multiple web workers </reference/cli>` and you need inter-process communication |
| 27 |
across multiple worker processes, you should use one of the other non-memory stores instead. |
| 28 |
|
| 29 |
:class:`FileStore <litestar.stores.file.FileStore>` |
| 30 |
A store that saves data as files on disk. Persistence is built in, and data is easy to extract and back up. |
| 31 |
It is slower compared to in-memory solutions, and primarily suitable for situations when larger amounts of data |
| 32 |
need to be stored, is particularly long-lived, or persistence has a very high importance. Offers `namespacing`_. |
| 33 |
|
| 34 |
:class:`RedisStore <litestar.stores.redis.RedisStore>` |
| 35 |
A store backend by `redis <https://redis.io/>`_. It offers all the guarantees and features of Redis, making it |
| 36 |
suitable for almost all applications. Offers `namespacing`_. |
| 37 |
|
| 38 |
:class:`ValkeyStore <litestar.stores.valkey.ValkeyStore>` |
| 39 |
A store backed by `valkey <https://valkey.io>`_, a fork of Redis created as the result of Redis' license changes. |
| 40 |
Similarly to the RedisStore, it is suitable for almost all applications and supports `namespacing`_. |
| 41 |
At the time of writing, :class:`Valkey <valkey.asyncio.Valkey>` is equivalent to :class:`redis.asyncio.Redis`, |
| 42 |
and all notes pertaining to Redis also apply to Valkey. |
| 43 |
|
| 44 |
.. admonition:: Why not memcached? |
| 45 |
:class: info |
| 46 |
|
| 47 |
Memcached is not a supported backend, and will likely also not be added in the future. The reason for this is simply |
| 48 |
that it's hard to support memcached properly, since it's missing a lot of basic functionality like checking a key's |
| 49 |
expiry time, or something like Redis' `SCAN <https://redis.io/commands/scan/>`_ command, which allows to implement |
| 50 |
pattern-based deletion of keys. |
| 51 |
|
| 52 |
|
| 53 |
Interacting with a store |
| 54 |
------------------------ |
| 55 |
|
| 56 |
The most fundamental operations of a store are: |
| 57 |
|
| 58 |
- :meth:`get <.base.Store.get>`: To retrieve a stored value |
| 59 |
- :meth:`set <.base.Store.set>`: To set a value in the store |
| 60 |
- :meth:`delete <.base.Store.delete>`: To delete a stored value |
| 61 |
|
| 62 |
|
| 63 |
Getting and setting values |
| 64 |
++++++++++++++++++++++++++ |
| 65 |
|
| 66 |
|
| 67 |
.. literalinclude:: /examples/stores/get_set.py |
| 68 |
:language: python |
| 69 |
|
| 70 |
|
| 71 |
Setting an expiry time |
| 72 |
++++++++++++++++++++++ |
| 73 |
|
| 74 |
The :meth:`set <.base.Store.set>` method has an optional parameter ``expires_in``, allowing to specify a time after |
| 75 |
which a stored value should expire. |
| 76 |
|
| 77 |
|
| 78 |
.. literalinclude:: /examples/stores/expiry.py |
| 79 |
:language: python |
| 80 |
|
| 81 |
|
| 82 |
.. note:: |
| 83 |
It is up to the individual store to decide how to handle expired values, and implementations may differ. The |
| 84 |
:class:`redis based store <.redis.RedisStore>` for example uses Redis' native expiry mechanism to handle this, |
| 85 |
while the :class:`FileStore <.file.FileStore>` only deletes expired values when they're trying to be accessed, |
| 86 |
or explicitly deleted via the :meth:`delete_expired <.file.FileStore.delete_expired>` method. |
| 87 |
|
| 88 |
|
| 89 |
It is also possible to extend the expiry time on each access, which is useful for applications such as server side |
| 90 |
sessions or LRU caches: |
| 91 |
|
| 92 |
.. literalinclude:: /examples/stores/expiry_renew_on_get.py |
| 93 |
:language: python |
| 94 |
|
| 95 |
|
| 96 |
Deleting expired values |
| 97 |
####################### |
| 98 |
|
| 99 |
When using a :class:`MemoryStore <.memory.MemoryStore>` or :class:`FileStore <.file.FileStore>`, expired data won't be |
| 100 |
deleted automatically. Instead, it will only happen when the data is being accessed, or if this process is invoked |
| 101 |
explicitly via :meth:`MemoryStore.delete_expired <.memory.MemoryStore.delete_expired>` or |
| 102 |
:meth:`FileStore.delete_expired <.file.FileStore.delete_expired>` respectively. |
| 103 |
|
| 104 |
It's a good practice to call ``delete_expired`` periodically, to ensure the size of the stored values does not grow |
| 105 |
indefinitely. |
| 106 |
|
| 107 |
In this example, an :ref:`after_response <after_response>` handler is used to delete expired items at most every 30 |
| 108 |
second: |
| 109 |
|
| 110 |
.. literalinclude:: /examples/stores/delete_expired_after_response.py |
| 111 |
:language: python |
| 112 |
|
| 113 |
When using the :class:`FileStore <.file.FileStore>`, expired items may also be deleted on startup: |
| 114 |
|
| 115 |
|
| 116 |
.. literalinclude:: /examples/stores/delete_expired_on_startup.py |
| 117 |
:language: python |
| 118 |
|
| 119 |
|
| 120 |
.. note:: |
| 121 |
For the :class:`MemoryStore <.memory.MemoryStore>`, this is not needed as the data is simply stored in a dictionary. |
| 122 |
This means that every time a new instance of this store is created, it will start out empty. |
| 123 |
|
| 124 |
|
| 125 |
What can be stored |
| 126 |
++++++++++++++++++ |
| 127 |
|
| 128 |
Stores generally operate on :class:`bytes`; They accept bytes to store, and will return bytes. For convenience, the |
| 129 |
:meth:`set <.base.Store.set>` method also allows to pass in strings, which will be UTF-8 encoded before being stored. |
| 130 |
This means that :meth:`get <.base.Store.get>` will return bytes even when a string has been passed to |
| 131 |
:meth:`set <.base.Store.set>`. |
| 132 |
|
| 133 |
The reason for this limitation is simple: Different backends used to store the data offer vastly different encoding, |
| 134 |
storage, and (de)serialization capacities. Since stores are designed to be interchangeable, this means settling for a |
| 135 |
common denominator, a type that all backends will support. :class:`bytes` meet these requirements and make it possible |
| 136 |
to store a very wide variety of data. |
| 137 |
|
| 138 |
.. admonition:: Technical details |
| 139 |
|
| 140 |
:class:`MemoryStore <.memory.MemoryStore>` differs from this, because it does not do any encoding before storing |
| 141 |
the value. This means that it's technically possible to store arbitrary objects in this store, and get the same |
| 142 |
object back. However, this is not reflected in the store's typing, as the underlying :class:`Store <.base.Store>` |
| 143 |
interface does not guarantee this behaviour, and it is not guaranteed that |
| 144 |
:class:`MemoryStore <.memory.MemoryStore>` will always behave in this case. |
| 145 |
|
| 146 |
|
| 147 |
Namespacing |
| 148 |
+++++++++++ |
| 149 |
|
| 150 |
When stores are being used for more than one purpose, some extra bookkeeping is required to safely perform bulk |
| 151 |
operations such as :class:`delete_all <.base.Store.delete_all>`. If for example a |
| 152 |
:class:`RedisStore <.redis.RedisStore>` was used, simply issuing a `FLUSHALL <https://redis.io/commands/flushall/>`_ |
| 153 |
command might have unforeseen consequences. |
| 154 |
|
| 155 |
To help with this, some stores offer namespacing capabilities, allowing to build a simple hierarchy of stores. |
| 156 |
These come with the additional :meth:`with_namespace <.base.NamespacedStore.with_namespace>` method, which returns a |
| 157 |
new :class:`NamespacedStore <.base.NamespacedStore>` instance. Once a namespaced store is created, operations on it |
| 158 |
will only affect itself and its child namespaces. |
| 159 |
|
| 160 |
When using the :class:`RedisStore <.redis.RedisStore>`, this allows to reuse the same underlying |
| 161 |
:class:`Redis <redis.asyncio.Redis>` instance and connection, while ensuring isolation. |
| 162 |
|
| 163 |
.. note:: |
| 164 |
:class:`RedisStore <.redis.RedisStore>` uses the ``LITESTAR`` namespace by default; all keys created by this store, |
| 165 |
will use the ``LITESTAR`` prefix when storing data in redis. |
| 166 |
:meth:`RedisStore.delete_all <.redis.RedisStore.delete_all>` is implemented in such a way that it will only delete |
| 167 |
keys matching the current namespace, making it safe and side-effect free. |
| 168 |
|
| 169 |
This can be turned off by explicitly passing ``namespace=None`` to the store when creating a new instance. |
| 170 |
|
| 171 |
|
| 172 |
.. literalinclude:: /examples/stores/namespacing.py |
| 173 |
:language: python |
| 174 |
|
| 175 |
Even though all three stores defined here use the same Redis instance, calling ``delete_all`` on the ``cache_store`` |
| 176 |
will not affect data within the ``session_store``. |
| 177 |
|
| 178 |
Defining stores hierarchically like this still allows to easily clear everything, by simply calling |
| 179 |
:meth:`delete_all <.base.Store.delete_all>` on the root store. |
| 180 |
|
| 181 |
|
| 182 |
Managing stores with the registry |
| 183 |
--------------------------------- |
| 184 |
|
| 185 |
The :class:`StoreRegistry <litestar.stores.registry.StoreRegistry>` is a central place through which stores can be |
| 186 |
configured and managed, and can help to easily access stores set up and used by other parts of the application, Litestar |
| 187 |
internals or third party integrations. It is available throughout the whole application context via the |
| 188 |
:class:`Litestar.stores <litestar.app.Litestar>` attribute. |
| 189 |
|
| 190 |
It operates on a few basic principles: |
| 191 |
|
| 192 |
- An initial mapping of stores can be provided to the registry |
| 193 |
- Registered stores can be requested with :meth:`get <.registry.StoreRegistry.get>` |
| 194 |
- If a store has been requested that has not been registered yet, a store of that name will be created and registered |
| 195 |
using the `the default factory`_ |
| 196 |
|
| 197 |
|
| 198 |
.. literalinclude:: /examples/stores/registry.py |
| 199 |
:language: python |
| 200 |
|
| 201 |
|
| 202 |
This pattern offers isolation of stores, and an easy way to configure stores used by middlewares and other Litestar |
| 203 |
features or third party integrations. |
| 204 |
|
| 205 |
In the following example, the store set up by the |
| 206 |
:class:`RateLimitMiddleware <litestar.middleware.rate_limit.RateLimitMiddleware>` is accessed via the registry: |
| 207 |
|
| 208 |
.. literalinclude:: /examples/stores/registry_access_integration.py |
| 209 |
:language: python |
| 210 |
|
| 211 |
|
| 212 |
This works because :class:`RateLimitMiddleware <litestar.middleware.rate_limit.RateLimitMiddleware>` will request |
| 213 |
its store internally via ``app.stores.get`` as well. |
| 214 |
|
| 215 |
|
| 216 |
The default factory |
| 217 |
+++++++++++++++++++ |
| 218 |
|
| 219 |
The pattern above is made possible by using the registry's default factory; A callable that gets invoked |
| 220 |
every time a store is requested that hasn't been registered yet. It's similar to the ``default`` argument to |
| 221 |
:meth:`dict.get`. |
| 222 |
|
| 223 |
By default, the default factory is a function that returns a new |
| 224 |
:class:`MemoryStore <litestar.stores.memory.MemoryStore>` instance. This behaviour can be changed by supplying a |
| 225 |
custom ``default_factory`` method to the registry. |
| 226 |
|
| 227 |
To make use of this, a registry instance can be passed directly to the application: |
| 228 |
|
| 229 |
.. literalinclude:: /examples/stores/registry_default_factory.py |
| 230 |
:language: python |
| 231 |
|
| 232 |
The registry will now return the same :class:`MemoryStore <litestar.stores.memory.MemoryStore>` every time an undefined |
| 233 |
store is being requested. |
| 234 |
|
| 235 |
|
| 236 |
Using the registry to configure integrations |
| 237 |
++++++++++++++++++++++++++++++++++++++++++++ |
| 238 |
|
| 239 |
This mechanism also allows to control the stores used by various integrations, such as middlewares: |
| 240 |
|
| 241 |
.. literalinclude:: /examples/stores/registry_configure_integrations.py |
| 242 |
:language: python |
| 243 |
|
| 244 |
|
| 245 |
In this example, the registry is being set up with stores using the ``sessions`` and ``response_cache`` keys. These are |
| 246 |
not magic constants, but instead configuration values that can be changed. Those names just happen to be their default |
| 247 |
values. Adjusting those default values allows to easily reuse stores, without the need for a more complex setup: |
| 248 |
|
| 249 |
.. literalinclude:: /examples/stores/configure_integrations_set_names.py |
| 250 |
:language: python |
| 251 |
|
| 252 |
Now the rate limit middleware and response caching will use the ``redis`` store, while sessions will be store in the |
| 253 |
``file`` store. |
| 254 |
|
| 255 |
|
| 256 |
Setting up the default factory with namespacing |
| 257 |
+++++++++++++++++++++++++++++++++++++++++++++++ |
| 258 |
|
| 259 |
The default factory can be used in conjunction with `namespacing`_ to create isolated, hierarchically organized stores, |
| 260 |
with minimal boilerplate: |
| 261 |
|
| 262 |
.. literalinclude:: /examples/stores/registry_default_factory_namespacing.py |
| 263 |
:language: python |
| 264 |
|
| 265 |
|
| 266 |
Without any extra configuration, every call to ``app.stores.get`` with a unique name will return a namespace for this |
| 267 |
name only, while re-using the underlying Redis instance. |
| 268 |
|
| 269 |
|
| 270 |
Store lifetime |
| 271 |
++++++++++++++ |
| 272 |
|
| 273 |
Stores may not be automatically closed when the application is shut down. |
| 274 |
This is the case in particular for the RedisStore if you are not using the class method :meth:`RedisStore.with_client <.redis.RedisStore.with_client>` and passing in your own Redis instance. |
| 275 |
In this case you're responsible to close the Redis instance yourself. |