Using Memcached Cloud with Multiple Languages

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

Feel free to contribute to this document at our documents repository: https://github.com/RedisLabs/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 Labs’ products and services facilitate the deployment and management of Memcached buckets on and off the cloud.

Top

Create a Bucket Using the Redise Pack

Redise Pack (RP) 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 Redise Pack documentation or click one of the links below:

Top

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:

  • or 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 Labs 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

Top

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 Labs 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 Labs’ own command line tool – bmemcached-cli – to quickly connect and manage any Memcached bucket (tip: you can also use telnet instead)

Top

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.

Top

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.

Top

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.

Top

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

Top

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

Top

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")

Top

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.

Top

Installing MemJS

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

$ npm install memjs

Top

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

Top

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

Top

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.

Top

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

Top

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

Top

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

Top

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.

Top

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.

Top

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

Top

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

Top

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).

Top

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:

  1. 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.

Top

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.redislabs.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

Top

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

Top

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#.

Top

Installing EnyimMemcached

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

PM> Install-Package EnyimMemcached

Top

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

Top

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

Top

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:

  1. Make sure that your Drupal server is installed with the libmemcached and the PECL memcached extension.
  2. 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.
  3. 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

Top

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:

  1. Make sure that your Drupal server is installed with libmemcached and the PECL memcached extension.
  2. Take your Drupal site offline
  3. Download and install the Drupal’s “Memcache API and Integration” module
  4. To make Memcached the default cache class, edit your site’s settings.php file, as shown in the example below
  5. 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

Top

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'
);

Top

Using Memcached with Joomla

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

  1. Make sure that your Joomla server is installed with the libmemcached and the PECL memcached extension.
  2. Log into Joomla’s administration console and navigate to the Site -> Global Configuration -> System tab
  3. 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
  4. Click Save

Top

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:

  1. Make sure that your Magento server is installed with libmemcached and the PECL memcached extension.
  2. 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.

  3. 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