Memcache API and Integration

High-performance cache backend integration using memcache or memcached PECL extensions for Drupal's caching system.

memcache

44,499 sites

drupal.org

api gui

cache performance memcache memcached scalability distributed cache lock high availability

Drupal 8 Drupal 9 Drupal 10 Drupal 11

Install

Drupal 11, 10, 9 v8.x-2.7

composer require 'drupal/memcache:8.x-2.7'

Drupal 8 v8.x-2.3

composer require 'drupal/memcache:8.x-2.3'

Overview

The Memcache API and Integration module provides a high-performance cache backend for Drupal that stores cached data in memcache servers instead of the database. This significantly improves site performance by offloading cache operations from the database to dedicated memory-based cache servers.

The module supports both PECL memcache and memcached PHP extensions, with automatic detection and selection. It implements Drupal's CacheBackendInterface for seamless integration with Drupal's cache system, and includes a lock backend implementation for distributed locking across multiple web servers.

Key architectural features include support for multiple memcache servers organized into clusters, automatic splitting of large cache items (over 470KB) into chunks, cache tag invalidation using timestamps stored in memcache, and configurable key prefixing for multi-site deployments sharing memcache instances.

The included Memcache Admin submodule provides a comprehensive UI for monitoring memcache server statistics, including hit/miss ratios, memory usage, connection information, and per-request cache operation details.

Features

Implements Drupal CacheBackendInterface for seamless cache backend replacement
Supports both PECL memcache and memcached PHP extensions with automatic detection
Multi-server support with server clustering for cache bin isolation
Automatic large item splitting for cache items exceeding 470KB
Timestamp-based cache tag invalidation stored in memcache (optional database-free mode)
Lock backend implementation for distributed locking using memcache
Key prefix configuration for multiple Drupal sites sharing memcache servers
Configurable key hash algorithm (default: sha1) for keys exceeding 250 bytes
Support for Unix socket connections to memcache servers
Persistent connection support for the memcache extension
SASL authentication support for secured memcached connections
Bootstrap container override for using memcache during early Drupal bootstrap
Debug mode for logging all memcache operations
Mcrouter proxy support for statistics collection
Per-page statistics display showing cache operations, hits, and misses
Detailed server statistics report with slab inspection capabilities

Use Cases

High-Traffic Website Caching

Replace database caching with memcache for high-traffic Drupal sites. Configure memcache as the default cache backend to eliminate database bottlenecks. Set $settings['cache']['default'] = 'cache.backend.memcache' in settings.php. This offloads all cache reads and writes from the database to dedicated memcache servers, significantly reducing database load and improving response times.

Multi-Server Load Balanced Environment

Deploy memcache for Drupal sites running across multiple web servers behind a load balancer. All web servers connect to shared memcache servers, ensuring cache consistency across the cluster. Configure the lock backend to use memcache for distributed locking: add the lock service override from example.services.yml to prevent race conditions during cache rebuilds.

Separate Cache Bins by Importance

Route different cache bins to dedicated memcache clusters based on importance and access patterns. For example, route the 'render' and 'page' bins to a larger, dedicated cluster while keeping less critical bins on a smaller cluster. Configure using $settings['memcache']['bins'] = ['render' => 'cluster_render', 'page' => 'cluster_render', 'default' => 'default'].

Multi-Site Drupal with Shared Memcache

Share memcache servers across multiple Drupal sites while maintaining cache isolation. Configure unique key prefixes for each site: $settings['memcache']['key_prefix'] = 'site1'; This ensures each site's cache keys are namespaced and don't collide with other sites sharing the same memcache infrastructure.

Database-Free Bootstrap

Configure Drupal to use memcache during early bootstrap before the database is available. This eliminates database queries during cache container initialization. Implement the bootstrap container definition from README.md in settings.php using either the database-backed cache tag invalidation (hybrid mode) or the pure memcache mode with TimestampCacheTagsChecksum service override.

Performance Monitoring and Debugging

Enable the memcache_admin submodule to monitor cache performance and debug cache issues. Enable per-page statistics in the admin settings to see real-time cache operations including hits, misses, and timing for each request. Use the reports at /admin/reports/memcache to view server health, memory usage, and hit ratios across all configured servers.

