Picking the right cache

MediaWiki has a variety of caching and persistence layers. Each layer has its own advantages and disadvantages, uses and misuses. In general, when choosing where to store data in MediaWiki, you should take into consideration the following:

  • Is the data original, or is it generated from other data?
    • How long does it take to regenerate the data?
  • How big is the data, and what format is it in?
  • For how long is the data expected to be stored and retrievable?

The goal of this document is to force you to answer these questions, and then provide suggestions on where your data should be stored in MediaWiki.


Layer name Description Structured Persistent Per-user
LocalStorage This is a client-side storage layer in the user's browser. No Yes Yes
Browser cache This is an HTML-only cache implemented in the user's browser. It caches web pages delivered by MediaWiki, and can be controlled via caching headers sent to the browser No No Yes
CDN cache This is server-side cache proxy that is implemented by a software separate from MediaWiki (e.g. Varnish at WMF). It stores copies of web responses from MediaWiki, such as HTML, JS and CSS. No No No
Object cache These are server-side key-value caches within MediaWiki. They are accessible via a service class, such as LocalServerObjectCache, MainWANObjectCache , and MainObjectStash (see Manual:Object cache)

Each of these is backed by a BagOStuff subclass, abstracting php-apcu, Memcached, Redis, or MySQL. See also Memcached at WMF.

No No Yes

Interface v. implementation


It is important to note that there is a fundamental separation between the interface of a caching layer and its implementation. The difference between the two is that the interface is the contract between the programmer and MediaWiki. When a caching layer has a certain property in its interface, it is guaranteed to follow that property.

For example, the object cache layer is listed in the above summary as being "not persistent". This is an interface detail. It means that when you use that caching layer, you should expect data to be erased at any moment. However, it is implementation-defined as to when and how data is erased. In other words, it is actually possible for a given implementation of the object cache layer to be persistent! All it has to do is never erase data. However, nonetheless, programmers should still consider it to be non-persistent, and use the layer as if data could disappear at any moment.

In MediaWiki, every caching layer has a number of implementations. Each implementation functions differently, but is guaranteed to follow the contract of the layer. Here are some example implementations for each layer:

LocalStorage and Browser cache
Google Chrome
HTTP cache
Object cache
Session data
Built-in PHP file-based sessions
SQL store

Notice that some implementations can be used for different layers, e.g., Redis functions as both an object cache, a session data store, and a key-value store. This is because of the idea explained above. Since an object cache can be persistent (it is just assumed not to be), Redis can be used to implement it.

Browser-level storage


The first step in caching is the user's browser. The browser has LocalStorage (among others, such as WebSQL, which MediaWiki does not use at the moment) and an HTML page cache. Some properties of browser caches are:

  • They are not just per-user, but per-browser, meaning a user can change computers and the cache will be different. This cache should only be used for data that can be re-fetched from the server if necessary.
  • They are entirely client-side. Thus there is no download necessary, and accessing the cache is very fast for the user. Of course, this means that you do not have access to any server-side resources.
  • The vary greatly between implementations. Unfortunately, not every browser implements caching the same way. There are standard interfaces, as set forth by W3, and in many cases the browser will stick to the standard, but always expect the unexpected.

A notable user of LocalStorage in MediaWiki by default is ResourceLoader, which uses it to cache JavaScript bundles. Read more about this at ResourceLoader/Architecture#Store.

Object cache


The object cache is perhaps the most used caching layer in MediaWiki. It is usually implemented by either Memcached or Redis, and functions as a quick way to cache results of expensive operations. This layer is not persistent, and you should expect data stored in this layer to disappear at any time, without warning! Of course, since it is a cache, the data will not disappear immediately, and in general you can expect the object cache to store data for a fairly long period of time.