Pure Documentation

Pure Memcache is a simple way to add Memcached servers to your Heroku application, using the built-in functionality to offer fault-tolerant caching by spreading the load across different server instances and availability zones.

Getting Started

Please note that this service is in pre-release, and you currently need to be invited to participate.

Firstly, choose between the Value and Performance tiers. The Value tier is the most cost-effective, whilst the Performance tier offers the fastest speed. You can view all our plans here. Then within each Tier you can choose the size of the cache.

Once you have chosen your plan, you can either add it via the Heroku control panel (under the Resources tab, enter Pure in the Add-on Services box), or via the command line. Here is the command for adding the default plan to your app:

$ heroku addons:create pure-memcache -a your-app-name-here

After a few seconds, three additional config vars will appear in your heroku environment: PURE_MEMCACHE_SERVERS, PURE_MEMCACHE_USERNAME and PURE_MEMCACHE_PASSWORD.

Using Pure Memcache from Ruby (and Rails)

You can use the Dalli gem to connect to Pure Memcache:

In your Gemfile add

gem 'dalli'

then run

$ bundle install

You can then access memcache as follows:

require 'dalli'
cache = Dalli::Client.new(ENV['PURE_MEMCACHE_SERVERS'].split(','),
  {username: ENV['PURE_MEMCACHE_USERNAME'], password: ENV['PURE_MEMCACHE_PASSWORD']})

Rails

Once the Dalli gem is installed, you can edit the config/environments/production.rb to use Pure Memcache as your default Rails cache:

config.cache_store = :mem_cache_store, ENV['PURE_MEMCACHE_SERVERS'].split(','),
  {username: ENV['PURE_MEMCACHE_USERNAME'], password: ENV['PURE_MEMCACHE_PASSWORD']}

Using Pure Memcache from Node

You can use the memjs package to access Pure Memcache from node:

$ npm install memjs

Then you can create a client like this:

const memjs = require('memjs'); // or import memjs from 'memjs' if using ES modules

const client = memjs.Client.create(process.env.PURE_MEMCACHE_SERVERS, {
  username: process.env.PURE_MEMCACHE_USERNAME,
  password: process.env.PURE_MEMCACHE_PASSWORD,
  failover: true
});

Using Pure Memcache from Python

You can use the bmemcached module to access Pure Memcache from Python. Firstly, add install the module:

$ pip install python-binary-memcached

Then the you can create a client like this:

import os
import bmemcached

client = bmemcached.Client(os.environ.get('PURE_MEMCACHE_SERVERS').split(','), os.environ.get('PURE_MEMCACHE_USERNAME'), os.environ.get('PURE_MEMCACHE_PASSWORD'))

Using Pure Memcache from Java

You can use the XMemcached client to access Pure Memcache from Java.

Firstly, add the XMemcached library to your Project Object Model file, pom.xml:

<dependency>
  <groupId>com.googlecode.xmemcached</groupId>
  <artifactId>xmemcached</artifactId>
  <version>2.4.8</version>
</dependency>

Then you can create a XMemcached client like this:

List<InetSocketAddress> servers = AddrUtil.getAddresses(System.getenv("PURE_MEMCACHE_SERVERS").replace(",", " "));
AuthInfo authInfo = AuthInfo.plain(System.getenv("PURE_MEMCACHE_USERNAME"), System.getenv("PURE_MEMCACHE_PASSWORD"));

MemcachedClientBuilder builder = new XMemcachedClientBuilder(servers);
for (InetSocketAddress server : servers) builder.addAuthInfo(server, authInfo);

// Must use binary protocol
builder.setCommandFactory(new BinaryCommandFactory());
MemcachedClient client=builder.build();

Using Pure Memcache from PHP

You can use the PHP Memcached Client to connect from PHP.

Firstly, add the following to your composer.json:

"require": {
    "ext-memcached": "*"
}

Then run

$ composer update

You create a Memcached client as follows:

$client = new Memcached();
$client->setOption(Memcached::OPT_BINARY_PROTOCOL, true);
// use consistent hashing to allow adding or removing of servers without losing cached values
$client->setOption(Memcached::OPT_LIBKETAMA_COMPATIBLE, true);
$client->setOption(Memcached::OPT_DISTRIBUTION, Memcached::DISTRIBUTION_CONSISTENT);
// failover
$client->setOption(Memcached::OPT_REMOVE_FAILED_SERVERS, true);
// this should only be called once to avoid adding the servers multiple times...
$client->addServers(array_map(fn($server) => explode(':', $server, 2), explode(',', $_ENV['PURE_MEMCACHE_SERVERS'])));
$client->setSaslAuthData($_ENV['PURE_MEMCACHE_USERNAME'], $_ENV['PURE_MEMCACHE_PASSWORD']);

Upgrading and downgrading

You can only upgrade and downgrade within a Tier, as these are implemented on completely different servers.

Within a Tier, if you want to minimise the impact of upgrades and downgrades on your production environment, then please change to next nearest plan in size, rather than jumping two or more sizes in one go. By stepping up or down gradually over some hours, you can ensure that the impact on your live service is minimal.