We are now, simply, Redis

Using Memcached Cloud with Multiple Languages

This document provides the instructions needed to create and connect to a Memcached Cloud bucket from Redis.

Feel free to contribute to this document at our documents repository: https://github.com/Redis/rldocs

Creating a Memcached Bucket

Memcached is a free & open source, high-performance, distributed memory object caching system, generic in nature, but intended for use in speeding up dynamic web applications by alleviating database load. Redis’ products and services facilitate the deployment and management of Memcached buckets on and off the cloud.

Create a Bucket Using the Redis Enterprise Software

Redis Enterprise Software enables you to install an enterprise-grade cluster that acts as a container for managing and running multiple Memcached buckets in a highly available and scalable manner, with predictable and stable top performance.

To create your bucket and obtain its connection information refer to the Redis Enterprise documentation or click one of the links below:

Create a Bucket Using Memcached Cloud

Memcached Cloud is a fully-managed, reliable service for hosting and running your Memcached.

To create a bucket with Memcached Cloud follow these steps:

Login or Sign up to Memcached Cloud
Using the web console, select an existing Memcached Cloud subscription or add a new plan in the cloud and data region of your choosing
Add a new Memcached bucket to your subscription and configure it
As your bucket becomes active, the console will display its connection information

Important note: Memcached buckets from Redis are powered by Redis and as such offer several advanced capabilities that are not included with the standard memcached server. While the use of these capabilities is strictly optional, consider the following advantages:

