Upgrading from v4 to v5

In the update of v5, we've made ioredis even more stable and developer-friendly while minimizing the number of breaking changes, so you can spend more time enjoying your life 😄.

This guide will provide you with a number of checklists to help you understand how to upgrade your application.

• Make sure your project uses Node.js 12 or newer.

  In v5, ioredis uses new features introduced in Node.js 12 to make the library more lightweight and easier to maintain. You need to make sure your project runtime uses Node.js 12 or newer.

• Only native Promise is supported.

  Previously, ioredis allows you to plug in a third-party Promise implementation (e.g. Bluebird) with Redis.Promise:

  const Redis = require("ioredis");
  Redis.Promise = require("bluebird");

  However, native Promise is stable enough and generally has better performance than any other third-party Promise implementations. What's more, Bluebird is already officially deprecated, so in v5, ioredis always uses the native implementation. Redis.Promise = require("bluebird") is a noop and you can remove it from your codebase.

• (TypeScript projects only) Official declarations are provided.

  Before v5, you need to install @types/ioredis for your TypeScript projects in order to get declarations for ioredis. However, that brings many issues caused by the declarations and the actual code don't match. In v5, ioredis provides TypeScript declarations officially so you can uninstall @types/ioredis:

  npm uninstall @types/ioredis

  There may be TypeScript errors after the upgrade due to the official declarations are not exactly the same as @types/ioredis. Those errors should be easy to catch and fix, and they don't affect actual compiled JavaScript code.

  However, if your project is an npm library and exposes typings directly from ioredis, you may want to double-check whether new typings are compatible with the old ones.

  Some possible TypeScript errors you may encounter and how to solve them:

  // Case 1: import Redis
  import * as Redis from 'ioredis'
  // Should be `import Redis from 'ioredis'`
  
  // Case 2: Cluster typing
  import Redis from 'ioredis'
  const cluster: Redis.Cluster = new Redis.Cluster([30000]);
  // Should be:
  // import { Cluster } from 'ioredis'
  // const cluster: Cluster = new Cluster([30000]);
  
  // Case 3: lower-case tokens
  redis.set('key', 'value', 'ex', 20)
  // Should be `redis.set('key', 'value', 'EX', 20)`.
  // Redis is case insensitive for the tokens (`EX`) but to avoid unnecessary
  // function overloads, ioredis only provides declarations for upper-case tokens,
  // although lower-case tokens still work if you ignore the TypeScript errors with
  // `// @ts-ignore`.

• Username in Redis URI is supported.

  Before ACL is a thing in Redis, username is not supported by Redis. Because of that, before ioredis v5, the username part in a Redis URI is ignored by ioredis: new Redis("redis://username:authpassword@127.0.0.1:6380/4"). Considering developers may pass random usernames in the URI, ioredis required allowUsernameInURI to be present in the URI in order to recognise username: new Redis("redis://username:authpassword@127.0.0.1:6380/4?allowUsernameInURI=true").

  In v5, allowUsernameInURI is removed and the username part will always be used. If you don't want to pass username to Redis, just omit the username part in your URI: new Redis("redis://:authpassword@127.0.0.1:6380/4").

• (Cluster only) slotsRefreshInterval is disabled by default.

  Previously, the default value was 5000, which means ioredis would refresh cluster slots every 5s even when there are no MOVED or CLUSTERDOWN errors. Generally, we think this feature should be optional and need developers' awareness to enable explicitly.