mod_memcached caches content on memcached servers

lookup tries to find data associated with the key, and returns it as http body with status 200 if it finds something.
store stores a http body (generated by another backend) in memcached.

Caching always requires you to think about what you want; you cannot cache content that changes with every request!

So most of the time you probably want to set a TTL for the stored content in memcached; your users probably don’t need new content to be available the next second, perhaps 60 seconds is still good (obviously not true for a chat…).

The other way is to purge the keys in your dynamic backend; you can set the memcached content from your backend too, which probably is faster than

If the key is longer than 255 bytes or contains characters outside the range 0x21 - 0x7e we will use a hash of it instead (for now sha1, but that may change).

memcached.lookup (action)

searches the content in a memcached database

memcached.lookup (options, action-hit, action-miss);
A key-value table with the following entries:
socket address as string (default:
(boolean, not supported yet) whether to lookup headers too. if false content-type determined by request.uri.path (default: false)
pattern for lookup key (default: "%{req.path}")
action to run on cache hit (lookup was successful)
action to run on cache miss (lookup was not successful) (action)

stores the generated response in a memcached database options;
A key-value table with the following entries:
socket address as string (default:
(integer) flags for storing data (default 0)
ttl for storing (default 30; use 0 if you want to cache "forever")
maximum size in bytes we want to store (default: 64*1024)
(boolean, not supported yet) whether to store headers too (default: false)
pattern for store key (default: "%{req.path}")


setup {
	module_load "mod_memcached";

memcached.lookup (["key" => "%{req.scheme}://%{}%{req.path}"], {
	header.add "X-Memcached" => "Hit";
}, {
	header.add "X-Memcached" => "Miss";
	docroot "/var/www";
#	important: You need a content handler before
	static; ["key" => "%{req.scheme}://%{}%{req.path}"];


mod_memcached exports a Lua API to per-worker luaStates too (for use in lua.handler): creates a new connection; a connection provides:

  • req = con:get(key, cb | vr)
  • req = con:set(key, value, cb | vr, [ttl])
  • con:setq(key, value, [ttl])

If a callback was given, the callback gets called with a response object; otherwise the response will be in req.response when ready.

The response object has:

  • code: 1 – Ok, 2 – Not stored, 3 – Exists, 4 – Not found, 5 – Error
  • error: error message
  • key: the lookup key
  • flags
  • ttl
  • cas
  • data