Migration Guide ioredis - valkey-io/valkey-glide GitHub Wiki

This guide provides a side-by-side comparison of how to migrate common Valkey commands from ioredis to Glide.

Installation

npm i @valkey/valkey-glide

Constructor

In ioredis, multiple constructors allow for various connection configurations.
In Glide, connections are established through a single configuration object, which comes pre-configured with best practices.

Glide requires minimal configuration changes, typically for:

Timeout settings
TLS
Read from replica
User authentication (username & password)

For advanced configurations, refer to the Glide Wiki - NodeJS.

Standalone Mode

ioredis

const Redis = require("ioredis");

const redis = new Redis();

Glide

import { GlideClient } from '@valkey/glide';

const addresses = [
        { host: "localhost", port: 6379 },
    ]; 

const client = await GlideClient.createClient({
    addresses: addresses
});

Cluster Mode

ioredis

const Redis = require("ioredis");

const cluster = new Redis.Cluster([
  { host: "127.0.0.1", port: 6379 },
  { host: "127.0.0.1", port: 6380 },
]);

Glide

import { GlideClusterClient } from '@valkey/glide';

const addresses = [
    { host: "127.0.0.1", port: 6379 },
    { host: "127.0.0.1", port: 6380 },
  ];

const client = await GlideClusterClient.createClient({
  addresses: addresses
});

ioredis vs. Glide Constructor Parameters

TODO: fix the table

The table below compares ioredis constructors with Glide configuration parameters:

ioredis Constructor	Equivalent Glide Configuration
`port: number`	`BaseClientConfiguration.addresses: { host: string; port?: number; }`
`host: string`	`BaseClientConfiguration.addresses: { host: string; port?: number; }`
`path: string`	Not supported
`tls: {}`	`BaseClientConfiguration.useTLS: true`
`options: RedisOptions`	`options: GlideClientConfiguration`

Advanced configuration

Standalone Mode uses AdvancedGlideClientConfiguration and Cluster Mode uses AdvancedGlideClusterClientConfiguration, but the usage is similar.

ioredis Constructor	Equivalent Glide Configuration
`connectTimeout: 500`	`BaseClientConfiguration.advancedConfiguration = {connectionTimeout: 500,};`

Commands in ioredis → Glide

Below is a list of the most commonly used Valkey commands in Glide clients and how they compare to ioredis.

Valkey Commands Sorted Alphabetically


AUTH	EXPIRE	MULTI
DECR	GET	RPUSH
DECRBY	HSET	SCAN
DEL	INCR	SET
EVAL	INCRBY	SETEX
EVALSHA	LPUSH
EXISTS	MGET

SET & GET

Both ioredis and Glide support this in the same way.

ioredis

await redis.set('key', 'value');
const val = await redis.get('key'); // "value"

Glide

await client.set('key', 'value');
const val = await client.get('key'); // "value"

DEL

The DEL command removes one or more keys from Valkey.

In ioredis, del() takes multiple arguments.
In Glide, del() expects an array.

ioredis

await redis.del('key1', 'key2'); // 2

Glide

await client.del(['key1', 'key2']); // 2

EXISTS

The EXISTS command checks if a key exists in Valkey.

In ioredis, accepts one or more arguments.
In Glide, expects an array of keys.
Both return the number of keys that exist.

ioredis

await redis.exists('existKey', 'nonExistKey'); // 1

Glide

await client.exists(['existKey', 'nonExistKey']); // 1

INCR / DECR

The INCR command increments the value of a key by 1, while DECR decrements it by 1.

Both clients support incr and decr identically.

ioredis

await redis.incr('counter'); // counter = 1
await redis.decr('counter'); // counter = 0

Glide

await client.incr('counter'); // counter = 1
await client.decr('counter'); // counter = 0

INCRBY / DECRBY

The INCRBY command increases the value of a key by a specified amount, while DECRBY decreases it by a specified amount.

Both behave the same: apply an integer delta to a key.

ioredis

await redis.incrby('counter', 5); // 5
await redis.decrby('counter', 2); // 3

Glide

await client.incrBy('counter', 5); // 5
await client.decrBy('counter', 2); // 3

MGET

The MGET command retrieves the values of multiple keys from Valkey.
todo Note: In cluster mode, if keys in keys map to different hash slots, the command will be split across these slots and executed separately for each. This means the command is atomic only at the slot level. If one or more slot-specific requests fail, the entire call will return the first encountered error, even though some requests may have succeeded while others did not. If this behavior impacts your application logic, consider splitting the request into sub-requests per slot to ensure atomicity.

In ioredis, mget() accepts multiple string arguments.
In Glide, pass an array of strings.

ioredis

const values = await redis.mget('key1', 'key2'); // ['value1', 'value2']

Glide

const values = await client.mget(['key1', 'key2']); // ['value1', value2']

