Getting Started with Memcached

You will need to have an administrator account on the Ubuntu box you are setting up. If you are performing some tests then most likely any machine would do the job but if you are setting this up as a production environment, you will need a machine with a decent amount of free memory for the caching job.

Update your apt local repository by using:

sudo apt-get update

When asked for the password, just enter your account password to give permission to the application to run as root.

First, we pulled the latest packages information from the apt repository online to make sure we are downloading the latest version of memcached to our local server. Then we simply used the apt-get command to download and auto-install the memcached package.

The installation script also starts the memcached daemon and marks this service to be auto-started on every boot of our Ubuntu box.

We validated that memcached was properly started by checking the running processes with the ps command and grep-ing to see only processes with the word memcached in them.

It's also important to note here that the default configuration of memcached limits the memcached daemon to listen only on the loopback device (localhost). This means that you can connect to your memcached daemons only from local processes running on the same computer.

Let's take a look at the configuration of the memcached daemon installed on our Ubuntu server.

Open the configuration file located at /etc/memcached.conf and locate the line where you see something like the following:

-l 127.0.0.1

This tells the memcached daemon to listen only on the localhost, note that this is the only security measure that memcached can offer, so make sure it's listening on a firewalled interface.

Change it to the following if you want the daemon to listen on all interfaces.

-l 0.0.0.0

Also locate the following line:

-m 64

This configuration parameter configures the upper cap of how large the in-memory storage can grow to. The default here is 64 megabytes. This means that you can store up to 64 MB worth data on your memcached daemon, but this doesn't mean that the daemon will allocate this memory on its boot.

We will be using a package manager for Mac OS X that is really a must-have tool for any Mac user and even more important if you are a developer or a system engineer.

The package manager we will be using is Homebrew, the missing package manager for OS X

You will need to install Homebrew first if you don't have it, installation is straightforward and all instructions are explained in different languages for your comfort at http://brew.sh/.

Or you can simply use this one liner to install Homebrew on your Mac:

ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"

We started by updating the local copy of the Homebrew repository from the Internet using the brew update, this ensures we are installing the latest version of any package we want to. Then we installed the latest version of memcached.

Homebrew does not start memcached automatically after installation nor during boot time, so we had to do this ourselves.

You can always start memcached manually in the foreground by using the memcached daemon executable. But if you want memcached to start on boot we created a symlink so that launchctl picks it up on boot.

If you have configured your memcached daemon to start on boot as previously described, you might be wondering, where is the default configuration? Is it in the same place as Ubuntu? The answer is No!

Because the memcached service will be started by launchctl, the configuration is controlled by it. You will find the configuration file at /usr/local/opt/memcached/homebrew.mxcl.memcached.plist and it's basically an XML file.

See the following section in the file:

 <array>
 <string>/usr/local/opt/memcached/bin/memcached</string>
 <string>-l</string>
 <string>localhost</string>
 </array>

As you may have discovered yourself, this represents a list of parameters passed to the memcached executable at runtime.

You can edit the localhost field, as previously described in the Ubuntu configuration section, but if you want to configure the amount of memory that memcached can use, you will need to insert a couple of directives for that directly after the localhost directive:

<string>-m</string><string>256</string>

This configures memcached to use up to 256 MB of memory for its on-memory storage.

