A robust, performance-focused and full-featured Redis client for Node.js.
Supports Redis >= 2.6.12. Completely compatible with Redis 7.x.
ioredis is a stable project and maintenance is done on a best-effort basis for relevant issues (contributions to ioredis will still be evaluated, reviewed, and merged when they benefit the project). For new projects, node-redis is the recommended client library. node-redis is the open-source (MIT license) Redis JavaScript client library redesigned from the ground up and actively maintained. node-redis supports new (hash-field expiration) and future commands and the capabilities available in Redis Stack and Redis 8 (search, JSON, time-series, probabilistic data structures).
Features
ioredis is a robust, full-featured Redis client that is used in the world's biggest online commerce company Alibaba and many other awesome companies.
- Full-featured. It supports Cluster, Sentinel, Streams, Pipelining, and of course Lua scripting, Redis Functions, Pub/Sub (with the support of binary messages).
- High performance 🚀.
- Delightful API 😄. It works with Node callbacks and Native promises.
- Transformation of command arguments and replies.
- Transparent key prefixing.
- Abstraction for Lua scripting, allowing you to define custom commands.
- Supports binary data.
- Supports TLS 🔒.
- Supports offline queue and ready checking.
- Supports ES6 types, such as
MapandSet. - Supports GEO commands 📍.
- Supports Redis ACL.
- Sophisticated error handling strategy.
- Supports NAT mapping.
- Supports autopipelining.
100% written in TypeScript and official declarations are provided:
Versions
| Version | Branch | Node.js Version | Redis Version |
|---|---|---|---|
| 6.x.x (latest) | main | >= 20 | 6.2 ~ latest |
| 5.x.x | v5 | >= 12 | 2.6.12 ~ latest |
| 4.x.x | v4 | >= 8 | 2.6.12 ~ 7 |
Refer to CHANGELOG.md for features and bug fixes introduced in v5.
Links
Quick Start
Install
npm install ioredis
In a TypeScript project, you may want to add TypeScript declarations for Node.js:
npm install --save-dev @types/node
Basic Usage
// Import ioredis.
// You can also use `import { Redis } from "ioredis"`
// if your project is a TypeScript project,
// Note that `import Redis from "ioredis"` is still supported,
// but will be deprecated in the next major version.
const Redis = require("ioredis");
// Create a Redis instance.
// By default, it will connect to localhost:6379.
// We are going to cover how to specify connection options soon.
const redis = new Redis();
redis.set("mykey", "value"); // Returns a promise which resolves to "OK" when the command succeeds.
// ioredis supports the node.js callback style
redis.get("mykey", (err, result) => {
if (err) {
console.error(err);
} else {
console.log(result); // Prints "value"
}
});
// Or ioredis returns a promise if the last argument isn't a function
redis.get("mykey").then((result) => {
console.log(result); // Prints "value"
});
redis.zadd("sortedSet", 1, "one", 2, "dos", 4, "quatro", 3, "three");
redis.zrange("sortedSet", 0, 2, "WITHSCORES").then((elements) => {
// ["one", "1", "dos", "2", "three", "3"] as if the command was `redis> ZRANGE sortedSet 0 2 WITHSCORES`
console.log(elements);
});
// All arguments are passed directly to the redis server,
// so technically ioredis supports all Redis commands.
// The format is: redis[SOME_REDIS_COMMAND_IN_LOWERCASE](ARGUMENTS_ARE_JOINED_INTO_COMMAND_STRING)
// so the following statement is equivalent to the CLI: `redis> SET mykey hello EX 10`
redis.set("mykey", "hello", "EX", 10);
See the examples/ folder for more examples. For example:
- TTL
- Strings
- Hashes
- Lists
- Sets
- Sorted Sets
- Streams
- Redis Modules e.g. RedisJSON
All Redis commands are supported. See the documentation for details.
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 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("/tmp/redis.sock");
new Redis({
port: 6379, // Redis port
host: "127.0.0.1", // Redis host
username: "default", // needs Redis >= 6
password: "my-top-secret",
db: 0, // Defaults to 0
});
You can also pass a connection string as the first constructor argument.
Use a redis:// URL or rediss:// URL when using TLS encryption:
// Connect to 127.0.0.1:6380, db 4, using password "authpassword":
new Redis("redis://:[email protected]:6380/4");
// Username can also be passed via URI.
new Redis("redis://username:[email protected]:6380/4");
See API Documentation for all available options.
Pub/Sub
Redis provides several commands for developers to implement the Publish–subscribe pattern. There are two roles in this pattern: publisher and subscriber. Publishers are not programmed to send their messages to specific subscribers. Rather, published messages are characterized into channels, without knowledge of what (if any) subscribers there may be.
By leveraging Node.js's built-in events module, ioredis makes pub/sub very straightforward to use. Below is a simple example that consists of two files, one is publisher.js that publishes messages to a channel, the other is subscriber.js that listens for messages on specific channels.
// publisher.js
const Redis = require("ioredis");
const redis = new Redis();
setInterval(() => {
const message = { foo: Math.random() };
// Publish to my-channel-1 or my-channel-2 randomly.
const channel = `my-channel-${1 + Math.round(Math.random())}`;
// Message can be either a string or a buffer
redis.publish(channel, JSON.stringify(message));
console.log("Published %s to %s", message, channel);
}, 1000);
// subscriber.js
const Redis = require("ioredis");
const redis = new Redis();
redis.subscribe("my-channel-1", "my-channel-2", (err, coun