ioredis — Robust Full-Featured Redis Client for Node.js

Introduction

ioredis is a robust Redis client for Node.js maintained by the Redis organization. It offers first-class support for Redis Cluster, Sentinel high-availability, Streams, pipelining, and Lua scripting — making it the preferred client for production applications that need reliability and performance beyond what simpler clients provide.

What ioredis Does

• Connects to standalone Redis, Redis Cluster, and Redis Sentinel topologies
• Pipelines multiple commands into a single network round-trip for throughput
• Executes server-side Lua scripts with automatic EVALSHA caching
• Subscribes to Pub/Sub channels and handles pattern-based subscriptions
• Reads and writes to Redis Streams with consumer group support

Architecture Overview

ioredis uses a single TCP connection per client instance with an internal command queue. Commands are serialized using the RESP protocol and flushed in batches when pipelining. The Cluster driver maintains a slot map and routes commands to the correct shard, handling MOVED and ASK redirections transparently. Sentinel support monitors master failovers and reconnects automatically.

Self-Hosting & Configuration

• Install via npm — pure JavaScript with optional native parser for extra speed
• Pass connection options as an object or a Redis URL string: new Redis('redis://user:pass@host:6379/0')
• Enable TLS with tls: {} for encrypted connections to managed Redis services
• Configure automatic reconnect with retryStrategy for resilient long-lived connections
• Use lazyConnect: true to defer connection until the first command is issued

Key Features

• Transparent Redis Cluster support with client-side slot routing and pipeline splitting
• Sentinel-aware failover: auto-discovers new masters and reconnects subscribers
• Built-in Lua script management with SHA caching to avoid resending script bodies
• Offline queue buffers commands during reconnection, replaying them once connected
• Over 15,000 GitHub stars and 12 million weekly npm downloads

Comparison with Similar Tools

• node-redis — the official Redis client; ioredis has richer Cluster and Sentinel support out of the box
• redis-py (Python) — Python equivalent; ioredis is the Node.js counterpart with async-native design
• Jedis (Java) — synchronous Java client; ioredis is fully async and non-blocking
• Lettuce (Java) — reactive Java client; ioredis achieves similar async patterns in Node.js
• Upstash Redis — HTTP-based serverless client; ioredis uses persistent TCP for lower latency

FAQ

Q: Should I use ioredis or node-redis? A: ioredis is preferred for Redis Cluster and Sentinel deployments. node-redis has improved recently but ioredis remains more mature for complex topologies.

Q: Does it support Redis 7 features? A: Yes. ioredis supports client-side caching, sharded Pub/Sub, and function commands available in Redis 7+.

Q: How do I handle connection failures in production? A: Configure retryStrategy to return a delay in milliseconds. ioredis will reconnect automatically and replay queued commands.

Q: Can I use ioredis with Valkey? A: Yes. Valkey is API-compatible with Redis, and ioredis connects to it without any code changes.

Sources

• https://github.com/redis/ioredis
• https://redis.github.io/ioredis/