Memcached

memcached is a fully featured Memcached client for Node.js. memcached is built with scaling, high availability and exceptional performance in mind. We use consistent hashing to store the data across different nodes. Consistent hashing is a scheme that provides a hash table functionality in a way that adding or removing a server node does not significantly change the mapping of the keys to server nodes. The algorithm that is used for consistent hashing is the same as libketama.

There are different ways to handle errors for example, when a server becomes unavailable you can configure the client to see all requests to that server as cache misses until it goes up again. It's also possible to automatically remove the affected server from the consistent hashing algorithm or provide memcached with a failover server that can take the place of the unresponsive server.

When these issues occur the memcached client will emit different events where you can subscribe to containing detailed information about the issues.

The client is configurable on different levels. There's a global configuration that you update so all your Memcached clusters will use the same failure configuration for example, but it's also possible to overwrite these changes per memcached instance.

protocol

As in other databases and message queues, this module uses the ASCII protocol to communicate with the server, which means that you can see what is send over the wire. For debugging this is easier for both the users and the developers however this also means that SASL auth is not supported because it demands the binary protocol.

Installation

npm install memcached

Setting up the client

The constructor of the memcached client take 2 different arguments server locations and options. Syntax:

var Memcached = require('memcached');
var memcached = new Memcached(Server locations, options);

Server locations

The server locations is designed to work with different formats. These formats are all internally parsed to the correct format so our consistent hashing scheme can work with it. You can either use:

1. String, this only works if you are running a single server instance of Memcached. It's as easy a suppling a string in the following format: hostname:port. For example 192.168.0.102:11211 This would tell the client to connect to host 192.168.0.102 on port number 11211.

2. Array, if you are running a single server you would only have to supply one item in the array. The array format is particularly useful if you are running a cluster of Memcached servers. This will allow you to spread the keys and load between the different servers. Giving you higher availability when one of your Memcached servers goes down.

3. Object, when running a cluster of Memcached servers, some servers may allocate different amounts of memory, e.g. 128, 512, and 128mb. While by default all servers are equally important and dispatch consistently the keys between the servers (33/33/33%), it is possible to send more keys in servers having more memory. To do so, define an object whose key represents the server location and whose value represents a server weight, the default weight for a server being 1; so, for instance { '192.168.0.102:11211': 1, '192.168.0.103:11211': 2, '192.168.0.104:11211': 1 } distributes 50% of the keys on server 103, but only 25% on 104 and 25% on 102.

To implement one of the above formats, your constructor would look like this:

var memcached = new Memcached({ '192.168.0.102:11211': 1, '192.168.0.103:11211': 2, '192.168.0.104:11211': 1 });
var memcached = new Memcached([ '192.168.0.102:11211', '192.168.0.103:11211', '192.168.0.104:11211' ]);
var memcached = new Memcached('192.168.0.102:11211');

Options

Memcached accepts two option schemes. The first one inherits of all Memcached server instances while the second one is client specific and overwrites the globals. To define these options, Memcached server uses the same properties:

• maxKeySize: 250, the maximum key size allowed.
• maxExpiration: 2592000, the maximum expiration time of keys (in seconds).
• maxValue: 1048576, the maximum size of a value.
• poolSize: 10, the maximum size of the connection pool.
• algorithm: md5, the hashing algorithm used to generate the hashRing values.
• reconnect: 18000000, the time between reconnection attempts (in milliseconds).
• timeout: 5000, the time after which Memcached sends a connection timeout (in milliseconds).
• retries: 5, the number of socket allocation retries per request.
• failures: 5, the number of failed-attempts to a server before it is regarded as 'dead'.
• retry: 30000, the time between a server failure and an attempt to set it up back in service.
• remove: false, if true, authorizes the automatic removal of dead servers from the pool.
• failOverServers: undefined, an array of server_locations to replace servers that fail and that are removed from the consistent hashing scheme.
• keyCompression: true, whether to use md5 as hashing scheme when keys exceed maxKeySize.
• idle: 5000, the idle timeout for the connections.
• encoding: utf8, encoding of data when socket as a readable stream