Another option if you are not a Homebrew user, is to use MacPorts (http://www.macports.org/), it works almost the same way and you can use the command port instead of brew.

Another interesting feature of brew, is that you can specify options to control the way memcached is built (compiled), so most of the time you don't really need to compile memcached from source on Mac OS X, instead, you use brew options for that. An example, is to enable SASL support to disable the plain ASCII protocol or to add SASL with password option, as stated in the brew info memcached.

--enable-sasl
      Enable SASL support -- disables ASCII protocol!
--enable-sasl-pwdb
      Enable SASL with memcached's own plain text password db support -- disables ASCII protocol!

So, for example, if you want to enable SASL support during installation, use the following:

brew install memcached --enable-sasl

We will install the requirements of the package by using apt-get:

sudo apt-get install g++ make libevent-dev

This installed the C++ compiler , make, and the libevent library headers needed to compile memcached.

You will need to have telnet client installed on your machine, in most cases you will find it already installed but in case you didn't find it you can install it on your Ubuntu box using

sudo apt-get install telnet

You also must make sure that the memcached daemon is actually running.

Connect to the running memcached daemon with telnet on port 11211.

telnet localhost 11211

You should see something like the following:

Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.

So, let's play with some basic storage commands to understand the main concepts behind memcached. We believe that this way is the best way to understand the features of the service and to truly realize its design simplicity and power.

Memcached supports a plain ASCII (text) protocol, you can find the protocol definition and specifications in the document in this link https://github.com/memcached/memcached/blob/master/doc/protocol.txt

This recipe gives you a glimpse of the kind of commands you can send to your memcached daemon using a simple tool like telnet.

We started by connecting to the memcached daemon on the default port 11211 using telenet. Then we used the stats command which asks the daemon to send us some useful statistics from the service such as the uptime, how many get requests actually returned data get_hits, and how many get requests resulted in a miss hit get_misses.

Then, we used stats settings which prints out the settings and configuration of the current running daemon, you will be able to see things such as tcpport which points to the port it is listening to and something such as maxbytes which is the maximum number of bytes allowed in this cache server.

Then, we moved to the storage commands set and get. Storage commands have the following format:

<command name> <key> <flags> <exptime> <bytes>

The <command name> field can be set, add, replace, append, or prepend.

The <key> field is the name of the key you are storing, in our case that was mykey.

The <flags> field is an arbitrary 16-bit unsigned number that the server stores along with the key and is returned when the client requests to get the value. It's opaque to the server, so it doesn't give any special meaning to the server itself but the client can use this number to add some special meaning to this key if needed. In our case, we just passed 0 for this field.

The <exptime> field indicates the expiration time, if it's 0, the item never expires (although it might get deleted when the server needs to free up place for another key to be stored). If it's non-zero (either Unix time or offset in seconds from the current time), it is guaranteed that clients will not be able to retrieve this item after the expiration time arrives (measured by the server time).

The <bytes> field indicates the length of the value to be stored, in our case that was 16, which is the length of the words I Love Memcached.

After hitting your return (Enter) key, you are supposed to feed the server with the value to be stored along with the key. Then, after hitting another return, you receive a STORED message indicating that the key-value pair has been stored.

Then, we moved to get, it's very simple, you get a <key> field and the value returns along with the <flags> field and the length of the value, then the value is printed before the END sentinel.

VALUE mykey 0 16
I Love Memcached
END

On server installations, we need to ensure that memcached is automatically started on boot if it's not already.

We are using update-rc.d script to create and delete symbolic links at /etc/rcX.d/ where X is the runlevel number.

Those symlinks are scanned on boot and they control whether the service is going to be started or not, based on the initial letter.

If you have seen the output of update-rc.d memcached enable

   Enabling system startup links for /etc/init.d/memcached.
   Removing any system startup links for /etc/init.d/memcached:
   /etc/rc0.d/K20memcached
   /etc/rc1.d/K20memcached
   /etc/rc2.d/K80memcached
   /etc/rc3.d/K80memcached
   /etc/rc4.d/K80memcached
   /etc/rc5.d/K80memcached
   /etc/rc6.d/K20memcached
   Adding system startup for /etc/init.d/memcached:
   /etc/rc0.d/K20memcached -> ../init.d/memcached
   /etc/rc1.d/K20memcached -> ../init.d/memcached
   /etc/rc6.d/K20memcached -> ../init.d/memcached
   /etc/rc2.d/S20memcached -> ../init.d/memcached
   /etc/rc3.d/S20memcached -> ../init.d/memcached
   /etc/rc4.d/S20memcached -> ../init.d/memcached
   /etc/rc5.d/S20memcached -> ../init.d/memcached

You will see that the symlinks may start with K or S. which indicates that in a certain runlevel, the system should Kill or Start the service, respectively.

So, it all starts when a single server cannot hold your entire cache and you need to split the cache pool across several servers.

If you are running multiple instances of the memcached daemon on the same server, make sure you are running them on different ports.

memcached -p 3030
memcached -p 3031

The server installation goes as previously described and the cluster configuration goes to your client by adding the list of servers to all your clients.

It's important to note that in order to ensure that the cluster is sane, is to have the same order of servers in all of your clients.

As an example, I'll be using python's pylibmc library to communicate with the memcached cluster:

import pylibmc
mc = pylibmc.Client(["127.0.0.1:3030", "127.0.0.1:3031"], binary=True, behaviors={"tcp_nodelay": True, "ketama": True})
mc["ahmed"] = "Hello World"
mc["tek"] = "Hello World"

What happens is that you specify a list of your servers to your client configuration and the client library uses consistent hashing to decide which server a certain key-value should go to.

The constructor of the client object here was fed with a couple of interesting parameters:

After we have created the client object, we have set two keys ahmed and tek with the value Hello World and what actually happens behind the scenes is that each key-value pair is actually stored on a different daemon, according to the consistent hashing of the key.

I'm assuming you are using Ubuntu; you will need to have the simple setup of apache2 and php5. It's simple to get this stack working using this command:

sudo apt-get install apache2 php5

First, we need to install the PHP memcache extension using apt-get:

sudo apt-get install php5-memcache

This automatically installs the extension and gets everything wired and configured for you, if you want to use the memcached extension instead, all you need to do is to replace php5-memcache with php5-memcached and voila, everything just works!

If you are using Mac OS X, it's a slightly different story, and you will need to install apache2 and php5.

One of the quickest ways to do so is to install a nice package called MAMP (http://www.mamp.info/en/index.html); it will make life a lot easier for you. But, if you are an advanced user and want to go with the more manual route, you get really detailed instructions to get your OS X setup ready with Apache, MySQL, and PHP ready at (http://jason.pureconcepts.net/2012/10/install-apache-php-mysql-mac-os-x/).

First, we are creating the Memcache object, that's the object we will be using to communicate with our memcached server in an object-oriented manner.

Then, we initialize the connection to the memcached server using the connect method that has the following signature which takes the host, port, and connection timeout:

bool Memcache::connect ( string $host [, int $port [, int $timeout ]] )

The connect method closes the connection to the memcached server automatically at the end of the execution of the script.

Then, we used the getVersion method to retrieve the version of the memcached server we are connected to. We are using this method only to test our connection to the memcached server.

We then moved to the real work, we created an instance of the stdClass of PHP and added two attributes to the object to serialize and store in memcached under the key "sample_user"; We set the timeout to 15 seconds, this means that the memcached server will delete the key after 15 seconds. We also used false for flags, since we don't need compression or any other setting at the moment.

Then, we retrieved the value back from memcached using the get method of the Memcache object, and then we printed it on the screen. The output of the script would be as follows:

Data stored in cached (will expire in 15 seconds)Object from the cache:object(stdClass)#3 (2) { ["str_attr"]=> string(23) "Memcache in PHP is cool" ["int_attr"]=> int(2468) }

If you are planning to connect to a cluster of memcached servers you will need to add all the servers using the addServer method:

<?php

/* OO API */
$memcache = new Memcache;
$memcache->addServer('memcached_host1', 11211);
$memcache->addServer('memcached_host2', 11211);
?>

Then, start using your memcache instance as usual and the magic will happen.

It's always a good idea to create virtualenv for your experiments to keep your experiments contained and not to pollute the global system with the packages you install.

You can create virtualenv easily:

virtualenv memcache_experimentssource memcache_experiments/bin/activate

We will need to install python-memcached first, using the pip package manager on our system:

sudo pip install python-memcached

The output of the script looks like the following:

Counter was incremented on the server by 1, now it's 11
Counter was incremented on the server by 9, now it's 20
Counter was decremented on the server by 1, now it's 19

The incr and decr methods allow you to specify a delta value or to by default increment/decrement by 1.

Alright, now let's sync a Python dict to memcached with a certain prefix:

import memcache

client = memcache.Client([('127.0.0.1', 11211)])

data = {"some_key1": "value1",
        "some_key2": "value2"}

client.set_multi(data, time=15, key_prefix="pfx_")

print "saved the dict with prefix pfx_"

print "getting one key: %s" % client.get("pfx_some_key1")

print "Getting all values: %s" % client.get_multi(["some_key1", "some_key2"], key_prefix="pfx_")

In this script, we are connecting to the memcached server(s) using the Client constructor, and then we are using the set method to store a standard Python dict as the value of the "sample_user" key. After that we use the get method to retrieve the value.

In the second script, we are playing with some of the features we never tried in the memcached server. The incr and decr are methods that allow you to increment and decrement integer values directly on the server automatically.

Then, we are using an awesome feature that we also didn't play with before, that is get/set_multi that allows us to set or get multiple key/values at a single request. Also it allows us to add a certain prefix to all the keys during the set or get operations.

The output of the last script should look like the following:

saved the dict with prefix pfx_
getting one key: value1
Getting all values: {'some_key1': 'value1', 'some_key2': 'value2'}

In the Client constructor, we specified the server hostname and port in a tuple (host, port) and passed that in a list of servers. This allows you to connect to a cluster of memcached servers by adding more servers to this list. For example:

client = memcache.Client([('host1', 1121), ('host2', 1121), ('host3', 1122)])

Also, you can also specify custom picklers/unpicklers to tell the memcached client how to serialize or de-serialize the Python types using your custom algorithm.

We need to install the Dalli gem using the following command:

gem install dalli

If you don't have the gem tool, then most likely you don't have Ruby properly installed. In Ubuntu you can always use the following to get Ruby installed:

sudo apt-get install ruby

First, we are importing Dalli into our namespace by using the require statement. Then, we are creating a client that connects to the memcached server and we are also setting some options. The following are some of the interesting options:

Then, we used the simple set method to set a basic integer value, after we retrieved that value and printed to the console using puts.

In the second snippet, we created a standard Ruby Hash and we used the built-in serializer to store this hash as a value for the "user1" key.

In the third snippet, we introduced a new feature of memcached, that is replace. This was used to replace the entire hash stored for the "user1" key with a modified version (we added age to it).

While we were replacing the value we also respecified the TTL value and changed the TTL of the value to be 5 seconds only. The replace feature fails if the key is not already stored in the memcached server and that's the main difference between it and the method that you are already familiar with set.

The constructor of the Client class can also accept a list of servers to specify, in case you have a memcached cluster as you can see, it's a list of servers.

Dalli::Client.new(['localhost:11211:10', 'cache-2.example.com:11211:5', '192.168.0.1:22122:5'], :threadsafe => true, :failover => true, :expires_in => 300)

For every server, the format is server:port:weight, where weight allows you to distribute cache unevenly. Both weight and port are optional. If you pass in nil, Dalli will use the MEMCACHE_SERVERS environment variable or default to localhost:11211 if it is not present.

The spymemcached java library has artifacts published on the maven central repository. If you are using maven you will need to add this to your pom.xml file (highlighted):

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.sample</groupId>
  <artifactId>spycache</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>spycache</name>
  <url>http://maven.apache.org</url>
  <dependencies>
   <dependency>
     <groupId>net.spy</groupId>
     <artifactId>spymemcached</artifactId>
     <version>2.10.1</version>
   </dependency>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

In my project here (named spycache), we will be showing snippets written inside the src/main/java/com/sample/ directory and to run the application you will need to run the mvn package.

Then after seeing BUILD SUCCESS you will need to run the application by using the following:

java -cp target/spycache-1.0-SNAPSHOT.jar com.sample.App

The output will be like the following:

2013-10-29 19:22:26.928 INFO net.spy.memcached.MemcachedConnection:  Added {QA sa=/127.0.0.1:11211, #Rops=0, #Wops=0, #iq=0, topRop=null, topWop=null, toWrite=0, interested=0} to connect queue
2013-10-29 19:22:26.935 INFO net.spy.memcached.MemcachedConnection:  Connection state changed for sun.nio.ch.SelectionKeyImpl@680e62df
Employee("Ihab", 26)
2013-10-29 19:22:26.964 INFO net.spy.memcached.MemcachedConnection:  Shut down memcached client

Basically, we are creating a MemcachedClient object that creates our memcached connection, note that this object is quite smart and does automatic reconnect on connection failure. By default, we are using the plain-text protocol but in the second example we are using the new binary protocol which is far more efficient.

The second snippet also shows how to configure MemcachedClient to connect to multiple memcached servers (cluster), automatic data distribution will be done for you.

The first method we used on the client object is set which is actually asynchronous, this means that it works like fire and forget, it does not block the current thread until the actual set operation happens. Then, we used get which is synchronous (the opposite), it blocks until data is retrieved and returns that data as Object, that's why we need casting to get a reference of the correct object type.

Java has an already very stable data serialization mechanism, and that's exactly what we have used. Standard types are serializable by default but what happens if you are trying to serialize your custom Employee object to memcached? You need to implement the serializable interface for that, then magically everything works as presented in the last recipe.

Spymemcached offers an asynchronous API for get as well, it's quite interesting actually and if you are familiar with java.util.concurrent.Future you will find it very easy to follow and understand.

The idea is that client.asyncGet returns a Future<Object> which you can use to retrieve the value asynchronously. You can use this future object to get the actual value later and set a timeout on your get request, as follows:

Future<Object> fobject = client.asyncGet("engineer");
try {
    fobject.get(10, TimeUnit.SECONDS);
} catch (InterruptedException e) {
    e.printStackTrace();
} catch (ExecutionException e) {
    e.printStackTrace();
} catch (TimeoutException e) {
    fobject.cancel(false);
}

What you can see here, is that we tried to get the future and we set 10 seconds for our trial, if the timeout expired, we get a TimeoutException, and then we can safely cancel the operation (by calling cancel() on the future). This means that we are not interested in the operation anymore.

You can also catch multiple exceptions to handle different types of potential failures, such as InterruptedException, which means that something interrupted the background thread, or ExecutionException, which means that an exception was thrown while trying to execute the background job.

You will need to have a working Rails installation on your system for that, you can find great tutorials on the Web for that, such as this one https://www.digitalocean.com/community/articles/how-to-install-ruby-on-rails-on-ubuntu-12-04-lts-precise-pangolin-with-rvm.

Now, we need to edit the application configuration to actually use memcached as the caching backend for the rails caching API.

Normally, you don't enable caching while development and you only turn it on in production, so we will be editing the config/environments/production.rb file (you may also want to add this to config/environments/development.rb if you want to see caching in development mode). Let's add:

 config.cache_store = :dalli_store

You will be able to use all of Rails automatic and manual caching features of Rails and the default cache store will be now Dalli (memcached client).

Rails has different features for caching, such as the following:

To use Dalli for Rails session storage that times out after 20 minutes, in config/initializers/session_store.rb:

config.cache_store = :dalli_store, 'cache-1.example.com', 'cache-2.example.com',
  { :namespace => NAME_OF_RAILS_APP, :expires_in => 1.day, :compress => true }

Of course, you will need to write the correct names of the memcached hosts and ports for your caching cluster, instead of cache-1.example.com and cache-2.example.com.

You will need to have a simple Django application to play with, if you don't have one you can create an empty project with an empty application by using the following:

django-admin.py startproject djangocache
cd djangocache/
python manage.py startapp cachista
python manage.py runserver

This will create a project called djangocache and a simple app (module) inside your project that we called cachista.

If you don't have python-memcached installed already, you can simply use pip for that:

pip install python-memcached

Now, let's tell Django to cache one of our views, it will automatically cache the view response for us. You will need to import that cache_page decorator first from django.views.decorators.cache import cache_page.

@cache_page(60 * 15, key_prefix="site1")
def my_view(request):
    """ my view code goes here """

Piece of cake! We told Django to cache this view for 15 minutes and the key prefix in the cache store will be "site1".

Now, do you remember the "default" we wrote in our CACHES setting? That was to setup multiple caching backends for Django! Yes, you can cache certain pages on certain caching backends. You can specify the caching backend in your cache_page view.

@cache_page(60 * 15, cache="memory_cache")

The "memory_cache" value must correspond to a key in your CACHES setting where you specify the caching backend settings. Fantastic!

As in Rails, you can specify fragments of your template to be cached.

{% load cache %}
{% cache 500 sidebar %}
    .. sidebar ..
{% endcache %}

Now, let's use the caching API to do manual caching of a value in our action/controller code from the following:

django.core.cache import get_cache
cache = get_cache('default')
cache.set('key', 'Hello Memcached!', 15)
print cache.get('key')

This looks very similar to the direct memcached API but it's not! It's an abstract API that can actually use multiple backends for you; memcached is one of them as configured in the CACHES setting.

We started by defining the CACHES variable in the settings.py file and there we can define multiple cache regions with different backends. Django supports multiple cache backends, file-based, memory-based, and database-based. In our case, we used python-memcached backend and we specified that for the 'default' cache region.

Of course, it's very popular to use memcached as a cluster and to specify the list of servers to your configuration.

You can also specify some interesting options along with the LOCATION and BACKEND keys, some examples of the same are as follows:

Then we played with cache_page decorator which automatically caches a view for us, you can specify the prefix or the cache region you are planning to use for this particular page.

Then we have seen the template caching, you can cache pieces/fragments of your template code with the "cache" tag, you can specify in the identifier for this cached fragment and expiration.

In our case we used the sidebar identifier as stated in the following line:

{% cache 500 sidebar %}

The expiration is set to 500 seconds, but interestingly you can specify more keywords for your identifier for the same fragment.

{% cache 500 sidebar welcome %}

Also, you can use the low-level caching API if you want more granular control over your caching and that was described in the last code snippet.

Congratulations, Play 2 is now connected and uses memcached as the caching backend.

First, we needed to edit the build script (build.sbt) to add the play2-memcached as a dependency, we did that by appending in the libraryDependencies setting key the value to "com.github.mumoshu" %% "play2-memcached" % "0.3.0.2".

Then, we added a resolver to tell sbt where to get this plugin from. Next, we created/edited the conf/play.plugins file to add the plugin to play and we configured conf/application.conf to point to our memcached server.

In the controller code, we used the play.api.cache.Cache object to get and set values from the cache.

The last thing is that you can use the Cached object to cache the entire action response in a named cache key "homePage".

If you are planning to use Play2 with a memcached cluster, you will need to configure the list of your servers in conf/application.conf.

The configuration is really straightforward. Just replace memcached.host="127.0.0.1:11211"with the list of the servers as follows:

memcached.1.host="cache-1.example.com:11211"
memcached.2.host="cache-1.example.com:11211"

As mentioned several times before, it's important to keep this list in-sync for all your Play servers.