Tips

For production deployments, use the memcached PECL extension over memcache as it supports more features and is actively maintained.
Enable compression with Memcached::OPT_COMPRESSION => TRUE to store more data in available memory.
Use consistent hashing (Memcached::OPT_DISTRIBUTION => Memcached::DISTRIBUTION_CONSISTENT) to minimize cache invalidation when adding or removing servers.
Configure separate memcache clusters for render/page caches vs other bins to optimize memory allocation for different access patterns.
When using multiple Drupal sites, always set unique key_prefix values to prevent cache key collisions.
Monitor eviction rates in the admin statistics - high evictions indicate insufficient memory allocation.
For maximum performance, implement the bootstrap container definition to use memcache during early Drupal bootstrap.
Use Unix sockets instead of TCP for local memcached connections to reduce network overhead.

Technical Details

Memcache Admin Settings /admin/config/system/memcache

Configuration page for the Memcache Admin module. Controls whether per-page memcache statistics are displayed at the bottom of each page for users with appropriate permissions.

Memcache Statistics /admin/reports/memcache

Displays comprehensive statistics for all configured memcache servers. Shows the PECL driver version in use, lists all configured server endpoints with their assigned cache bins, and provides detailed statistics tables including uptime, memory usage, connection counts, cache hit/miss ratios, evictions, and performance metrics. Links to individual server statistics for deeper analysis.

Memcache Statistics - Cluster /admin/reports/memcache/{cluster}

Displays statistics for a specific memcache cluster, showing data for all servers in that cluster.

Memcache Statistics - Server /admin/reports/memcache/{cluster}/{server}

Displays raw statistics for a specific memcache server. Provides navigation to view different statistics types (default, slabs, items, sizes) when using the Memcache extension. Shows property/value pairs for all server metrics.

Memcache Statistics - Slab Cache Dump /admin/reports/memcache/{cluster}/{server}/{type}/cachedump/{slab}

Displays the contents of a specific memcache slab, showing cached keys with their sizes and expiration times. Requires the 'access slab cachedump' permission. Only available with the Memcache extension.

Access memcache statistics

Allows users to view memcache statistics on the reports page and see per-page statistics when enabled. This is a standard permission without special security restrictions.

Access cachedump of memcache slab

Allows users to view the contents of individual memcache slabs, including cached keys and their metadata. This is a restricted permission because it can expose potentially sensitive cache data.

Failure to set key error message

Upgrade your PECL memcache library to version 2.2.1 or higher. Also check that zlib compression at the php.ini level is not conflicting with memcache (see http://drupal.org/node/273824).

SERVER_ERROR object too large for cache

Modify the memcached configuration file (/etc/memcached.conf) to increase the maximum item size: --max-item-size=5M. The default is 1MB which may be insufficient for some cached items.

No memcache extension found error

Install either the PECL memcache or memcached PHP extension. For most systems: pecl install memcache or pecl install memcached. Ensure the extension is enabled in php.ini.

Cache inconsistency with multiple servers

Enable consistent hashing distribution. For PECL memcache: set memcache.hash_strategy=consistent in php.ini. For PECL memcached: this is the default, but can be explicitly set via $settings['memcache']['options'][Memcached::OPT_DISTRIBUTION] = Memcached::DISTRIBUTION_CONSISTENT.

Connection refused or timeout errors

Verify memcached daemon is running (systemctl status memcached). Check firewall rules if memcached is on a remote server. Verify the configured host:port matches the memcached daemon configuration.

Statistics not showing in admin

Ensure you have the 'access memcache statistics' permission. If viewing per-page statistics, enable the option at /admin/config/system/memcache. Note that statistics are not shown for anonymous users.

The 'access slab cachedump' permission can expose sensitive cached data including session information and user data. Grant this permission only to highly trusted administrators.
SASL authentication should be enabled for memcached servers accessible over untrusted networks to prevent unauthorized access.
Memcached has no built-in access control beyond network-level security. Ensure memcached ports are firewalled appropriately.
Cached data is stored unencrypted in memory. Do not store highly sensitive data in cache bins without additional encryption.