HSET

The HSET command sets multiple field-value pairs in a hash.

In ioredis, fields and values are passed inline.
In Glide, use a key-value object.

ioredis

await redis.hset('hash', 'key1', '1', 'key2', '2'); // 2

Glide

await client.hset('hash', { key1: '1', key2: '2' }); // 2

EXPIRE

The EXPIRE command sets a time-to-live (TTL) for a key.

Both clients support TTL expiration using expire.
In ioredis, it returns a number 1 if successful or 0 if otherwise.
In Glide, it returns a boolean indicating success.

ioredis

await redis.expire('key', 10); // 1

Glide

await client.expire('key', 10); // true

SETEX

The SETEX command sets a key with an expiration time.

In ioredis, setex is a dedicated function.
In Glide, TTL is passed as an option to set.

ioredis

await redis.setex('key', 5, 'value'); // OK

Glide

import { TimeUnit } from "@valkey/valkey-glide";

await client.set('key', 'value', {expiry: {type: TimeUnit.Seconds, count: 5 }}); // OK

LPUSH / RPUSH

LPUSH adds to the start of a Valkey list, RPUSH to the end.

ioredis: accepts multiple values, returns new list length.
Glide: values must be in an array, also returns new length.

ioredis

let lengthOfList = await redis.lpush('list', 'a', 'b', "c");    // lengthOfList = 3
lengthOfList = await redis.rpush('list', 'd', 'e');             // lengthOfList = 5

Glide

let lengthOfList = await client.lpush("list", ["a", "b", "c"]); // lengthOfList = 3
lengthOfList = await client.rpush("list", ["d", "e"]);          // lengthOfList = 5

SCAN

ioredis ioredis uses different constructors while Glide uses a single scan method with options.
Glide supports cluster mode scanning to scan the entire cluster. For more.

ioredis

let cursor = '0';
let result;
do {
    result = await client.scan(cursor);
    cursor = result[0];

    const keys = result[1];
    if (keys.length > 0) {
        console.log('SCAN iteration: ' + keys.join(', '));
    }
} while (cursor !== '0');

Glide

let cursor = '0';
let result;
do {
    result = await client.scan(cursor);
    cursor = result[0].toString();

    const keys = result[1];
    if (keys.length > 0) {
        console.log('SCAN iteration: ' + keys.join(', '));
    }
} while (cursor !== '0');

Transactions (MULTI / EXEC)

The MULTI command starts a Valkey transaction.
The EXEC command executes all queued commands in the transaction.

In ioredis, transactions are started using redis.multi(). exec returns [[error, result], ...]
In Glide, transactions are represented as a Transaction object. exec returns [result1, result2, ...]

ioredis

const transaction = redis.multi()
        .set("key", "value")
        .get("key");
const result = await transaction.exec(); // 
console.log(result); // Output: [ [ null, 'OK' ], [ null, 'value' ] ]

Glide

import { Transaction } from "@valkey/valkey-glide";
const transaction = new Transaction()
            .set("key", "value")
            .get("key");
const result = await client.exec(transaction);
console.log(result); // Output: ['OK', 'value']

EVAL / EVALSHA

The EVAL and EVALSHA commands execute Lua scripts in Valkey.

In ioredis, Lua scripts are executed using eval() or evalsha().
In Glide, Lua scripts are executed via invokeScript() using a Script object.
The Script class wraps the Lua script.

Jedis

// EVAL
const luaScript = `return { KEYS[1], ARGV[1] }`;
const scriptOptions = {
    keys: ["foo"],
    args: ["bar"],
};

const result = await redis.eval(luaScript, 1, ...scriptOptions.keys, ...scriptOptions.args);
console.log(result); // Output: ['foo', 'bar']

Glide

import { Script } from "@valkey/valkey-glide";

const luaScript = new Script("return { KEYS[1], ARGV[1] }");
const scriptOptions = {
    keys: ["foo"],
    args: ["bar"],
};

const result = await client.invokeScript(luaScript, scriptOptions);
console.log(result); // Output: ['foo', 'bar']

AUTH

The AUTH command is used to authenticate a Valkey connection with a password.

In ioredis, auth() is a direct method call.
In Glide, use updateConnectionPassword.

ioredis

await redis.auth('mypass'); // OK

Glide

await client.updateConnectionPassword('mypass'); // OK

Custom Command

The customCommand function lets you execute any Valkey command as a raw list of arguments, without input validation. It's a flexible option when the standard Glide API doesn't cover a specific command.

Example:

await client.customCommand(['SET', 'key', 'value']);

This sends the raw SET key value command to Valkey.

Migration Guide ioredis - valkey-io/valkey-glide GitHub Wiki

Installation

Constructor

Commands in ioredis → Glide

Valkey Commands Sorted Alphabetically

Custom Command

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️