Redis
Integrates Drupal with Redis key-value store, providing cache, lock, flood, and queue backends for improved performance.
redis
Install
composer require 'drupal/redis:8.x-1.11'
Overview
The Redis module provides comprehensive integration between Drupal and the Redis key-value store (as well as compatible alternatives like Valkey). It offers high-performance alternatives to Drupal's default database-backed services by leveraging Redis's in-memory data structure store.
The module supports three different Redis client libraries: PhpRedis (PHP extension), Predis (pure PHP library), and Relay (PHP extension with in-memory caching). It automatically selects the first available client based on priority, though a specific client can be configured explicitly.
Key features include a Redis-based cache backend with support for cache tags, data compression, and configurable TTL settings; a distributed lock backend for synchronizing access to resources across multiple web servers; a flood backend for rate limiting and brute-force protection; and both basic and reliable queue implementations for background task processing.
The module also provides a detailed administrative report showing Redis connection status, memory usage, cache statistics per bin, cache tag invalidations, and render cache analysis to help identify performance bottlenecks.
Features
- Redis cache backend with full cache tag invalidation support and automatic checksum tracking
- Optional gzip compression for cached data to reduce memory usage (configurable threshold and level)
- Support for three Redis client libraries: PhpRedis, Predis, and Relay with automatic selection
- Distributed lock backend for multi-server environments supporting both regular and persistent locks
- Flood protection backend for rate limiting login attempts and other brute-force protection
- Basic queue backend for background task processing with lease time support
- Reliable queue backend implementing ReliableQueueInterface for guaranteed delivery
- Administrative report showing Redis status, memory usage, connected clients, keys per cache bin, and cache tag statistics
- Support for Redis Sentinel high availability mode with master/slave configuration
- Support for Redis replication with primary/replica configuration (Predis)
- Configurable cache prefix for multi-site environments sharing a single Redis instance
- Configurable permanent TTL per cache bin with support for human-readable intervals
- Bootstrap container cache support for using Redis before Drupal is fully initialized
- In-memory caching support with Relay for ChainedFastBackend-like performance
- Support for igbinary serialization for optimized storage and unserialization speed
Use Cases
High-traffic website caching
Replace database-backed cache with Redis for significantly improved performance on high-traffic sites. Redis's in-memory storage provides sub-millisecond cache reads compared to database queries. Configure with: $settings['cache']['default'] = 'cache.backend.redis' and include example.services.yml for cache tag invalidation support.
Multi-server load-balanced environment
Use Redis as a shared cache backend across multiple web servers behind a load balancer. All servers connect to the same Redis instance, ensuring cache consistency. The distributed lock backend prevents race conditions when multiple servers attempt to rebuild caches simultaneously.
Brute-force login protection at scale
Replace the database flood backend with Redis for efficient rate limiting. Redis's atomic increment operations and TTL-based expiration handle high volumes of authentication attempts without database load. Configure in example.services.yml or custom services.yml.
Background job processing with reliable queues
Use Redis reliable queues for mission-critical background processing where job loss is unacceptable. The reliable queue tracks claimed items and automatically releases them if the worker crashes. Configure with: $settings['queue_default'] = 'queue.redis_reliable'.
Optimizing render cache with compression
Enable gzip compression for large render cache entries to reduce Redis memory usage. Set $settings['redis_compress_length'] = 100 to compress entries larger than 100 bytes. Particularly effective for page and render cache bins with large HTML fragments.
Multi-site installation with shared Redis
Run multiple Drupal sites on shared infrastructure using a single Redis instance. Configure unique cache prefixes per site: $settings['cache_prefix'] = 'site1_' to prevent key collisions while sharing the Redis server resources.
High-availability Redis with Sentinel
Configure Redis Sentinel for automatic failover in production environments. Set sentinel hosts as an array and specify the instance name: $settings['redis.connection']['host'] = ['sentinel1:5000','sentinel2:5000'] and $settings['redis.connection']['instance'] = 'mymaster'.
Maximum performance with Relay
Use the Relay PHP extension for additional performance gains through its built-in in-memory cache, similar to ChainedFastBackend but more efficient. Configure specific bins to use Relay's memory cache: $settings['redis_relay_memory_bins'] = ['container', 'bootstrap', 'config', 'discovery'].
Tips
- Use volatile-lfu eviction policy for optimal cache eviction behavior - it evicts least frequently used items with TTL while protecting cache tags
- Enable compression with $settings['redis_compress_length'] = 100 to significantly reduce memory usage for text-heavy caches
- Set $settings['redis_invalidate_all_as_delete'] = TRUE for improved performance by avoiding dual invalidation checks
- Configure specific permanent TTLs for large cache bins like page and render to help Redis manage memory: $settings['redis_perm_ttl_page'] = '3 days'
- Use the Redis report at /admin/reports/redis to identify render cache entries with excessive variations - these indicate missing cache contexts
- When using Relay, bypass ChainedFastBackend for config, discovery, and bootstrap bins since Relay provides its own efficient in-memory caching
- Set redis_ttl_offset to enable expired cache item recovery while still allowing Redis to eventually evict old items
- Store persistent data like queues in a separate Redis instance with AOF persistence enabled to prevent data loss
- Monitor cache tag invalidation counts in the report - high counts for specific tags may indicate inefficient invalidation patterns
- For development environments using DDEV, install ddev-redis add-on and override host to 'redis' in settings.php
Technical Details
Admin Pages 1
/admin/reports/redis
Displays comprehensive Redis usage statistics and connection status. Shows warnings about configuration issues, cache tag invalidation counts, connected client information, Redis version and mode, number of stored keys, memory usage with eviction policy, server uptime, read/write statistics, keys per cache bin breakdown, render cache entries with most variations, and most invalidated cache tags.
Permissions 1
Hooks 2
hook_help
Provides help text for the Redis module showing current client connection status.
hook_requirements
Checks Redis connection status during runtime and reports it on the status report page.
Troubleshooting 8
Ensure the Redis server is running and accessible. Check the status report at /admin/reports/redis or run 'drush status-report' to verify connection. Ensure redis.services.yml is included in settings.php. Verify the PHP extension (phpredis) or library (predis) is installed and available.
Configure an appropriate eviction policy in Redis: 'maxmemory-policy volatile-lfu' is recommended. Set a maxmemory limit. The module sets TTL on all cache entries, making volatile eviction policies effective. Avoid 'noeviction' policy as it will cause errors when memory is full.
The drush cr command does not flush Redis storage by design - it only invalidates caches. Items remain in Redis until TTL expiration or eviction. To manually clear Redis: 'redis-cli flushall' or via Drush: drush php:eval "\Drupal::service('redis.factory')->getClient()->flushAll()"
Ensure the cache tag checksum service is overridden in example.services.yml or custom services.yml. The 'cache_tags.invalidator.checksum' service must use RedisCacheTagsChecksum class. Include: $settings['container_yamls'][] = 'modules/contrib/redis/example.services.yml'
Managed Redis services may disable the CONFIG command for security. Recent module versions handle this gracefully. Update to the latest version. Some statistics in the report may be unavailable without CONFIG access.
Replace the default lock service with Redis lock backend by including example.services.yml. This provides distributed locking across all web servers. Ensure all servers connect to the same Redis instance.
By default, Redis does not persist data (or uses RDB snapshots that may lose recent data). For reliable queues, either configure Redis AOF persistence or use a separate persistent Redis instance for queues. Consider using the database queue for truly critical data.
Check if Redis maxmemory is set too low causing frequent evictions. Use 'redis-cli INFO' to check memory usage. Consider enabling compression for large cache entries. For Relay users, verify in-memory caching is enabled for appropriate bins. Check network latency if Redis is on a remote server.
Security Notes 8
- Restrict access to the Redis report page using the 'access redis report' permission - it exposes cache structure information
- Configure Redis to bind only to localhost or internal network interfaces, never expose Redis directly to the internet
- Use Redis authentication (requirepass) for any Redis instance accessible from multiple machines
- When using Redis replication, ensure all connections use authentication
- Cache data may contain sensitive information - ensure Redis access is properly secured at the network level
- The flood backend stores IP addresses - ensure Redis access controls comply with privacy requirements
- Consider network encryption (TLS/SSL) for Redis connections over untrusted networks
- Never store unencrypted secrets in Redis queues - use encryption for sensitive job data