Depending on your chosen plan, your bucket can be configured with data persistency for durability purposes so you don’t need to synchronize your cache’s contents to another SQL or NoSQL database
You can import and export data to and from your bucket
You can use KEYS and MONITOR, just like in Redis (for more information read this blog post

Connecting to Memcached

To establish a connection to a Memcached bucket, you’ll need the following information:

The hostname or IP address of the Memcached server
The port number that the Memcached server is listening at
The bucket’s username and password (when configured with SASL authentication which is strongly recommended)

The combination of the hostname:port is commonly referred to as the “endpoint.” This information is readily obtainable from your web console. Memcached buckets from Redis are accessible via a single managed endpoint to ensure high availability

You can connect to a Memcached bucket using a wide variety of tools and libraries depending on your needs. Here’s a short list:

Use one of the many clients for Memcached (see below for client-specific information and examples)
Code your own Memcached client, based on the Memcached protocols
Make friends with Redis’ own command line tool – bmemcached-cli – to quickly connect and manage any Memcached bucket (tip: you can also use telnet instead)

Basic Connection Troubleshooting

Connecting to a remote server can be challenging. Here’s a quick checklist of common pitfalls:

Verify that the connection information was copy-pasted correctly – more than 90% of connectivity issues are due to a single missing character
If you’re using Memcached in the cloud or not inside of a LAN, consider adjusting your client’s timeout settings
If you’re using SASL authentication, note that the default Memcached text protocol can’t be used with SASL authentication – you’ll only be able to use tools and clients that use Memcached’s binary protocol
Try disabling any security measures that your database may have been set up with (e.g. Source IP/Subnet lists, Security Groups, SASL, etc.)
Try using a command line tool to connect to the database from your server – it is possible that your host and/port are blocked by the network.
If you’ve managed to open a connection, try sending the STATS command and take note of its reply or error message

If you encounter any difficulties or have questions please feel free to contact our help desk.

Using Memcached with Ruby

In order to use Memcached with Ruby you will need a Ruby Memcached client. In the following sections, we will demonstrate the use of dalli, a high-performance memcached client for Ruby.

Installing Dalli

Dalli’s installation instructions are given in the “Installation and usage” section of its README file. After installing memcached, use gem to install Dalli:

foo@bar:~$ gem install dalli

Or, include dalli in your Gemfile by adding the following line:

gem 'dalli'

Followed by executing bundle install.

Opening a Connection to Memcached Using Dalli

The following code creates a connection to Memcached using Dalli:

require 'dalli'

options = { :username => 'username', :password => 'password' }
mc = Dalli::Client.new('hostname:port', options)

To adapt this example to your code, make sure that you replace the following values with those of your bucket:

In line 3, :username should be set with your bucket’s username
In line 3, :password should be set with your bucket’s password
In line 4, the first argument should be your bucket’s endpoint

Reading and Writing Data with Dalli

Once connected to Memcached, you can start reading and writing data. The following code snippet writes the value bar to the Memcached key foo, reads it back, and prints it:

# open a connection to Memcached
...

mc.set('foo', 'bar')
value = mc.get('foo')
puts value

The output of the above code should be:

$ ruby example_dalli.rb
bar

Using Dalli with Rails 3 and 4

To use Memcached as a cache store for Rails, modify the file config/environments/production.rb with the following:

config.cache_store = :dalli_store,
                ('hostname:port',
                {:username => 'username',
                 :password => 'password'
                }

Once configured, you can use the following snippet to use the cache in your Rails app:

Rails.cache.write("foo", "bar")
value = Rails.cache.read("foo")

Using Memcached with Node.js

In order to use Memcached with Node.js you will need a Node.js Memcached client. In the following sections, we will demonstrate the use of MemJS, a Memcache client for Node.js using the binary protocol and SASL authentication.

Installing MemJS

MemJS’ installation instructions are given in the “Installation” section of its README file. To install, use npm as follows:

$ npm install memjs

Opening a Connection to Memcached Using MemJS

The following code creates a connection to Memcached using MemJS:

var memjs = require('memjs');

var mc = memjs.Client.create('hostname:port', {
  username: 'username',
  password: 'password'
});

To adapt this example to your code, make sure that you replace the following values with those of your bucket:

In line 3, the first argument should be your bucket’s endpoint
In line 4, username should be set with your bucket’s username
In line 5, password should be set with your bucket’s password

Reading and Writing Data with MemJS

Once connected to Memcached, you can start reading and writing data. The following code snippet writes the value bar to the Memcached key foo, reads it back, and prints it:

// open a connection to Memcached
...

mc.set('foo', 'bar');
mc.get('foo', function (err, value, key) {
    if (value != null) {
        console.log(value.toString());
    }
});

The output of the above code should be:

$ node example_memjs.js
bar

Using Memcached with Python

In order to use Memcached with Python you will need a Python Memcached client. In the following sections, we will demonstrate the use of bmemcached, a pure Python module (thread-safe) to access Memcached via its binary protocol with SASL auth support.

Installing bmemcached

bememcached’s installation instructions are given in the “Installing” section of its README file. Use pip to install bmemcached:

$ sudo pip install python-binary-memcached

Opening a Connection to Memcached Using bmemcached

The following code creates a connection to Memcached using MemJS:

import bmemcached

mc = bmemcached.Client('hostname:port', 'username', 'password')

To adapt this example to your code, make sure that you replace the following values with those of your bucket:

In line 3, the first argument should be your bucket’s endpoint
In line 3, the second argument should be set with your bucket’s username
In line 3, the third argument should be set with your bucket’s password

Reading and Writing Data with bmemcached

Once connected to Memcached, you can start reading and writing data. The following code snippet writes the value bar to the Memcached key foo, reads it back, and prints it:

# open a connection to Memcached
...

mc.set('foo', 'bar')
value = mc.get('foo')
print(value)

The output of the above code should be:

$ python example_bmemcached.py
bar

Using Memcached with Java

In order to use Memcached with Java you will need a Java Memcached client. In the following sections, we will demonstrate the use of spymemcached, a simple, asynchronous, single-threaded Memcached client written in Java.

Installing spymemcached

To use spymemcached, begin by adding the following repository to Maven:

<repositories>
    <repository>
      <id>spy</id>
      <name>Spy Repository</name>
      <layout>default</layout>
      <url>http://files.couchbase.com/maven2/</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
</repositories>

Next, declare the following Maven dependency:

<dependency>
  <groupId>spy</groupId>
  <artifactId>spymemcached</artifactId>
  <version>2.11.6</version>
  <scope>provided</scope>
</dependency>

Even if you’re not using Maven, you can download the latest spymemcached .jar files directly from The Maven Central Repository.

Opening a Connection to Memcached Using spymemcached

The following code creates a connection to Memcached using spymemcached:

import java.io.IOException;
import net.spy.memcached.*;

public class spymemcachedExample {
    public static void main(String[] args) {
        AuthDescriptor ad = new AuthDescriptor("PLAIN", 
            new PlainCallbackHandler("username", "password"));

        try {
            MemcachedClient mc = new MemcachedClient(
            new ConnectionFactoryBuilder()
                .setProtocol(ConnectionFactoryBuilder.Protocol.BINARY)
                .setAuthDescriptor(ad).build(),
            AddrUtil.getAddresses(new String[] { "hostname:port" }));
        } catch (IOException e) {
            // handle exception
        }
    }
}

To adapt this example to your code, make sure that you replace the following values with those of your bucket:

In line 7, replace username with your bucket’s username
In line 7, replace password with your bucket’s password
In line 14, the argument should be your bucket’s endpoint

Reading and Writing Data with spymemcached

Once connected to Memcached, you can start reading and writing data. The following code snippet writes the value bar to the Memcached key foo, reads it back, and prints it:

// open a connection to Memcached
...

mc.set("foo", 0, "bar");
String value = mc.get("foo");
System.out.println(value);

The output of the above code should be:

$ java spymemcachedExample
bar

Using Memcached with PHP

In order to use Memcached with PHP you will need a PHP Memcached client. In the following sections, we will demonstrate the use of PECL memcached, an extension that uses the libmemcached library to provide an API for communicating with Memcached servers as well as a session handler (memcached).

Installing PECL memcached

PECL memcached’s installation instructions are given in its “Installation” page. To install it, use the following command:

pecl install memcached

Note: PECL memcached depends on having libmemcached installed as per the PECL memcached requirements page.

Once installed, you should review the /etc/php5/mods-available/memcached.ini file or your site’s php.ini file and verify the following setting in it:

SASL authentication (memcached.use_sasl) – to use a SASL-enabled Memcached Cloud bucket, enable this setting by setting it to 1

Note: if you’ve installed PECL memcached, you should consider restarting your web server to apply the changes.

Opening a Connection to Memcached Using PECL memcached

The following code creates a connection to Memcached using PECL memcached:

<?php
    $mc = new Memcached();
    $mc->setOption(Memcached::OPT_BINARY_PROTOCOL, true);
    $mc->addServer('hostname.redis.com', 11211);
    $mc->setSaslAuthData('username', 'password');
?>

To adapt this example to your code, make sure that you replace the following values with those of your bucket:

In line 4, the first argument to addServer should be your bucket’s hostname or IP address
In line 4, the second argument to addServer should be your bucket’s port
In line 5, the first argument to setSaslAuthData should be your bucket’s username
In line 5, the second argument to setSaslAuthData should be your bucket’s password

Reading and Writing Data with PECL memcached

Once connected to Memcached, you can start reading and writing data. The following code snippet writes the value bar to the Memcached key foo, reads it back, and prints it:

// open a connection to Memcached
...

$mc->set('foo', 'bar');
value = $mc->get('foo');
echo value;

The output of the above code should be:

$ php memcached.php
bar

Using Memcached with .NET C#

In order to use Memcached with .NET C# you will need a .NET C# Memcached client. In the following sections, we will demonstrate the use of EnyimMemcached, a .NET client library for Memcached written in C#.

Installing EnyimMemcached

To install EnyimMemcached, run the following command in the Package Manager Console:

PM> Install-Package EnyimMemcached

Opening a Connection to Memcached Using EnyimMemcached

The following code creates a connection to Memcached using EnyimMemcached:

using Enyim.Caching;
using Enyim.Caching.Configuration;
using Enyim.Caching.Memcached;

MemcachedClientConfiguration config = new MemcachedClientConfiguration();
config.Servers.Add(new IPEndPoint("hostname", port));
config.Protocol = MemcachedProtocol.Binary;
config.Authentication.Type = typeof(PlainTextAuthenticator);
config.Authentication.Parameters["userName"] = "username";
config.Authentication.Parameters["password"] = "password";
config.Authentication.Parameters["zone"] = "";

var mc = new MemcachedClient(config);

To adapt this example to your code, make sure that you replace the following values with those of your bucket:

In line 6, the first argument to IPEndPoint should be your bucket’s hostname or IP address
In line 6, the second argument to IPEndPoint should be your bucket’s port
In line 9, userName should be set with your bucket’s username
In line 10, password should be set with your bucket’s password

Reading and Writing Data with EnyimMemcached

Once connected to Memcached, you can start reading and writing data. The following code snippet writes the value bar to the Memcached key foo, reads it back, and prints it:

///<summary>
///open a connection to Memcached
///</summary>   
...

mc.Store(StoreMode.Set, "foo", "bar");
var value = mc.Get("foo");
Console.WriteLine(value);

The output of the above code should be:

bar

Using Memcached with WordPress

To use Memcached as a cache for your WordPress installation, follow these steps as described in the documentation of the Memcached Cloud plugin for WordPress:

Make sure that your Drupal server is installed with the libmemcached and the PECL memcached extension.
Copy the file object-cache.php from the Memcached Cloud plugin for WordPress .ZIP file to wp-content/object-cache.php of your WordPress installation.
Add the following definitions to your WordPress’ installation wp-config.php file:
```
 global $memcached_servers;
 $memcached_servers = array( array( 'hostname', port ) );

 global $memcached_username;
 $memcached_username = 'username';

 global $memcached_password;
 $memcached_password = 'password';
```
- In line 3, the first argument should be your bucket’s hostname or IP address
- In line 3, the second argument should be your bucket’s port
- In line 5, the value should be your bucket’s username
- In line 7, the value should be your bucket’s password
Top

Using Memcached with Django

To use Memcached as a cache for your Django website
edit your Django’s settings.py file as described in the “Django’s cache framework” page of Django’s documentation. Add the following CACHE settings to settings.py:

Install django-bmemcached:
```
$ pip install python-binary-memcached

$ pip install django-bmemcached
```
Next, configure your CACHES in the settings.py file:
```
import os
import urlparse
import json

CACHES = {
    'default': {
        'BACKEND': 'django_bmemcached.memcached.BMemcached',
        'LOCATION': '',
        'OPTIONS': {
                   'username': '<>',
                   'password': '<>'
            }
    }
}
```
You will need to replace the endpoint, connection username and password.

Note: make sure you have django-pylibmc installed on your Django server by running the following command:

$ sudo pip install django-pylibmc

Using Memcached with Drupal

To use Memcached as a cache for your Drupal site, follow the instructions provided in “Memcached / Installation” page of Drupal’s documentation. The required steps are:

Make sure that your Drupal server is installed with libmemcached and the PECL memcached extension.
Take your Drupal site offline
Download and install the Drupal’s “Memcache API and Integration” module
To make Memcached the default cache class, edit your site’s settings.php file, as shown in the example below
Take your Drupal site back online

Your settings.php should resemble the following snippet:

$conf['cache_backends'][] = 'sites/all/modules/memcache/memcache.inc';
// The 'cache_form' bin must be assigned no non-volatile storage.
$conf['cache_class_cache_form'] = 'DrupalDatabaseCache';
$conf['cache_default_class'] = 'MemCacheDrupal';

$conf['memcache_key_prefix'] = 'default';
$conf['memcache_servers'] = array( 'hostname:port' => 'default' ); 
$conf['memcache_sasl_auth'] = array(    'user' => 'username', 'password' => 'password' );

In line 6, the value should be your bucket’s endpoint
In line 7, the first value should be your bucket’s username
In line 7, the second value should be your bucket’s password

Using Multiple Memcached Buckets

Although a single Memcached bucket can be used for all of your site’s needs, it is possible to use multiple buckets via the bins mechanism. The following snippet demonstrates the use of two Memcached buckets – the first for all data and the second for users:

$conf['memcache_servers'] = array(
    'hostname1:port1' => 'default',
    'hostname2:port2' => 'users'
);
$conf['memcache_bins'] = array(
    'cache' => 'default',
    'users' => 'users'
);

Using Memcached with Joomla

To use Memcached as a cache for your Joomla site follow these steps:

Make sure that your Joomla server is installed with the libmemcached and the PECL memcached extension.
Log into Joomla’s administration console and navigate to the Site -> Global Configuration -> System tab
Under Cache Settings, set the following:
1. Cache: On-Progressive
2. Handler: Memcache
3. Server: the hostname of your bucket
4. Server port: the port number of your bucket
Click Save

Using Memcached with Magento

Magento can use Memcached both as a cache and as a session storage. We recommend you use a different Memcached bucket for each purpose.

To use Memcached as a cache and as a session storage for your Magento site, follow these steps:

Make sure that your Magento server is installed with libmemcached and the PECL memcached extension.
Log into Magento’s administration console and set default value of the Cookie Lifetime in the Magento Session Cookie Management to 31536000 in order to comply with following Memcached protocol specification about expiration times:

Some commands involve a client sending some kind of expiration time
(relative to an item or to an operation requested by the client) to
the server. In all such cases, the actual value sent may either be
Unix time (number of seconds since January 1, 1970, as a 32-bit
value), or a number of seconds starting from current time. In the
latter case, this number of seconds may not exceed 606024*30 (number
of seconds in 30 days); if the number sent by a client is larger than
that, the server will consider it to be real Unix time value rather
than an offset from current time.

Edit your site’s XML file, typically located at app/etc/local.xml, and add the following to the <global> block:

 <session_cache_limiter></session _cache_limiter>
 <session_save>
     <![CDATA[memcache]]>
 </session_save>
 <session_save_path>
     <![CDATA[tcp://hostname1:port1?persistent=1&weight=1&timeout=10&retry_interval=10]]>
 </session_save_path>
 <cache>
     <backend>
         memcached
     </backend>
     <slow_backend>
         database
     </slow_backend>
     <slow_backend_store_data>
         0
     </slow_backend_store_data>
     <memcached>
         <servers>
             <server>
                 <host>
                     <![CDATA[hostname2]]>
                 </host>
                 <port>
                     <![CDATA[port2]]>
                 </port>
                 <persistent>
                     <![CDATA[1]]>
                 </persistent>
                 <weight>
                     <![CDATA[1]]>
                 </weight>
                 <timeout>
                     <![CDATA[10]]>
                 </timeout>
                 <retry_interval>
                     <![CDATA[10]]>
                 </retry_interval>
                 <status>
                     <![CDATA[1]]>
                 </status>
             </server>
         </servers>
         <compression>
             <![CDATA[0]]>
         </compression>
         <cache_dir>
             <![CDATA[]]>
         </cache_dir>
         <hashed_directory_level>
             <![CDATA[]]>
         </hashed_directory_level>
         <hashed_directory_umask>
             <![CDATA[]]>
         </hashed_directory_umask>
         <file_name_prefix>
             <![CDATA[]]>
         </file_name_prefix>
     </memcached>
 </cache>

To modify these settings so that your Memcached buckets are used:

Replace hostname1 with the hostname of your sessions bucket
Replace port1 with the port of your sessions bucket
Replace hostname2 with the hostname of your cache bucket
Replace port2 with the port of your cache bucket
Displaying Memcached Howto – merged.md.

Top