Pure Memcache is an add-on for adding Memcached servers to your Heroku application. The built-in functionality offers fault-tolerant caching by spreading the load across different server instances and availability zones.

Provisioning the Add-on

Pure Memcache offers several plans with different cache sizes. The Value tier is the most cost-effective, while the Performance tier offers faster speed.

Attach Pure Memcache to a Heroku application via the CLI:

$ heroku addons:create pure-memcache:value1
Creating pure-memcache on example-app... free
Your add-on has been provisioned successfully

After provisioning Pure Memcache, the following config vars are available in the attached app’s configuration:

• PURE_MEMCACHE_SERVERS
• PURE_MEMCACHE_USERNAME
• PURE_MEMCACHE_PASSWORD

You can see the config var via the heroku config:get command:

$ heroku config:get PURE_MEMCACHE_SERVERS

After installing Pure Memcache, the application is fully configured to integrate with the add-on.

Using Pure Memcache from Ruby and Rails

Use the Dalli gem to connect to Pure Memcache:

In your Gemfile add:

gem 'dalli'

Then run:

$ bundle install

You can then access Memcache with:

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

Rails

After installing the Dalli gem, you can edit the config/environments/production.rb file 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.js

Use the memjs package to access Pure Memcache from Node.js:

$ npm install memjs

Then you can create a client:

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

Use the bmemcached module to access Pure Memcache from Python.

First, install the module:

$ pip install python-binary-memcached

Then the you can create a client:

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

Use the XMemcached client to access Pure Memcache from Java.

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

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

Then you can create a XMemcached client:

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

Use the PHP Memcached Client to connect from PHP.

First, add the following to your composer.json file:

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

Then run:

$ composer update

Then you can create a Memcached client:

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

Migrating Between Plans

You can only upgrade and downgrade plans within the same tier as the Value and Performance tiers are implemented on completely different servers. To minimize the impact of upgrades and downgrades within a tier on your production environment, we recommend changing to the next nearest plan in size. By changing plans gradually over time, you can ensure the impact on your live service is minimal.

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade pure-memcache:value2
-----> Upgrading pure-memcache:value 2 to example-app.. done, v18 ($49/mo)
       Your plan has been updated to: pure-memcache:value 2

Removing the Add-on

Remove Pure Memcache via the CLI:

$ heroku addons:destroy pure-memcache
-----> Removing pure-memcache from example-app... done

Support

Submit all Pure Memcache support and runtime issues via one of the Heroku Support channels. Any non-support-related issues or product feedback is welcome at feedback@pureserv.link.