Flushing

Cache flushing in WordPress is deceptively simple on the surface — wp_cache_flush() — but in practice it can be slow, disruptive and affect unrelated sites when Redis is shared between multiple WordPress installations.

If more than one WordPress site uses the same Redis database, a cache flush will wipe data for all sites. Each WordPress installation should use its own dedicated Redis database. While using a prefix will avoid data collisions, it will not prevent cache flushes from affecting all sites and is strongly recommended against.

  1. Full Cache Flush
  2. Group Flushing
  3. Network Flushing
  4. Pattern deletion method

Full Cache Flush

By default wp_cache_flush() calls FLUSHDB and removes all keys in the current Redis database instantly. This is fast and atomic, but indiscriminate — everything is gone.

Group Flushing

When wp_cache_flush_group() is called, only the keys belonging to that specific cache group are removed. This adds significant complexity to flushing, because Redis has no native concept of cache groups — keys must be found by pattern and deleted individually. This is why Object Cache Pro 2.0 introduced atomic group flushing, which sidesteps the problem entirely by storing groups in Redis/Valkey hashes.

The group_flush option controls how this happens:

  • scan: Lua script using SCAN to find and delete keys atomically. Default.
  • atomic: Hash-based group storage with key expiration. Recommended for 2.x.
  • keys: Lua script using KEYS to find and delete keys atomically. Not recommended for large datasets.
  • incremental: PHP-side SCAN iteration, deletes in chunks. Non-atomic.
  • full: Flushes the entire cache.

The atomic method stores cache groups in hashes and uses hash field expiration to flush them. It requires:

  • Redis 8.0 or Valkey 9.0
  • PhpRedis 6.3 or Relay 0.12.1
define('WP_REDIS_CONFIG', [
    'group_flush' => 'atomic',
]);

Network Flushing

In a multisite network, all sites share the same Redis database. By default, calling wp_cache_flush() flushes the entire database — destroying cached data for every site in the network.

The network_flush option provides granular control:

  • all: Flushes the entire cache. Standard WordPress behavior. Default.
  • site: Flushes only the current site’s cache keys. Global groups are not touched.
  • global: Flushes the current site’s keys and all global group keys (e.g. users, usermeta).

When set to site or global, a call to wp_cache_flush() invokes flushBlog() instead of flush(), which constructs wildcard patterns for the target site’s keys and deletes them using pattern-based key deletion.

Setting network_flush to site or global also enables the “Flush” site action under Network Admin > Sites.

Pattern deletion method

Network flushing uses a SCAN-based Lua script to find and delete matching keys. This works well for most sites.

On very large multisite networks where a single Lua script would be too slow, the pattern_flush option can be set to incremental to use PHP-side SCAN iteration instead, which deletes keys in smaller chunks without blocking Redis. A value of keys is also available but not recommended for large datasets.

Most users do not need to set pattern_flush — it defaults to scan automatically.

define('WP_REDIS_CONFIG', [
    'network_flush' => 'global',
    'pattern_flush' => 'scan',
    'async_flush' => true,
]);