Debian Codegraph @

docs/usage/stores.rst

raw
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.