Example usage:

var memcached = new Memcached('localhost:11211', {retries:10,retry:10000,remove:true,failOverServers:['192.168.0.103:11211']});

If you wish to configure the options globally:

var Memcached = require('memcached');
// all global configurations should be applied to the .config object of the Client.
Memcached.config.poolSize = 25;

API

Public methods

memcached.touch Touches the given key.

• key: String The key
• lifetime: Number After how long should the key expire measured in seconds
• callback: Function

memcached.touch('key', 10, function (err) { /* stuff */ });

memcached.get Get the value for the given key.

• key: String, the key
• callback: Function, the callback.

memcached.get('foo', function (err, data) {
  console.log(data);
});

memcached.gets Get the value and the CAS id.

• key: String, the key
• callback: Function, the callback.

memcached.gets('foo', function (err, data) {
  console.log(data.foo);
  console.log(data.cas);

  // Please note that the data is stored under the name of the given key.
});

memcached.getMulti Retrieves a bunch of values from multiple keys.

• keys: Array, all the keys that needs to be fetched
• callback: Function, the callback.

memcached.getMulti(['foo', 'bar'], function (err, data) {
  console.log(data.foo);
  console.log(data.bar);
});

memcached.set Stores a new value in Memcached.

• key: String the name of the key
• value: Mixed Either a buffer, JSON, number or string that you want to store.
• lifetime: Number, how long the data needs to be stored measured in seconds
• callback: Function the callback

memcached.set('foo', 'bar', 10, function (err) { /* stuff */ });

memcached.replace Replaces the value in memcached.

• key: String the name of the key
• value: Mixed Either a buffer, JSON, number or string that you want to store.
• lifetime: Number, how long the data needs to be replaced measured in seconds
• callback: Function the callback

memcached.replace('foo', 'bar', 10, function (err) { /* stuff */ });

memcached.add Add the value, only if it's not in memcached already.

• key: String the name of the key
• value: Mixed Either a buffer, JSON, number or string that you want to store.
• lifetime: Number, how long the data needs to be replaced measured in seconds
• callback: Function the callback

memcached.add('foo', 'bar', 10, function (err) { /* stuff */ });

memcached.cas Add the value, only if it matches the given CAS value.

• key: String the name of the key
• value: Mixed Either a buffer, JSON, number or string that you want to store.
• lifetime: Number, how long the data needs to be replaced measured in seconds
• cas: String the CAS value
• callback: Function the callback

memcached.gets('foo', function (err, data) {
  memcached.cas('foo', 'bar', data.cas, 10, function (err) { /* stuff */ });
});

memcached.append Add the given value string to the value of an existing item.

• key: String the name of the key
• value: Mixed Either a buffer, JSON, number or string that you want to store.
• callback: Function the callback

memcached.append('foo', 'bar', function (err) { /* stuff */ });

memcached.prepend Add the given value string to the value of an existing item.

• key: String the name of the key
• value: Mixed Either a buffer, JSON, number or string that you want to store.
• callback: Function the callback

memcached.prepend('foo', 'bar', function (err) { /* stuff */ });

memcached.incr Increment a given key.

• key: String the name of the key
• amount: Number The increment
• callback: Function the callback

memcached.incr('foo', 10, function (err) { /* stuff */ });

memcached.decr Decrement a given key.

• key: String the name of the key
• amount: Number The increment
• callback: Function the callback

memcached.decr('foo', 10, function (err) { /* stuff */ });

memcached.del Remove the key from memcached.

• key: String the name of the key
• callback: Function the callback

memcached.del('foo', function (err) { /* stuff */ });

memcached.version Retrieves the version number of your server.

• callback

memcached.flush Fl