METADATA 32 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042
  1. Metadata-Version: 2.1
  2. Name: django-redis
  3. Version: 5.4.0
  4. Summary: Full featured redis cache backend for Django.
  5. Home-page: https://github.com/jazzband/django-redis
  6. Author: Andrei Antoukh
  7. Author-email: niwi@niwi.nz
  8. License: BSD-3-Clause
  9. Classifier: Development Status :: 5 - Production/Stable
  10. Classifier: Environment :: Web Environment
  11. Classifier: Framework :: Django
  12. Classifier: Framework :: Django :: 3.2
  13. Classifier: Framework :: Django :: 4.0
  14. Classifier: Framework :: Django :: 4.1
  15. Classifier: Framework :: Django :: 4.2
  16. Classifier: Intended Audience :: Developers
  17. Classifier: License :: OSI Approved :: BSD License
  18. Classifier: Operating System :: OS Independent
  19. Classifier: Programming Language :: Python
  20. Classifier: Programming Language :: Python :: 3
  21. Classifier: Programming Language :: Python :: 3 :: Only
  22. Classifier: Programming Language :: Python :: 3.6
  23. Classifier: Programming Language :: Python :: 3.7
  24. Classifier: Programming Language :: Python :: 3.8
  25. Classifier: Programming Language :: Python :: 3.9
  26. Classifier: Programming Language :: Python :: 3.10
  27. Classifier: Programming Language :: Python :: 3.11
  28. Classifier: Topic :: Software Development :: Libraries
  29. Classifier: Topic :: Utilities
  30. Requires-Python: >=3.6
  31. Description-Content-Type: text/x-rst
  32. License-File: LICENSE
  33. License-File: AUTHORS.rst
  34. Requires-Dist: Django >=3.2
  35. Requires-Dist: redis !=4.0.0,!=4.0.1,>=3
  36. Provides-Extra: hiredis
  37. Requires-Dist: redis[hiredis] !=4.0.0,!=4.0.1,>=3 ; extra == 'hiredis'
  38. ==============================
  39. Redis cache backend for Django
  40. ==============================
  41. .. image:: https://jazzband.co/static/img/badge.svg
  42. :target: https://jazzband.co/
  43. :alt: Jazzband
  44. .. image:: https://github.com/jazzband/django-redis/actions/workflows/ci.yml/badge.svg
  45. :target: https://github.com/jazzband/django-redis/actions/workflows/ci.yml
  46. :alt: GitHub Actions
  47. .. image:: https://codecov.io/gh/jazzband/django-redis/branch/master/graph/badge.svg
  48. :target: https://codecov.io/gh/jazzband/django-redis
  49. :alt: Coverage
  50. .. image:: https://img.shields.io/pypi/v/django-redis.svg?style=flat
  51. :target: https://pypi.org/project/django-redis/
  52. This is a `Jazzband <https://jazzband.co>`_ project. By contributing you agree
  53. to abide by the `Contributor Code of Conduct
  54. <https://jazzband.co/about/conduct>`_ and follow the `guidelines
  55. <https://jazzband.co/about/guidelines>`_.
  56. Introduction
  57. ------------
  58. django-redis is a BSD licensed, full featured Redis cache and session backend
  59. for Django.
  60. Why use django-redis?
  61. ~~~~~~~~~~~~~~~~~~~~~
  62. - Uses native redis-py url notation connection strings
  63. - Pluggable clients
  64. - Pluggable parsers
  65. - Pluggable serializers
  66. - Primary/secondary support in the default client
  67. - Comprehensive test suite
  68. - Used in production in several projects as cache and session storage
  69. - Supports infinite timeouts
  70. - Facilities for raw access to Redis client/connection pool
  71. - Highly configurable (can emulate memcached exception behavior, for example)
  72. - Unix sockets supported by default
  73. Requirements
  74. ~~~~~~~~~~~~
  75. - `Python`_ 3.6+
  76. - `Django`_ 2.2+
  77. - `redis-py`_ 3.0+
  78. - `Redis server`_ 2.8+
  79. .. _Python: https://www.python.org/downloads/
  80. .. _Django: https://www.djangoproject.com/download/
  81. .. _redis-py: https://pypi.org/project/redis/
  82. .. _Redis server: https://redis.io/download
  83. User guide
  84. ----------
  85. Installation
  86. ~~~~~~~~~~~~
  87. Install with pip:
  88. .. code-block:: console
  89. $ python -m pip install django-redis
  90. Configure as cache backend
  91. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  92. To start using django-redis, you should change your Django cache settings to
  93. something like:
  94. .. code-block:: python
  95. CACHES = {
  96. "default": {
  97. "BACKEND": "django_redis.cache.RedisCache",
  98. "LOCATION": "redis://127.0.0.1:6379/1",
  99. "OPTIONS": {
  100. "CLIENT_CLASS": "django_redis.client.DefaultClient",
  101. }
  102. }
  103. }
  104. django-redis uses the redis-py native URL notation for connection strings, it
  105. allows better interoperability and has a connection string in more "standard"
  106. way. Some examples:
  107. - ``redis://[[username]:[password]]@localhost:6379/0``
  108. - ``rediss://[[username]:[password]]@localhost:6379/0``
  109. - ``unix://[[username]:[password]]@/path/to/socket.sock?db=0``
  110. Three URL schemes are supported:
  111. - ``redis://``: creates a normal TCP socket connection
  112. - ``rediss://``: creates a SSL wrapped TCP socket connection
  113. - ``unix://`` creates a Unix Domain Socket connection
  114. There are several ways to specify a database number:
  115. - A ``db`` querystring option, e.g. ``redis://localhost?db=0``
  116. - If using the ``redis://`` scheme, the path argument of the URL, e.g.
  117. ``redis://localhost/0``
  118. When using `Redis' ACLs <https://redis.io/topics/acl>`_, you will need to add the
  119. username to the URL (and provide the password with the Cache ``OPTIONS``).
  120. The login for the user ``django`` would look like this:
  121. .. code-block:: python
  122. CACHES = {
  123. "default": {
  124. "BACKEND": "django_redis.cache.RedisCache",
  125. "LOCATION": "redis://django@localhost:6379/0",
  126. "OPTIONS": {
  127. "CLIENT_CLASS": "django_redis.client.DefaultClient",
  128. "PASSWORD": "mysecret"
  129. }
  130. }
  131. }
  132. An alternative would be write both username and password into the URL:
  133. .. code-block:: python
  134. CACHES = {
  135. "default": {
  136. "BACKEND": "django_redis.cache.RedisCache",
  137. "LOCATION": "redis://django:mysecret@localhost:6379/0",
  138. "OPTIONS": {
  139. "CLIENT_CLASS": "django_redis.client.DefaultClient",
  140. }
  141. }
  142. }
  143. In some circumstances the password you should use to connect Redis
  144. is not URL-safe, in this case you can escape it or just use the
  145. convenience option in ``OPTIONS`` dict:
  146. .. code-block:: python
  147. CACHES = {
  148. "default": {
  149. "BACKEND": "django_redis.cache.RedisCache",
  150. "LOCATION": "redis://127.0.0.1:6379/1",
  151. "OPTIONS": {
  152. "CLIENT_CLASS": "django_redis.client.DefaultClient",
  153. "PASSWORD": "mysecret"
  154. }
  155. }
  156. }
  157. Take care, that this option does not overwrites the password in the uri, so if
  158. you have set the password in the uri, this settings will be ignored.
  159. Configure as session backend
  160. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  161. Django can by default use any cache backend as session backend and you benefit
  162. from that by using django-redis as backend for session storage without
  163. installing any additional backends:
  164. .. code-block:: python
  165. SESSION_ENGINE = "django.contrib.sessions.backends.cache"
  166. SESSION_CACHE_ALIAS = "default"
  167. Testing with django-redis
  168. ~~~~~~~~~~~~~~~~~~~~~~~~~
  169. django-redis supports customizing the underlying Redis client (see "Pluggable
  170. clients"). This can be used for testing purposes.
  171. In case you want to flush all data from the cache after a test, add the
  172. following lines to your test class:
  173. .. code-block:: python
  174. from django_redis import get_redis_connection
  175. def tearDown(self):
  176. get_redis_connection("default").flushall()
  177. Advanced usage
  178. --------------
  179. Pickle version
  180. ~~~~~~~~~~~~~~
  181. For almost all values, django-redis uses pickle to serialize objects.
  182. The ``pickle.DEFAULT_PROTOCOL`` version of pickle is used by default to ensure safe upgrades and compatibility across Python versions.
  183. If you want set a concrete version, you can do it, using ``PICKLE_VERSION`` option:
  184. .. code-block:: python
  185. CACHES = {
  186. "default": {
  187. # ...
  188. "OPTIONS": {
  189. "PICKLE_VERSION": -1 # Will use highest protocol version available
  190. }
  191. }
  192. }
  193. Socket timeout
  194. ~~~~~~~~~~~~~~
  195. Socket timeout can be set using ``SOCKET_TIMEOUT`` and
  196. ``SOCKET_CONNECT_TIMEOUT`` options:
  197. .. code-block:: python
  198. CACHES = {
  199. "default": {
  200. # ...
  201. "OPTIONS": {
  202. "SOCKET_CONNECT_TIMEOUT": 5, # seconds
  203. "SOCKET_TIMEOUT": 5, # seconds
  204. }
  205. }
  206. }
  207. ``SOCKET_CONNECT_TIMEOUT`` is the timeout for the connection to be established
  208. and ``SOCKET_TIMEOUT`` is the timeout for read and write operations after the
  209. connection is established.
  210. Compression support
  211. ~~~~~~~~~~~~~~~~~~~
  212. django-redis comes with compression support out of the box, but is deactivated
  213. by default. You can activate it setting up a concrete backend:
  214. .. code-block:: python
  215. CACHES = {
  216. "default": {
  217. # ...
  218. "OPTIONS": {
  219. "COMPRESSOR": "django_redis.compressors.zlib.ZlibCompressor",
  220. }
  221. }
  222. }
  223. Let see an example, of how make it work with *lzma* compression format:
  224. .. code-block:: python
  225. import lzma
  226. CACHES = {
  227. "default": {
  228. # ...
  229. "OPTIONS": {
  230. "COMPRESSOR": "django_redis.compressors.lzma.LzmaCompressor",
  231. }
  232. }
  233. }
  234. *Lz4* compression support (requires the lz4 library):
  235. .. code-block:: python
  236. import lz4
  237. CACHES = {
  238. "default": {
  239. # ...
  240. "OPTIONS": {
  241. "COMPRESSOR": "django_redis.compressors.lz4.Lz4Compressor",
  242. }
  243. }
  244. }
  245. *Zstandard (zstd)* compression support (requires the pyzstd library):
  246. .. code-block:: python
  247. import pyzstd
  248. CACHES = {
  249. "default": {
  250. # ...
  251. "OPTIONS": {
  252. "COMPRESSOR": "django_redis.compressors.zstd.ZStdCompressor",
  253. }
  254. }
  255. }
  256. Memcached exceptions behavior
  257. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  258. In some situations, when Redis is only used for cache, you do not want
  259. exceptions when Redis is down. This is default behavior in the memcached
  260. backend and it can be emulated in django-redis.
  261. For setup memcached like behaviour (ignore connection exceptions), you should
  262. set ``IGNORE_EXCEPTIONS`` settings on your cache configuration:
  263. .. code-block:: python
  264. CACHES = {
  265. "default": {
  266. # ...
  267. "OPTIONS": {
  268. "IGNORE_EXCEPTIONS": True,
  269. }
  270. }
  271. }
  272. Also, you can apply the same settings to all configured caches, you can set the global flag in
  273. your settings:
  274. .. code-block:: python
  275. DJANGO_REDIS_IGNORE_EXCEPTIONS = True
  276. Log Ignored Exceptions
  277. ~~~~~~~~~~~~~~~~~~~~~~
  278. When ignoring exceptions with ``IGNORE_EXCEPTIONS`` or
  279. ``DJANGO_REDIS_IGNORE_EXCEPTIONS``, you may optionally log exceptions using the
  280. global variable ``DJANGO_REDIS_LOG_IGNORED_EXCEPTIONS`` in your settings file::
  281. DJANGO_REDIS_LOG_IGNORED_EXCEPTIONS = True
  282. If you wish to specify the logger in which the exceptions are output, simply
  283. set the global variable ``DJANGO_REDIS_LOGGER`` to the string name and/or path
  284. of the desired logger. This will default to ``__name__`` if no logger is
  285. specified and ``DJANGO_REDIS_LOG_IGNORED_EXCEPTIONS`` is ``True``::
  286. DJANGO_REDIS_LOGGER = 'some.specified.logger'
  287. Infinite timeout
  288. ~~~~~~~~~~~~~~~~
  289. django-redis comes with infinite timeouts support out of the box. And it
  290. behaves in same way as django backend contract specifies:
  291. - ``timeout=0`` expires the value immediately.
  292. - ``timeout=None`` infinite timeout
  293. .. code-block:: python
  294. cache.set("key", "value", timeout=None)
  295. Get ttl (time-to-live) from key
  296. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  297. With Redis, you can access to ttl of any stored key, for it, django-redis
  298. exposes ``ttl`` function.
  299. It returns:
  300. - 0 if key does not exists (or already expired).
  301. - None for keys that exists but does not have any expiration.
  302. - ttl value for any volatile key (any key that has expiration).
  303. .. code-block:: pycon
  304. >>> from django.core.cache import cache
  305. >>> cache.set("foo", "value", timeout=25)
  306. >>> cache.ttl("foo")
  307. 25
  308. >>> cache.ttl("not-existent")
  309. 0
  310. With Redis, you can access to ttl of any stored key in milliseconds, for it, django-redis
  311. exposes ``pttl`` function.
  312. .. code-block:: pycon
  313. >>> from django.core.cache import cache
  314. >>> cache.set("foo", "value", timeout=25)
  315. >>> cache.pttl("foo")
  316. 25000
  317. >>> cache.pttl("not-existent")
  318. 0
  319. Expire & Persist
  320. ~~~~~~~~~~~~~~~~
  321. Additionally to the simple ttl query, you can send persist a concrete key or
  322. specify a new expiration timeout using the ``persist`` and ``expire`` methods:
  323. .. code-block:: pycon
  324. >>> cache.set("foo", "bar", timeout=22)
  325. >>> cache.ttl("foo")
  326. 22
  327. >>> cache.persist("foo")
  328. True
  329. >>> cache.ttl("foo")
  330. None
  331. .. code-block:: pycon
  332. >>> cache.set("foo", "bar", timeout=22)
  333. >>> cache.expire("foo", timeout=5)
  334. True
  335. >>> cache.ttl("foo")
  336. 5
  337. The ``expire_at`` method can be used to make the key expire at a specific moment in time.
  338. .. code-block:: pycon
  339. >>> cache.set("foo", "bar", timeout=22)
  340. >>> cache.expire_at("foo", datetime.now() + timedelta(hours=1))
  341. True
  342. >>> cache.ttl("foo")
  343. 3600
  344. The ``pexpire_at`` method can be used to make the key expire at a specific moment in time with milliseconds precision:
  345. .. code-block:: pycon
  346. >>> cache.set("foo", "bar", timeout=22)
  347. >>> cache.pexpire_at("foo", datetime.now() + timedelta(milliseconds=900, hours=1))
  348. True
  349. >>> cache.ttl("foo")
  350. 3601
  351. >>> cache.pttl("foo")
  352. 3600900
  353. The ``pexpire`` method can be used to provide millisecond precision:
  354. .. code-block:: pycon
  355. >>> cache.set("foo", "bar", timeout=22)
  356. >>> cache.pexpire("foo", timeout=5500)
  357. True
  358. >>> cache.pttl("foo")
  359. 5500
  360. Locks
  361. ~~~~~
  362. It also supports the Redis ability to create Redis distributed named locks. The
  363. Lock interface is identical to the ``threading.Lock`` so you can use it as
  364. replacement.
  365. .. code-block:: python
  366. with cache.lock("somekey"):
  367. do_some_thing()
  368. Scan & Delete keys in bulk
  369. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  370. django-redis comes with some additional methods that help with searching or
  371. deleting keys using glob patterns.
  372. .. code-block:: pycon
  373. >>> from django.core.cache import cache
  374. >>> cache.keys("foo_*")
  375. ["foo_1", "foo_2"]
  376. A simple search like this will return all matched values. In databases with a
  377. large number of keys this isn't suitable method. Instead, you can use the
  378. ``iter_keys`` function that works like the ``keys`` function but uses Redis
  379. server side cursors. Calling ``iter_keys`` will return a generator that you can
  380. then iterate over efficiently.
  381. .. code-block:: pycon
  382. >>> from django.core.cache import cache
  383. >>> cache.iter_keys("foo_*")
  384. <generator object algo at 0x7ffa9c2713a8>
  385. >>> next(cache.iter_keys("foo_*"))
  386. "foo_1"
  387. For deleting keys, you should use ``delete_pattern`` which has the same glob
  388. pattern syntax as the ``keys`` function and returns the number of deleted keys.
  389. .. code-block:: pycon
  390. >>> from django.core.cache import cache
  391. >>> cache.delete_pattern("foo_*")
  392. To achieve the best performance while deleting many keys, you should set ``DJANGO_REDIS_SCAN_ITERSIZE`` to a relatively
  393. high number (e.g., 100_000) by default in Django settings or pass it directly to the ``delete_pattern``.
  394. .. code-block:: pycon
  395. >>> from django.core.cache import cache
  396. >>> cache.delete_pattern("foo_*", itersize=100_000)
  397. Redis native commands
  398. ~~~~~~~~~~~~~~~~~~~~~
  399. django-redis has limited support for some Redis atomic operations, such as the
  400. commands ``SETNX`` and ``INCR``.
  401. You can use the ``SETNX`` command through the backend ``set()`` method with the
  402. ``nx`` parameter:
  403. .. code-block:: pycon
  404. >>> from django.core.cache import cache
  405. >>> cache.set("key", "value1", nx=True)
  406. True
  407. >>> cache.set("key", "value2", nx=True)
  408. False
  409. >>> cache.get("key")
  410. "value1"
  411. Also, the ``incr`` and ``decr`` methods use Redis atomic operations when the
  412. value that a key contains is suitable for it.
  413. Raw client access
  414. ~~~~~~~~~~~~~~~~~
  415. In some situations your application requires access to a raw Redis client to
  416. use some advanced features that aren't exposed by the Django cache interface.
  417. To avoid storing another setting for creating a raw connection, django-redis
  418. exposes functions with which you can obtain a raw client reusing the cache
  419. connection string: ``get_redis_connection(alias)``.
  420. .. code-block:: pycon
  421. >>> from django_redis import get_redis_connection
  422. >>> con = get_redis_connection("default")
  423. >>> con
  424. <redis.client.Redis object at 0x2dc4510>
  425. WARNING: Not all pluggable clients support this feature.
  426. Connection pools
  427. ~~~~~~~~~~~~~~~~
  428. Behind the scenes, django-redis uses the underlying redis-py connection pool
  429. implementation, and exposes a simple way to configure it. Alternatively, you
  430. can directly customize a connection/connection pool creation for a backend.
  431. The default redis-py behavior is to not close connections, recycling them when
  432. possible.
  433. Configure default connection pool
  434. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  435. The default connection pool is simple. For example, you can customize the
  436. maximum number of connections in the pool by setting ``CONNECTION_POOL_KWARGS``
  437. in the ``CACHES`` setting:
  438. .. code-block:: python
  439. CACHES = {
  440. "default": {
  441. "BACKEND": "django_redis.cache.RedisCache",
  442. # ...
  443. "OPTIONS": {
  444. "CONNECTION_POOL_KWARGS": {"max_connections": 100}
  445. }
  446. }
  447. }
  448. You can verify how many connections the pool has opened with the following
  449. snippet:
  450. .. code-block:: python
  451. from django_redis import get_redis_connection
  452. r = get_redis_connection("default") # Use the name you have defined for Redis in settings.CACHES
  453. connection_pool = r.connection_pool
  454. print("Created connections so far: %d" % connection_pool._created_connections)
  455. Since the default connection pool passes all keyword arguments it doesn't use
  456. to its connections, you can also customize the connections that the pool makes
  457. by adding those options to ``CONNECTION_POOL_KWARGS``:
  458. .. code-block:: python
  459. CACHES = {
  460. "default": {
  461. # ...
  462. "OPTIONS": {
  463. "CONNECTION_POOL_KWARGS": {"max_connections": 100, "retry_on_timeout": True}
  464. }
  465. }
  466. }
  467. Use your own connection pool subclass
  468. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  469. Sometimes you want to use your own subclass of the connection pool. This is
  470. possible with django-redis using the ``CONNECTION_POOL_CLASS`` parameter in the
  471. backend options.
  472. .. code-block:: python
  473. from redis.connection import ConnectionPool
  474. class MyOwnPool(ConnectionPool):
  475. # Just doing nothing, only for example purpose
  476. pass
  477. .. code-block:: python
  478. # Omitting all backend declaration boilerplate code.
  479. "OPTIONS": {
  480. "CONNECTION_POOL_CLASS": "myproj.mypool.MyOwnPool",
  481. }
  482. Customize connection factory
  483. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  484. If none of the previous methods satisfies you, you can get in the middle of the
  485. django-redis connection factory process and customize or completely rewrite it.
  486. By default, django-redis creates connections through the
  487. ``django_redis.pool.ConnectionFactory`` class that is specified in the global
  488. Django setting ``DJANGO_REDIS_CONNECTION_FACTORY``.
  489. .. code-block:: python
  490. class ConnectionFactory(object):
  491. def get_connection_pool(self, params: dict):
  492. # Given connection parameters in the `params` argument, return new
  493. # connection pool. It should be overwritten if you want do
  494. # something before/after creating the connection pool, or return
  495. # your own connection pool.
  496. pass
  497. def get_connection(self, params: dict):
  498. # Given connection parameters in the `params` argument, return a
  499. # new connection. It should be overwritten if you want to do
  500. # something before/after creating a new connection. The default
  501. # implementation uses `get_connection_pool` to obtain a pool and
  502. # create a new connection in the newly obtained pool.
  503. pass
  504. def get_or_create_connection_pool(self, params: dict):
  505. # This is a high layer on top of `get_connection_pool` for
  506. # implementing a cache of created connection pools. It should be
  507. # overwritten if you want change the default behavior.
  508. pass
  509. def make_connection_params(self, url: str) -> dict:
  510. # The responsibility of this method is to convert basic connection
  511. # parameters and other settings to fully connection pool ready
  512. # connection parameters.
  513. pass
  514. def connect(self, url: str):
  515. # This is really a public API and entry point for this factory
  516. # class. This encapsulates the main logic of creating the
  517. # previously mentioned `params` using `make_connection_params` and
  518. # creating a new connection using the `get_connection` method.
  519. pass
  520. Use the sentinel connection factory
  521. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  522. In order to facilitate using `Redis Sentinels`_, django-redis comes with a
  523. built in sentinel connection factory, which creates sentinel connection pools.
  524. In order to enable this functionality you should add the following:
  525. .. code-block:: python
  526. # Enable the alternate connection factory.
  527. DJANGO_REDIS_CONNECTION_FACTORY = 'django_redis.pool.SentinelConnectionFactory'
  528. # These sentinels are shared between all the examples, and are passed
  529. # directly to redis Sentinel. These can also be defined inline.
  530. SENTINELS = [
  531. ('sentinel-1', 26379),
  532. ('sentinel-2', 26379),
  533. ('sentinel-3', 26379),
  534. ]
  535. CACHES = {
  536. "default": {
  537. "BACKEND": "django_redis.cache.RedisCache",
  538. # The hostname in LOCATION is the primary (service / master) name
  539. "LOCATION": "redis://service_name/db",
  540. "OPTIONS": {
  541. # While the default client will work, this will check you
  542. # have configured things correctly, and also create a
  543. # primary and replica pool for the service specified by
  544. # LOCATION rather than requiring two URLs.
  545. "CLIENT_CLASS": "django_redis.client.SentinelClient",
  546. # Sentinels which are passed directly to redis Sentinel.
  547. "SENTINELS": SENTINELS,
  548. # kwargs for redis Sentinel (optional).
  549. "SENTINEL_KWARGS": {},
  550. # You can still override the connection pool (optional).
  551. "CONNECTION_POOL_CLASS": "redis.sentinel.SentinelConnectionPool",
  552. },
  553. },
  554. # A minimal example using the SentinelClient.
  555. "minimal": {
  556. "BACKEND": "django_redis.cache.RedisCache",
  557. # The SentinelClient will use this location for both the primaries
  558. # and replicas.
  559. "LOCATION": "redis://minimal_service_name/db",
  560. "OPTIONS": {
  561. "CLIENT_CLASS": "django_redis.client.SentinelClient",
  562. "SENTINELS": SENTINELS,
  563. },
  564. },
  565. # A minimal example using the DefaultClient.
  566. "other": {
  567. "BACKEND": "django_redis.cache.RedisCache",
  568. "LOCATION": [
  569. # The DefaultClient is [primary, replicas...], but with the
  570. # SentinelConnectionPool it only requires one "is_master=0".
  571. "redis://other_service_name/db?is_master=1",
  572. "redis://other_service_name/db?is_master=0",
  573. ],
  574. "OPTIONS": {"SENTINELS": SENTINELS},
  575. },
  576. # A minimal example only using only replicas in read only mode (and
  577. # the DefaultClient).
  578. "readonly": {
  579. "BACKEND": "django_redis.cache.RedisCache",
  580. "LOCATION": "redis://readonly_service_name/db?is_master=0",
  581. "OPTIONS": {"SENTINELS": SENTINELS},
  582. },
  583. }
  584. It is also possible to set some caches as sentinels and some as not:
  585. .. code-block:: python
  586. SENTINELS = [
  587. ('sentinel-1', 26379),
  588. ('sentinel-2', 26379),
  589. ('sentinel-3', 26379),
  590. ]
  591. CACHES = {
  592. "sentinel": {
  593. "BACKEND": "django_redis.cache.RedisCache",
  594. "LOCATION": "redis://service_name/db",
  595. "OPTIONS": {
  596. "CLIENT_CLASS": "django_redis.client.SentinelClient",
  597. "SENTINELS": SENTINELS,
  598. "CONNECTION_POOL_CLASS": "redis.sentinel.SentinelConnectionPool",
  599. "CONNECTION_FACTORY": "django_redis.pool.SentinelConnectionFactory",
  600. },
  601. },
  602. "default": {
  603. "BACKEND": "django_redis.cache.RedisCache",
  604. "LOCATION": "redis://127.0.0.1:6379/1",
  605. "OPTIONS": {
  606. "CLIENT_CLASS": "django_redis.client.DefaultClient",
  607. },
  608. },
  609. }
  610. .. _Redis Sentinels: https://redis.io/topics/sentinel
  611. Pluggable parsers
  612. ~~~~~~~~~~~~~~~~~
  613. redis-py (the Python Redis client used by django-redis) comes with a pure
  614. Python Redis parser that works very well for most common task, but if you want
  615. some performance boost, you can use hiredis.
  616. hiredis is a Redis client written in C and it has its own parser that can be
  617. used with django-redis.
  618. .. code-block:: python
  619. "OPTIONS": {
  620. "PARSER_CLASS": "redis.connection.HiredisParser",
  621. }
  622. Note: if using version 5 of redis-py, use ``"redis.connection._HiredisParser"`` for the ``PARSER_CLASS`` due to an internal rename of classes within that package.
  623. Pluggable clients
  624. ~~~~~~~~~~~~~~~~~
  625. django-redis is designed for to be very flexible and very configurable. For it,
  626. it exposes a pluggable backends that make easy extend the default behavior, and
  627. it comes with few ones out the box.
  628. Default client
  629. ^^^^^^^^^^^^^^
  630. Almost all about the default client is explained, with one exception: the
  631. default client comes with replication support.
  632. To connect to a Redis replication setup, you should change the ``LOCATION`` to
  633. something like:
  634. .. code-block:: python
  635. "LOCATION": [
  636. "redis://127.0.0.1:6379/1",
  637. "redis://127.0.0.1:6378/1",
  638. ]
  639. The first connection string represents the primary server and the rest to
  640. replica servers.
  641. WARNING: Replication setup is not heavily tested in production environments.
  642. Shard client
  643. ^^^^^^^^^^^^
  644. This pluggable client implements client-side sharding. It inherits almost all
  645. functionality from the default client. To use it, change your cache settings to
  646. something like this:
  647. .. code-block:: python
  648. CACHES = {
  649. "default": {
  650. "BACKEND": "django_redis.cache.RedisCache",
  651. "LOCATION": [
  652. "redis://127.0.0.1:6379/1",
  653. "redis://127.0.0.1:6379/2",
  654. ],
  655. "OPTIONS": {
  656. "CLIENT_CLASS": "django_redis.client.ShardClient",
  657. }
  658. }
  659. }
  660. WARNING: Shard client is still experimental, so be careful when using it in
  661. production environments.
  662. Herd client
  663. ^^^^^^^^^^^
  664. This pluggable client helps dealing with the thundering herd problem. You can read more about it
  665. on link: `Wikipedia <https://en.wikipedia.org/wiki/Thundering_herd_problem>`_
  666. Like previous pluggable clients, it inherits all functionality from the default client, adding some
  667. additional methods for getting/setting keys.
  668. .. code-block:: python
  669. CACHES = {
  670. "default": {
  671. "BACKEND": "django_redis.cache.RedisCache",
  672. "LOCATION": "redis://127.0.0.1:6379/1",
  673. "OPTIONS": {
  674. "CLIENT_CLASS": "django_redis.client.HerdClient",
  675. }
  676. }
  677. }
  678. This client exposes additional settings:
  679. - ``CACHE_HERD_TIMEOUT``: Set default herd timeout. (Default value: 60s)
  680. Pluggable serializer
  681. ~~~~~~~~~~~~~~~~~~~~
  682. The pluggable clients serialize data before sending it to the server. By
  683. default, django-redis serializes the data using the Python ``pickle`` module.
  684. This is very flexible and can handle a large range of object types.
  685. To serialize using JSON instead, the serializer ``JSONSerializer`` is also
  686. available.
  687. .. code-block:: python
  688. CACHES = {
  689. "default": {
  690. "BACKEND": "django_redis.cache.RedisCache",
  691. "LOCATION": "redis://127.0.0.1:6379/1",
  692. "OPTIONS": {
  693. "CLIENT_CLASS": "django_redis.client.DefaultClient",
  694. "SERIALIZER": "django_redis.serializers.json.JSONSerializer",
  695. }
  696. }
  697. }
  698. There's also support for serialization using `MsgPack`_ (that requires the
  699. msgpack library):
  700. .. code-block:: python
  701. CACHES = {
  702. "default": {
  703. "BACKEND": "django_redis.cache.RedisCache",
  704. "LOCATION": "redis://127.0.0.1:6379/1",
  705. "OPTIONS": {
  706. "CLIENT_CLASS": "django_redis.client.DefaultClient",
  707. "SERIALIZER": "django_redis.serializers.msgpack.MSGPackSerializer",
  708. }
  709. }
  710. }
  711. .. _MsgPack: https://msgpack.org/
  712. Pluggable Redis client
  713. ~~~~~~~~~~~~~~~~~~~~~~
  714. django-redis uses the Redis client ``redis.client.StrictClient`` by default. It
  715. is possible to use an alternative client.
  716. You can customize the client used by setting ``REDIS_CLIENT_CLASS`` in the
  717. ``CACHES`` setting. Optionally, you can provide arguments to this class by
  718. setting ``REDIS_CLIENT_KWARGS``.
  719. .. code-block:: python
  720. CACHES = {
  721. "default": {
  722. "OPTIONS": {
  723. "REDIS_CLIENT_CLASS": "my.module.ClientClass",
  724. "REDIS_CLIENT_KWARGS": {"some_setting": True},
  725. }
  726. }
  727. }
  728. Closing Connections
  729. ~~~~~~~~~~~~~~~~~~~
  730. The default django-redis behavior on close() is to keep the connections to Redis server.
  731. You can change this default behaviour for all caches by the ``DJANGO_REDIS_CLOSE_CONNECTION = True``
  732. in the django settings (globally) or (at cache level) by setting ``CLOSE_CONNECTION: True`` in the ``OPTIONS``
  733. for each configured cache.
  734. Setting True as a value will instruct the django-redis to close all the connections (since v. 4.12.2), irrespectively of its current usage.
  735. .. code-block:: python
  736. CACHES = {
  737. "default": {
  738. "BACKEND": "django_redis.cache.RedisCache",
  739. "LOCATION": "redis://127.0.0.1:6379/1",
  740. "OPTIONS": {
  741. "CLIENT_CLASS": "django_redis.client.DefaultClient",
  742. "CLOSE_CONNECTION": True,
  743. }
  744. }
  745. }
  746. SSL/TLS and Self-Signed certificates
  747. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  748. In case you encounter a Redis server offering a TLS connection using a
  749. self-signed certificate you may disable certification verification with the
  750. following:
  751. .. code-block:: python
  752. CACHES = {
  753. "default": {
  754. "BACKEND": "django_redis.cache.RedisCache",
  755. "LOCATION": "rediss://127.0.0.1:6379/1",
  756. "OPTIONS": {
  757. "CLIENT_CLASS": "django_redis.client.DefaultClient",
  758. "CONNECTION_POOL_KWARGS": {"ssl_cert_reqs": None}
  759. }
  760. }
  761. }
  762. License
  763. -------
  764. .. code-block:: text
  765. Copyright (c) 2011-2015 Andrey Antukh <niwi@niwi.nz>
  766. Copyright (c) 2011 Sean Bleier
  767. All rights reserved.
  768. Redistribution and use in source and binary forms, with or without
  769. modification, are permitted provided that the following conditions
  770. are met:
  771. 1. Redistributions of source code must retain the above copyright
  772. notice, this list of conditions and the following disclaimer.
  773. 2. Redistributions in binary form must reproduce the above copyright
  774. notice, this list of conditions and the following disclaimer in the
  775. documentation and/or other materials provided with the distribution.
  776. 3. The name of the author may not be used to endorse or promote products
  777. derived from this software without specific prior written permission.
  778. THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS`` AND ANY EXPRESS OR
  779. IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  780. OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  781. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  782. INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  783. NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  784. DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  785. THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  786. (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  787. THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.