How the WordPress transient API works, and when `wp transient delete` actually helps

WordPress offers an in-built feature known as the transient API, allowing developers to temporarily store data for a predetermined period before it becomes invalid. This comes in handy for caching external API responses or the results of complex computations within WordPress core and numerous plugins. However, without proper understanding of how it works, expired entries can accumulate, gradually increasing the database size.

The transient API is essentially a set of PHP functions - set_transient(), get_transient(), and delete_transient() - that manage cache entries along with an expiration period.

Saving a transient involves defining three parameters: the value, the key, and the expiration in seconds. The stored value's location depends on the website's setup: In the default setup (common on shared hosting), the data resides in the wp_options table, specifically in rows named _transient_key_ and _transient_timeout_key_. If a persistent object cache like Redis or Memcached is used, the data gets stored there instead of wp_options.

When get_transient() is invoked, WordPress compares the stored timeout value against the current time, and returns false if the entry has expired. However, the cleanup process for expired entries isn't as straightforward as it seems. Theoretically, an expired transient should vanish. Yet in reality, wp_options can amass a lot of long-expired rows due to two factors: get_transient() is not called again for that key.

The automatic cleanup mechanism is passive, only triggering when someone tries to read the value and discovers it's expired. This isn't an active sweep. Moreover, WP-Cron's garbage collection doesn't run unless a page is visited, and on sites with light traffic, this cleanup can go on for long periods without executing. The situation worsens when most _transient_-prefixed options are saved with autoload set to yes, meaning WordPress loads them into memory on every single page request, even if those pages don't need them.

While a few stale rows are harmless, hundreds can start slowing down every page load, regardless of whether the cached values are used or not.

WP-CLI provides specialized commands to manage transients: wp transient list lists all currently stored transients; wp transient delete key removes a specific key; wp transient delete --expired deletes only the expired entries; and wp transient delete --all wipes out all transient data, live or expired. The latter could potentially disrupt other plugins as it removes live, still-valid cache entries, prompting them to recompute or re-fetch data immediately afterward.

For routine maintenance, --expired is the safer option. In case of a significant slowdown, a site administrator might consider running wp transient delete --expired. Also, upon swapping or bulk-removing plugins, some may leave orphaned _transient_ rows behind, needing to be cleaned up. Including transient cleanup in the regular maintenance routine, such as wp db check / wp db optimize, could help catch any autoload bloat before it impacts performance.

So, the transient API's effectiveness hinges on regular usage of get_transient() and proper functioning of WP-Cron's garbage collection. A regular transient audit using WP-CLI commands can help detect autoload bloat before it becomes a noticeable performance issue.