ioredis is a robust, performance-focused, and full-featured Redis client for Node.js. It supports both Redis commands and the cluster mode introduced in Redis 3.0. It provides a more intuitive and flexible way to interact with a Redis server or a cluster of Redis servers, offering features like automatic reconnection, offline queueing, and support for transactions, pub/sub, and Lua scripting.
Basic Commands
Execute basic Redis commands such as SET and GET. This example demonstrates setting and getting the value of a key.
const Redis = require('ioredis');
const redis = new Redis();
redis.set('foo', 'bar');
redis.get('foo', (err, result) => {
console.log(result);
});Publish/Subscribe
Use Redis' pub/sub capabilities to publish messages to a channel and subscribe to receive messages from that channel.
const Redis = require('ioredis');
const subscriber = new Redis();
const publisher = new Redis();
subscriber.subscribe('news', () => {
publisher.publish('news', 'Hello world!');
});
subscriber.on('message', (channel, message) => {
console.log(`Received \
${message} from ${channel}`);
});Transactions
Perform transactions using the MULTI/EXEC commands to execute multiple commands atomically.
const Redis = require('ioredis');
const redis = new Redis();
redis.multi()
.set('foo', 'bar')
.get('foo')
.exec((err, results) => {
console.log(results);
});Pipeline
Use pipelining to send multiple commands to the server without waiting for the replies, improving performance.
const Redis = require('ioredis');
const redis = new Redis();
redis.pipeline()
.set('foo', 'bar')
.get('foo')
.del('foo')
.exec((err, results) => {
console.log(results);
});Lua Scripting
Extend Redis with Lua scripting. This example defines a custom command that gets the current value of a key and sets it to a new value atomically.
const Redis = require('ioredis');
const redis = new Redis();
redis.defineCommand('getAndSet', {
numberOfKeys: 1,
lua: 'return {redis.call('get', KEYS[1]), redis.call('set', KEYS[1], ARGV[1])}'
});
redis.getAndSet('foo', 'new value', (err, result) => {
console.log(result);
});redis-commands is not a full client but a comprehensive list of all Redis commands for use in JavaScript. It's useful for developers who want to ensure compatibility or extend their own Redis client implementations. Unlike ioredis, it doesn't provide a client interface or connection management.
A delightful, performance-focused Redis client for Node and io.js
Support Redis >= 2.6.12 and (Node.js >= 0.11.13 or io.js).
ioredis is a robust, full-featured Redis client used in the world's biggest online commerce company Alibaba.
Map and Set.$ npm install ioredis
var Redis = require('ioredis');
var redis = new Redis();
redis.set('foo', 'bar');
redis.get('foo', function (err, result) {
console.log(result);
});
// or using promise if the last argument isn't a function
redis.get('foo').then(function (result) {
console.log(result);
});
// Arguments to commands are flatten, so the following are same:
redis.sadd('set', 1, 3, 5, 7);
redis.sadd('set', [1, 3, 5, 7]);
When a new Redis instance is created,
a connection to Redis will be created at the same time.
You can specify which Redis to connect to by:
new Redis() // Connect to 127.0.0.1:6379
new Redis(6380) // 127.0.0.1:6380
new Redis(6379, '192.168.1.1') // 192.168.1.1:6379
new Redis('redis://:authpassword@127.0.0.1:6380/4') // 127.0.0.1:6380, db 4
new Redis('/tmp/redis.sock')
new Redis({
port: 6379, // Redis port
host: '127.0.0.1', // Redis host
family: 4, // 4(IPv4) or 6(IPv6)
password: 'auth'
db: 0
})
See API Documentation for all available options.
Here is a simple example of the API for publish / subscribe. This program opens two client connections. It subscribes to a channel with one connection, and publishes to that channel with the other:
var Redis = require('ioredis');
var redis = new Redis();
var pub = new Redis();
redis.subscribe('news', 'music', function (err, count) {
// Now both channel 'news' and 'music' are subscribed successfully.
// `count` represents the number of channels we are currently subscribed to.
pub.publish('news', 'Hello world!');
pub.publish('music', 'Hello again!');
});
redis.on('message', function (channel, message) {
// Receive message Hello world! from channel news
// Receive message Hello again! from channel music
console.log('Receive message %s from channel %s', message, channel);
});
// There's also a event called 'messageBuffer', which is same to 'message' except
// it returns buffers instead of strings.
redis.on('messageBuffer', function (channel, message) {
// Both `channel` and `message` are buffers.
});
When a client issues a SUBSCRIBE or PSUBSCRIBE, that connection is put into a "subscriber" mode. At that point, only commands that modify the subscription set are valid. When the subscription set is empty, the connection is put back into regular mode.
If you need to send regular commands to Redis while in subscriber mode, just open another connection.
Arguments can be buffers:
redis.set('foo', new Buffer('bar'));
And every command has a method that returns a Buffer (by adding a suffix of "Buffer" to the command name). To get a buffer instead of a utf8 string:
redis.getBuffer('foo', function (err, result) {
// result is a buffer.
});
If you want to send a batch of commands(e.g. > 5), you can use pipelining to queue the commands in the memory, then send them to Redis all at once. This way the performance improves by 50%~300%(See benchmark section).
redis.pipeline() creates a Pipeline instance. You can call any Redis
commands on it just like the Redis instance. The commands are queued in the memory
and flushed to Redis by calling exec method:
var pipeline = redis.pipeline();
pipeline.set('foo', 'bar');
pipeline.del('cc');
pipeline.exec(function (err, results) {
// `err` is always null, and `results` is an array of responses
// corresponding the sequence the commands where queued.
// Each response follows the format `[err, result]`.
});
// You can even chain the commands:
redis.pipeline().set('foo', 'bar').del('cc').exec(function (err, results) {
});
// `exec` also returns a Promise:
var promise = redis.pipeline().set('foo', 'bar').get('foo').exec();
promise.then(function (result) {
// result === [[null, 'OK'], [null, 'bar']]
});
Each chained command can also have a callback, which will be invoked when the command get a reply:
redis.pipeline().set('foo', 'bar').get('foo', function (err, result) {
// result === 'bar'
}).exec(function (err, result) {
// result[1][1] === 'bar'
});
Most of the time the transaction commands multi & exec are used together with pipeline.
Therefore by default when multi is called, a Pipeline instance is created automatically,
so that you can use multi just like pipeline:
redis.multi().set('foo', 'bar').get('foo').exec(function (err, results) {
// results === [[null, 'OK'], [null, 'bar']]
});
If there's a syntax error in the transaction's command chain (e.g. wrong number of arguments, wrong command name, etc), then none of the commands would be executed, and an error is returned:
redis.multi().set('foo').set('foo', 'new value').exec(function (err, results) {
// err === new Error('...Transaction discarded because of previous errors.');
});
In terms of the interface, multi differs from pipeline in that when specifying a callback
to each chained command, the queueing state is passed to the callback instead of the result of the command:
redis.multi().set('foo', 'bar', function (err, result) {
// result === 'QUEUED'
}).exec(/* ... */);
If you want to use transaction without pipeline, pass { pipeline: false } to multi,
and every command would be sent to Redis immediately without waiting for an exec invokation:
redis.multi({ pipeline: false });
redis.set('foo', 'bar');
redis.get('foo');
redis.exec(function (err, result) {
// result === [[null, 'OK'], [null, 'bar']]
});
Inline transaction is supported by pipeline, that means you can group a subset commands in the pipeline into a transaction:
redis.pipeline().get('foo').mulit().set('foo', 'bar').get('foo').exec().get('foo').exec();
Most Redis commands take one or more Strings as arguments,
and replies are sent back as a single String or an Array of Strings. However sometimes
you may want something different: For instance it would be more convenient if HGETALL
command returns a hash (e.g. {key: val1, key2: v2}) rather than an array of key values (e.g. [key1,val1,key2,val2]).
ioredis has a flexible system for transforming arguments and replies. There are two types of transformers, argument transform and reply transformer:
var Redis = require('ioredis');
// define a argument transformer that convert
// hmset('key', { k1: 'v1', k2: 'v2' })
// or
// hmset('key', new Map([['k1', 'v1'], ['k2', 'v2']]))
// into
// hmset('key', 'k1', 'v1', 'k2', 'v2')
Redis.Command.setArgumentTransformer('hmset', function (args) {
if (args.length === 2) {
if (typeof Map !== 'undefined' && args[1] instanceof Map) {
return [args[0]].concat(utils.convertMapToArray(args[1]));
}
if ( typeof args[1] === 'object' && args[1] !== null) {
return [args[0]].concat(utils.convertObjectToArray(args[1]));
}
}
return args;
});
// define a reply transformer that convert the reply
// ['k1', 'v1', 'k2', 'v2']
// into
// { k1: 'v1', 'k2': 'v2' }
Redis.Command.setReplyTransformer('hgetall', function (result) {
if (Array.isArray(result)) {
var obj = {};
for (var i = 0; i < result.length; i += 2) {
obj[result[i]] = result[i + 1];
}
return obj;
}
return result;
});
There are three built-in transformers, two argument transformers for hmset & mset and
a reply transformer for hgetall. Transformers for hmset and hgetall has been mentioned
above, and the transformer for mset is similar to the one for hmset:
redis.mset({ k1: 'v1', k2: 'v2' });
redis.get('k1', function (err, result) {
// result === 'v1';
});
redis.mset(new Map([['k3', 'v3'], ['k4', 'v4']]));
redis.get('k3', function (err, result) {
// result === 'v3';
});
ioredis supports all of the scripting commands such as EVAL, EVALSHA and SCRIPT.
However it's tedious to use in real world scenarios since developers have to take
care of script caching and to detect when to use EVAL and when to use EVALSHA.
ioredis expose a defineCommand method to make scripting much easier to use:
var redis = new Redis();
// This will define a command echo:
redis.defineCommand('echo', {
numberOfKeys: 2,
lua: 'return {KEYS[1],KEYS[2],ARGV[1],ARGV[2]}'
});
// Now `echo` can be used just like any other ordinary commands,
// and ioredis will try to use `EVALSHA` internally when possible for better performance.
redis.echo('k1', 'k2', 'a1', 'a2', function (err, result) {
// result === ['k1', 'k2', 'a1', 'a2']
});
// `echoBuffer` is also defined automatically to return buffers instead of strings:
redis.echoBuffer('k1', 'k2', 'a1', 'a2', function (err, result) {
// result[0] === new Buffer('k1');
});
// And of course it works with pipeline:
redis.pipeline().set('foo', 'bar').echo('k1', 'k2', 'a1', 'a2').exec();
If the number of keys can't be determined when defining a command, you can
omit the numberOfKeys property, and pass the number of keys as the first argument
when you call the command:
redis.defineCommand('echoDynamicKeyNumber', {
lua: 'return {KEYS[1],KEYS[2],ARGV[1],ARGV[2]}'
});
// Now you have to pass the number of keys as the first argument every time
// you invoke the `echoDynamicKeyNumber` command:
redis.echoDynamicKeyNumber(2, 'k1', 'k2', 'a1', 'a2', function (err, result) {
// result === ['k1', 'k2', 'a1', 'a2']
});
Redis supports the MONITOR command, which lets you see all commands received by the Redis server across all client connections, including from other client libraries and other computers.
The monitor method returns a monitor instance.
After you send the MONITOR command, no other commands are valid on that connection. ioredis would emit a monitor event for every new monitor message that comes across.
The callback for the monitor event takes a timestamp from the Redis server and an array of command arguments.
Here is a simple example:
redis.monitor(function (err, monitor) {
monitor.on('monitor', function (time, args) {
});
});
By default, ioredis will try to reconnect when the connection to Redis is lost
except when the connection is closed manually by redis.disconnect() or redis.quit().
It's very flexible to control how long to wait to reconnect after disconnected
using the retryStrategy option:
var redis = new Redis({
// This is the default value of `retryStrategy`
retryStrategy: function (times) {
var delay = Math.min(times * 2, 2000);
return delay;
}
});
retryStrategy is a function that will be called when the connection is lost.
The argument times represents this is the nth reconnection being made and
the return value represents how long(ms) to wait to reconnect. When the
return value isn't a number, ioredis will stop trying reconnecting and the connection
will be lost forever if user don't call redis.connect() manually.
When a command can't be processed by Redis(e.g. the connection hasn't been established or
Redis is loading data from disk), by default it's added to the offline queue and will be
executed when it can be processed. You can disable this feature by set enableOfflineQueue
option to false:
var redis = new Redis({ enableOfflineQueue: false });
ioredis supports Sentinel out of the box. It works transparently as all features that work when you connect to a single node also work when you connect to a sentinel group. Make sure to run Redis 2.8+ if you want to use this feature.
To connect using Sentinel, use:
var redis = new Redis({
sentinels: [{ host: 'localhost', port: 26379 }, { host: 'localhost', port: 26380 }],
name: 'mymaster'
});
redis.set('foo', 'bar');
The arguments passed to the constructor are different from ones you used to connect to a single node, where:
name identifies a group of Redis instances composed of a master and one or more slaves (mymaster in the example);sentinels are a list of sentinels to connect to. The list does not need to enumerate all your sentinel instances, but a few so that if one is down the client will try the next one.ioredis guarantees that the node you connected with is always a master even after a failover. When a failover happens, instead of trying to reconnect with the failed node(which will be demoted to slave when it's available again), ioredis will ask sentinels for the new master node and connect to it. All commands sent during the failover are queued and will be executed when the new connection is established so that none of the commands will be lost.
It's possible to connect to a slave instead of a master by specifying the option role with the value of slave, and ioredis will try to connect to a random slave of the specified master, with the guarantee that the connected node is always a slave. If the current node is promoted to master owing to a failover, ioredis will disconnect with it and ask sentinels for another slave node to connect to.
Support for Cluster is currently experimental and under active development. It's not recommended to use it in production. If you encounter any problems, welcome to submit an issue :-).
You can connect to a cluster like this:
var Redis = require('ioredis');
var cluster = new Redis.Cluster([{
port: 6380,
host: '127.0.0.1'
}, {
port: 6381,
host: '127.0.0.1'
}]);
cluster.set('foo', 'bar');
cluster.get('foo', function (err, res) {
// res === 'bar'
});
When using Redis.Cluster to connect to a cluster, there are some differences from using Redis:
info and pipeline, custom commands also don't work(currently).If hiredis is installed(by npm install hiredis),
ioredis will use it by default. Otherwise, a pure JavaScript parser will be used.
Typically there's not much differences between them in terms of performance.
Compares with node_redis:
> npm run bench
simple set
65,438 op/s » ioredis
36,954 op/s » node_redis
simple get
71,109 op/s » ioredis
36,825 op/s » node_redis
simple get with pipeline
11,123 op/s » ioredis
3,820 op/s » node_redis
lrange 100
58,812 op/s » ioredis
46,703 op/s » node_redis
Suites: 4
Benches: 8
Elapsed: 61,715.11 ms
You can find the code at benchmark.js.
Start a Redis server on 127.0.0.1:6379, and then:
$ npm test
FLUSH ALL will be invoked after each test, so make sure there's no valuable data in it before running tests.
You can set the DEBUG env to ioredis:* to print debug info:
$ DEBUG=ioredis:* node app.js
Originally we used the Redis client node_redis, but over a period of time we found that it's not robust enough for us to use in our production environment. The library has some non-trivial bugs and many unresolved issues on the GitHub(165 so far). For instance:
var redis = require('redis');
var client = redis.createClient();
client.set('foo', 'message');
client.set('bar', 'Hello world');
client.mget('foo', 'bar');
client.subscribe('channel');
client.on('message', function (msg) {
// Will print "Hello world", although no `publish` is invoked.
console.log('received ', msg);
});
I submitted some pull requests but sadly none of them has been merged, so here's ioredis.
The JavaScript and hiredis parsers are modified from node_redis (MIT License, Copyright (c) 2010 Matthew Ranney, http://ranney.com/).
MIT
v1.0.10 - April 25, 2015
FAQs
A robust, performance-focused and full-featured Redis client for Node.js.
The npm package ioredis receives a total of 4,452,268 weekly downloads. As such, ioredis popularity was classified as popular.
We found that ioredis demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.