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 has better performance than any other third-party Promise implementations, and Bluebird is deprecated, so in v5, ioredis always uses the native implementation. Redis.Promise = require("bluebird") will become 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.

• 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.