What is ioredis?
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.
What are ioredis's main functionalities?
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);
});
Other packages similar to ioredis
redis-commands
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.
ioredis
[Work In Progress] A delightful, performance-focused Redis client for Node and io.js
Support Redis >= 2.6.12 and (Node.js >= 0.11.6 or io.js).
Feature
ioredis is a robust, full-featured Redis client
used in the biggest online commerce company Alibaba.
- Full-featured. It supports Cluster, Sentinel, Pipelining and of course Lua scripting & Pub/Sub
- High performance.
- Delightful API supports both Node-style callback and Promise.
- Supports Redis commands transforming.
- Abstraction for Transaction, Lua scripting and
SCAN
, SSCAN
, ZSCAN
, HSCAN
. - Supports binary data.
- Support for both TCP/IP and UNIX domain sockets.
- Flexible system for defining custom command and registering command plugins.
- Supports offine queue and ready checking.
- Supports ES6 types such as
Map
and Set
.
Instal
$ npm install ioredis
Basic Usage
var Redis = require('ioredis');
var redis = new Redis();
redis.set('foo', 'bar');
redis.get('foo', function (err, result) {
console.log(result);
});
redis.get('foo').then(function (result) {
console.log(result);
});
redis.sadd('set', 1, 3, 5, 7);
redis.sadd('set', [1, 3, 5, 7]);
Connect to Redis
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 by:
new Redis()
new Redis(6380)
new Redis(6379, '192.168.1.1')
new Redis('redis://127.0.0.1:6380')
new Redis('/tmp/redis.sock')
new Redis({
port: 6379
host: '127.0.0.1'
family: 4
})
Pub/Sub
Here is a simple example of the API for publish / subscribe.
This program opens two client connections, subscribes to a channel on one of them,
and publishes to that channel on the other:
var Redis = require('ioredis');
var redis = new Redis();
var pub = new Redis();
redis.subscribe('news', 'music', function (err, count) {
pub.publish('news', 'Hello world!');
pub.publish('music', 'Hello again!');
});
redis.on('message', function (channel, message) {
console.log('Receive message %s from channel %s', message, channel);
});
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.
Handle Binary Data
Arguments can be buffers:
redis.set('foo', new Buffer('bar'));
And every command has a buffer method(by adding a suffix of "Buffer" to the command name)
to reply a buffer instead of a utf8 string:
redis.getBuffer('foo', function (err, result) {
});
Motivation
Firstly we used the Redis client node_redis,
however over a period of time we found out it's not robust enough for us to use
in the production environment. The library has some not trivial bugs and many unresolved
issues in 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) {
console.log('received ', msg);
});
I submited some pull requests but sadly none of them has been merged, so here ioredis is.