Skip to content

Caches

A cache stores volatile, ephemeral data. CiviCRM has multiple caches which may be stored in different ways, depending on the particular data and the environment/configuration.

CiviCRM's default configuration is designed to minimize system-requirements and maximize compatibility -- you only need PHP and MySQL. This simplifies installation on self-hosted infrastructure.

The default configuration stores caches in MySQL, and this works well for most sites. On busier sites, a specialized cache service such as Redis or Memcache can reduce the load on the database by keeping volatile data in RAM. Many sites in the CiviCRM community run Redis for this reason.

A cache service is not a free win, though. Every backend stores entries as serialized PHP data, so each read still transfers the whole entry and unserializes it on the web server. A cache service takes these reads off the database, but the CPU time on the web server stays. Whether the trade-off pays off depends on the site and its workload, so monitor database load and response times before and after the change.

What data (exactly) is stored where (exactly)?

Data Redis Memcache(d) FileCache APCucache Default
Configuration metadata, settings, session/form state Redis Memcache Files APCu MySQL
Search results paged over multiple screens Redis MySQL MySQL MySQL MySQL
Smart group memberships, ACL caches MySQL MySQL MySQL MySQL MySQL
  • Smart group and ACL caches always stay in MySQL because search queries join against them directly.
  • Search results follow the setting PrevNext Cache (prevNextBackend). Its default uses Redis when Redis is configured; there is no Memcache implementation.
  • A few small caches (e.g. the extension browser) always use MySQL.

Choose a cache service

CiviCRM integrates with the following specialized cache services:

  • Redis is a lightweight memory-backed cache service with a few features for system administration (eg basic access-control; optional logging/persistence) and development (eg richer cache APIs).
  • Memcached is well-known for defining the genre of minimalist memory-backed cache services, and it remains true to its original minimalism.
  • APCu keeps cache data in the shared memory of the local PHP process pool. It needs no extra service but is not suitable if you have multiple web-servers, and it is experimental (see below).
  • The file cache (CiviCRM 6.1+) stores cache data as files under [civicrm.private]/filecache. It needs no extra service and may suit single-server deployments.

These services are used by many PHP applications, so your hosting provider may already support one of them.

If you're free to choose and have no particular preference, then use Redis. It provides a good balance of performance and functionality.

APCu is experimental

Treat the APCucache driver as experimental: APCu memory is private to each PHP process pool, so cv flush and other command-line tools cannot clear the cache used by the web server (dev/core#6837).

Install the cache service and driver

For Redis or Memcached, you will need to install the server and a PHP driver, e.g.

Most Linux distributions package both, e.g. on Debian/Ubuntu apt install redis-server php-redis or apt install memcached php-memcached. For other platforms, see the official instructions:

For APCu, install only the PHP extension, e.g. apt install php-apcu on Debian/Ubuntu or pecl install apcu, and restart PHP-FPM or the web server. Raise apc.shm_size in php.ini if the default (32M) is too small for your site.

The file cache needs no installation; the web server must be able to write to [civicrm.private].

Once you've installed, you should have a few pieces of information:

  • Redis: Hostname (e.g. localhost), port (e.g 6379), and optionally a password
  • Memcache: Hostname (e.g. localhost), port (e.g 11211)

Configure the CiviCRM cache

The cache service is an essential part of CiviCRM that must be available at the very beginning of each page-request. To configure CiviCRM to use a cache, edit the civicrm.settings.php and update the define() statements for CIVICRM_DB_CACHE_* options. Below are some examples followed by a more detailed reference.

Example: Memcache

define('CIVICRM_DB_CACHE_CLASS', 'Memcached'); // Or the alternate 'Memcache'
define('CIVICRM_DB_CACHE_HOST', '127.0.0.1');
define('CIVICRM_DB_CACHE_PORT', 11211);
define('CIVICRM_DB_CACHE_PREFIX', 'example.com');

Example: Redis

define('CIVICRM_DB_CACHE_CLASS', 'Redis');
define('CIVICRM_DB_CACHE_HOST', '127.0.0.1');
define('CIVICRM_DB_CACHE_PORT', 6379);
define('CIVICRM_DB_CACHE_PASSWORD', 'topsecret');
define('CIVICRM_DB_CACHE_PREFIX', 'example.com');

If you are using Redis with a Standalone install, you probably also want to store PHP sessions in Redis; otherwise they are stored in the civicrm_session table. This is required if you also use rpow. Configure the phpredis session handler in your php.ini:

session.save_handler = redis
; Use your Redis host/port; omit "?auth=..." if Redis has no password.
session.save_path = "tcp://127.0.0.1:6379?auth=topsecret"

Optionally, enable session locking:

; Should the locking be enabled? Defaults to: 0.
redis.session.locking_enabled = 1
; How long should the lock live (in seconds)? Defaults to: value of max_execution_time.
redis.session.lock_expire = 60
; How long to wait between attempts to acquire lock, in microseconds (µs)? Defaults to: 20000
redis.session.lock_wait_time = 50000
; Maximum number of times to retry (-1 means infinite). Defaults to: 100
redis.session.lock_retries = 2000

Example: APCu or file cache

define('CIVICRM_DB_CACHE_CLASS', 'APCucache'); // Or 'FileCache'
define('CIVICRM_DB_CACHE_PREFIX', 'example.com');

Development and testing

Leave the cache service disabled for headless tests, which expect the default cache. On development sites, a persistent cache can also hide changes until you flush it.

Reference

  • CIVICRM_DB_CACHE_CLASS: Specifies the type of driver. The following values are allowed:
    • APCucache - Use the PHP APCu extension (CiviCRM 5.62+). Experimental, see above.
    • ArrayCache (default) - Use an temporary, in-memory cache (unique for each page-request).
    • FileCache - Store cache data as files under [civicrm.private]/filecache (CiviCRM 6.1+)
    • Memcache - Use the PHP memcache extension
    • Memcached - Use the PHP memcached extension
    • NoCache - Do not cache anything
    • Redis - Use the PHP redis extension
  • CIVICRM_DB_CACHE_HOST: The hostname or IP address of the remote server. (Applies to Memcache, Memcached, Redis.)
  • CIVICRM_DB_CACHE_PORT: The port number of the remote server. (Applies to Memcache, Memcached, Redis.)
  • CIVICRM_DB_CACHE_PASSWORD: A secret that grants access to the cache-server. (Only applies to Redis.)
  • CIVICRM_DB_CACHE_PREFIX: A unique prefix that differentiates your CiviCRM cache. (Applies to APCucache, FileCache, Memcache, Memcached, Redis.)
    • The prefix is strongly recommended but not strictly required. Setting a unique prefix serves a few purposes:
      • If the cache server is shared with other applications, the prefix prevents collisions between applications.
      • If the cache server is used in a multisite/multienant environment, the prefix prevents collisions between sites.
      • When debugging or inspecting a cache, the prefix helps you identify the origin of each cache record.