# django-elastipymemcache
[](https://codecov.io/gh/harikitech/django-elastipymemcache)
## Overview
**django-elastipymemcache** is a Django cache backend for **Amazon ElastiCache (memcached)** clusters.
It is built on top of [pymemcache](https://github.com/pinterest/pymemcache) and connects to all cluster nodes via
[ElastiCache Auto Discovery](https://docs.aws.amazon.com/AmazonElastiCache/latest/UserGuide/AutoDiscovery.html).
Originally forked from [django-elasticache](https://github.com/gusdan/django-elasticache), this implementation adds:
- Thread-safe topology updates (atomic swaps)
- Auto discovery for scaling events
- Connection pooling (data nodes & config endpoint)
- Optional TLS connectivity
- Compatibility with Django’s cache interface
## Requirements
- Python >= 3.10
- Django >= 4.2
- pymemcache >= 4.0.0
## Installation
Get it from PyPI:
```bash
python3 -m pip install django-elastipymemcache
```
## Usage
### Basic
```python
CACHES = {
"default": {
"BACKEND": "django_elastipymemcache.backend.ElastiPymemcache",
"LOCATION": "[configuration-endpoint]:11211",
"OPTIONS": {
"ignore_exc": True,
},
}
}
```
### Connection Pooling
```python
CACHES = {
"default": {
"BACKEND": "django_elastipymemcache.backend.ElastiPymemcache",
"LOCATION": "[configuration-endpoint]:11211",
"OPTIONS": {
# Enable pooling for both config endpoint and data nodes
"use_pooling": True,
"max_pool_size": 50,
"pool_idle_timeout": 30,
"connect_timeout": 0.3,
"timeout": 0.5,
"ignore_exc": True,
},
}
}
```
### Auto Discovery (with pooling)
```python
CACHES = {
"default": {
"BACKEND": "django_elastipymemcache.backend.ElastiPymemcache",
"LOCATION": "[configuration-endpoint]:11211",
"OPTIONS": {
"use_pooling": True,
"discovery_interval": 60.0,
"discovery_retry_delay": 2.0,
"ignore_exc": True,
},
}
}
```
## Options
The backend accepts a combination of **ElastiPymemcache-specific options** and
**pymemcache client options**. For the complete list of pymemcache options, see:
<https://pymemcache.readthedocs.io/>
### ElastiPymemcache-specific options
| Option | Type | Default | Description |
| ----------------------- | ----- | ------- | ------------------------------------------------------------------ |
| `discovery_interval` | float | `0.0` | Periodic auto-discovery interval in seconds. Set `0.0` to disable. |
| `discovery_retry_delay` | float | `0.0` | Delay (seconds) before retrying discovery after failure. |
| `use_vpc_ip_address` | bool | `True` | Prefer VPC private IPs over DNS hostnames (recommended on AWS). |
### Notes
- According to the official Amazon ElastiCache documentation, **auto-discovery must be enabled to support vertical scaling**.
<https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/Scaling-self-designed.mem-heading.html>
- Auto-discovery also runs **on demand** when the ring is empty, even if `discovery_interval` is `0.0`.
This helps recover after scale events.
- If you use TLS, pass the appropriate `tls_context` through `OPTIONS` (this is a pymemcache option)
and ensure your ElastiCache cluster supports TLS.
## Notice
### Datadog `ddtrace` & `pymemcache` instrumentation (temporary workaround)
When using `ddtrace` with Django or other frameworks, enabling the `pymemcache` integration may trigger runtime errors such as:
```text
ValueError: wrapper has not been initialized
```
This issue occurs due to `wrapt` interfering with class initialization order inside `ddtrace`’s `pymemcache` integration.
Until Datadog releases a fix, disable the `pymemcache` tracer.
#### Environment variable
```sh
DD_TRACE_PYMEMCACHE_ENABLED=false
```
#### Code-level patch
```python
patch_all(pymemcache=False)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "django-elastipymemcache",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "cache, django, elasticache, memcached, pymemcache",
"author": "Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ca/5c/2b780abe7508e575d44a46430a2babf98df5d850a17047179650c4541082/django_elastipymemcache-3.0.0.tar.gz",
"platform": null,
"description": "# django-elastipymemcache\n\n[](https://codecov.io/gh/harikitech/django-elastipymemcache)\n\n## Overview\n\n**django-elastipymemcache** is a Django cache backend for **Amazon ElastiCache (memcached)** clusters.\nIt is built on top of [pymemcache](https://github.com/pinterest/pymemcache) and connects to all cluster nodes via\n[ElastiCache Auto Discovery](https://docs.aws.amazon.com/AmazonElastiCache/latest/UserGuide/AutoDiscovery.html).\n\nOriginally forked from [django-elasticache](https://github.com/gusdan/django-elasticache), this implementation adds:\n\n- Thread-safe topology updates (atomic swaps)\n- Auto discovery for scaling events\n- Connection pooling (data nodes & config endpoint)\n- Optional TLS connectivity\n- Compatibility with Django\u2019s cache interface\n\n## Requirements\n\n- Python >= 3.10\n- Django >= 4.2\n- pymemcache >= 4.0.0\n\n## Installation\n\nGet it from PyPI:\n\n```bash\npython3 -m pip install django-elastipymemcache\n```\n\n## Usage\n\n### Basic\n\n```python\nCACHES = {\n \"default\": {\n \"BACKEND\": \"django_elastipymemcache.backend.ElastiPymemcache\",\n \"LOCATION\": \"[configuration-endpoint]:11211\",\n \"OPTIONS\": {\n \"ignore_exc\": True,\n },\n }\n}\n```\n\n### Connection Pooling\n\n```python\nCACHES = {\n \"default\": {\n \"BACKEND\": \"django_elastipymemcache.backend.ElastiPymemcache\",\n \"LOCATION\": \"[configuration-endpoint]:11211\",\n \"OPTIONS\": {\n # Enable pooling for both config endpoint and data nodes\n \"use_pooling\": True,\n \"max_pool_size\": 50,\n \"pool_idle_timeout\": 30,\n \"connect_timeout\": 0.3,\n \"timeout\": 0.5,\n \"ignore_exc\": True,\n },\n }\n}\n```\n\n### Auto Discovery (with pooling)\n\n```python\nCACHES = {\n \"default\": {\n \"BACKEND\": \"django_elastipymemcache.backend.ElastiPymemcache\",\n \"LOCATION\": \"[configuration-endpoint]:11211\",\n \"OPTIONS\": {\n \"use_pooling\": True,\n \"discovery_interval\": 60.0,\n \"discovery_retry_delay\": 2.0,\n \"ignore_exc\": True,\n },\n }\n}\n```\n\n## Options\n\nThe backend accepts a combination of **ElastiPymemcache-specific options** and\n**pymemcache client options**. For the complete list of pymemcache options, see:\n<https://pymemcache.readthedocs.io/>\n\n### ElastiPymemcache-specific options\n\n| Option | Type | Default | Description |\n| ----------------------- | ----- | ------- | ------------------------------------------------------------------ |\n| `discovery_interval` | float | `0.0` | Periodic auto-discovery interval in seconds. Set `0.0` to disable. |\n| `discovery_retry_delay` | float | `0.0` | Delay (seconds) before retrying discovery after failure. |\n| `use_vpc_ip_address` | bool | `True` | Prefer VPC private IPs over DNS hostnames (recommended on AWS). |\n\n### Notes\n\n- According to the official Amazon ElastiCache documentation, **auto-discovery must be enabled to support vertical scaling**.\n <https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/Scaling-self-designed.mem-heading.html>\n- Auto-discovery also runs **on demand** when the ring is empty, even if `discovery_interval` is `0.0`.\n This helps recover after scale events.\n- If you use TLS, pass the appropriate `tls_context` through `OPTIONS` (this is a pymemcache option)\n and ensure your ElastiCache cluster supports TLS.\n\n## Notice\n\n### Datadog `ddtrace` & `pymemcache` instrumentation (temporary workaround)\n\nWhen using `ddtrace` with Django or other frameworks, enabling the `pymemcache` integration may trigger runtime errors such as:\n\n```text\nValueError: wrapper has not been initialized\n```\n\nThis issue occurs due to `wrapt` interfering with class initialization order inside `ddtrace`\u2019s `pymemcache` integration.\nUntil Datadog releases a fix, disable the `pymemcache` tracer.\n\n#### Environment variable\n\n```sh\nDD_TRACE_PYMEMCACHE_ENABLED=false\n```\n\n#### Code-level patch\n\n```python\npatch_all(pymemcache=False)\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "pymemcache-based Django cache backend for Amazon ElastiCache with auto discovery",
"version": "3.0.0",
"project_urls": null,
"split_keywords": [
"cache",
" django",
" elasticache",
" memcached",
" pymemcache"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eaedd6367503f4b74d637ac1170fdf84a60e6c5f88919c014e3efc7ae1c8f5c0",
"md5": "8b77cdca9876d8da3ad3a5383ba86d5c",
"sha256": "3e7af17c47683eab919b5d4deb977242527e842efac5dd1bfbfdd1e42d7148ce"
},
"downloads": -1,
"filename": "django_elastipymemcache-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b77cdca9876d8da3ad3a5383ba86d5c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 7745,
"upload_time": "2025-11-02T17:43:18",
"upload_time_iso_8601": "2025-11-02T17:43:18.900008Z",
"url": "https://files.pythonhosted.org/packages/ea/ed/d6367503f4b74d637ac1170fdf84a60e6c5f88919c014e3efc7ae1c8f5c0/django_elastipymemcache-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ca5c2b780abe7508e575d44a46430a2babf98df5d850a17047179650c4541082",
"md5": "fa205c1de67247f6a345e816cf40bbc2",
"sha256": "6316fbe817d43aa12af919a2c3aa6a309faf9d646d850bbd40e7122d5b5e6877"
},
"downloads": -1,
"filename": "django_elastipymemcache-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "fa205c1de67247f6a345e816cf40bbc2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 11008,
"upload_time": "2025-11-02T17:43:20",
"upload_time_iso_8601": "2025-11-02T17:43:20.015091Z",
"url": "https://files.pythonhosted.org/packages/ca/5c/2b780abe7508e575d44a46430a2babf98df5d850a17047179650c4541082/django_elastipymemcache-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-02 17:43:20",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "django-elastipymemcache"
}
JSON