Interface ClusterOptions

Options for Cluster constructor

interface ClusterOptions {
    autoPipeliningIgnoredCommands?: string[];
    clusterNodeRetryStrategy?: ((times) => number | void);
    clusterRetryStrategy?: ((times, reason?) => number | void);
    dnsLookup?: DNSLookupFunction;
    enableAutoPipelining?: boolean;
    enableOfflineQueue?: boolean;
    enableReadyCheck?: boolean;
    himportFieldsets?: readonly HimportFieldset[];
    keyPrefix?: string;
    lazyConnect?: boolean;
    maxRedirections?: number;
    natMap?: NatMap;
    redisOptions?: Omit<RedisOptions, "path" | "host" | "port" | "readOnly" | "sentinels" | "retryStrategy" | "enableOfflineQueue" | "himportFieldsets">;
    resolveSrv?: DNSResolveSrvFunction;
    retryDelayOnClusterDown?: number;
    retryDelayOnFailover?: number;
    retryDelayOnMoved?: number;
    retryDelayOnTryAgain?: number;
    scaleReads?: Function | NodeRole;
    scripts?: Record<string, {
        lua: string;
        numberOfKeys?: number;
        readOnly?: boolean;
    }>;
    shardedSubscribers?: boolean;
    showFriendlyErrorStack?: boolean;
    slotsRefreshInterval?: number;
    slotsRefreshTimeout?: number;
    useSRVRecords?: boolean;
}

Hierarchy

  • CommanderOptions
    • ClusterOptions

Properties

autoPipeliningIgnoredCommands? clusterNodeRetryStrategy? clusterRetryStrategy? dnsLookup? enableAutoPipelining? enableOfflineQueue? enableReadyCheck? himportFieldsets? keyPrefix? lazyConnect? maxRedirections? natMap? redisOptions? resolveSrv? retryDelayOnClusterDown? retryDelayOnFailover? retryDelayOnMoved? retryDelayOnTryAgain? scaleReads? scripts? shardedSubscribers? showFriendlyErrorStack? slotsRefreshInterval? slotsRefreshTimeout? useSRVRecords?

Properties

Optional autoPipeliningIgnoredCommands

autoPipeliningIgnoredCommands?: string[]

See Redis class.

Default

[]

Optional clusterNodeRetryStrategy

clusterNodeRetryStrategy?: ((times) => number | void)

When a cluster node connection is closed, this function will be called to determine the retry delay (in ms). Returning null or a non-number disables reconnection for that node.

By default this is null, meaning cluster nodes will NOT automatically reconnect — the cluster relies on MOVED errors to refresh topology. Set this to enable reconnection, e.g. for replica nodes that restart without any slot changes.

Type declaration

    • (times): number | void

    • Parameters

      • times: number

      Returns number | void

Example

clusterNodeRetryStrategy: (times) => Math.min(times * 100, 3000)

Default

null

Optional clusterRetryStrategy

clusterRetryStrategy?: ((times, reason?) => number | void)

See "Quick Start" section.

Type declaration

    • (times, reason?): number | void

    • Parameters

      • times: number
      • Optional reason: Error

      Returns number | void

Default

(times) => Math.min(100 + times * 2, 2000)

Optional dnsLookup

dnsLookup?: DNSLookupFunction

Hostnames will be resolved to IP addresses via this function. This is needed when the addresses of startup nodes are hostnames instead of IPs.

You may provide a custom lookup function when you want to customize the cache behavior of the default function.

Default

require('dns').lookup

Optional enableAutoPipelining

enableAutoPipelining?: boolean

See Redis class.

Default

false

Optional enableOfflineQueue

enableOfflineQueue?: boolean

See Redis class.

Default

true

Optional enableReadyCheck

enableReadyCheck?: boolean

When enabled, ioredis only emits "ready" event when CLUSTER INFO command reporting the cluster is ready for handling commands.

Default

true

Optional Experimental himportFieldsets

himportFieldsets?: readonly HimportFieldset[]

Managed-fieldset support is experimental and requires Redis 8.10 or newer.

Long-lived HIMPORT fieldsets managed across all current and future master connections for the lifetime of this Cluster client. Configure this option at the top level, not under redisOptions.

When a managed HIMPORT SET needs fieldset preparation or recovery, later commands issued on this Cluster client may be sent before that SET resumes. Await the SET before issuing commands that depend on its write.

Explicit pipelines containing a managed HIMPORT SET wait for required fieldset preparation on the selected master before the batch is sent.

Background preparation failures do not prevent the connection from becoming ready and are reported through the node error event. A dependent managed HIMPORT SET retries preparation and rejects if recovery fails.

Direct HIMPORT PREPARE, DISCARD, and DISCARDALL calls fan out to all current masters. Within an explicit pipeline, these commands remain connection-affine and are not managed.

Use explicit HIMPORT commands on a separate unconfigured client for bounded, manually managed batches.

Default

undefined
@experimental

Optional keyPrefix

keyPrefix?: string

Optional lazyConnect

lazyConnect?: boolean

By default, When a new Cluster instance is created, it will connect to the Redis cluster automatically. If you want to keep the instance disconnected until the first command is called, set this option to true.

Default

false

Optional maxRedirections

maxRedirections?: number

When a MOVED or ASK error is received, client will redirect the command to another node. This option limits the max redirections allowed to send a command.

Default

16

Optional natMap

natMap?: NatMap

Optional redisOptions

redisOptions?: Omit<RedisOptions, "path" | "host" | "port" | "readOnly" | "sentinels" | "retryStrategy" | "enableOfflineQueue" | "himportFieldsets">

Passed to the constructor of Redis

Default

null

Optional resolveSrv

resolveSrv?: DNSResolveSrvFunction

SRV records will be resolved via this function.

You may provide a custom resolveSrv function when you want to customize the cache behavior of the default function.

Default

require('dns').resolveSrv

Optional retryDelayOnClusterDown

retryDelayOnClusterDown?: number

When a CLUSTERDOWN error is received, client will retry if retryDelayOnClusterDown is valid delay time (in ms).

Default

100

Optional retryDelayOnFailover

retryDelayOnFailover?: number

When an error is received when sending a command (e.g. "Connection is closed." when the target Redis node is down), client will retry if retryDelayOnFailover is valid delay time (in ms).

Default

100

Optional retryDelayOnMoved

retryDelayOnMoved?: number

By default, this value is 0, which means when a MOVED error is received, the client will resend the command instantly to the node returned together with the MOVED error. However, sometimes it takes time for a cluster to become state stabilized after a failover, so adding a delay before resending can prevent a ping pong effect.

Default

0

Optional retryDelayOnTryAgain

retryDelayOnTryAgain?: number

When a TRYAGAIN error is received, client will retry if retryDelayOnTryAgain is valid delay time (in ms).

Default

100

Optional scaleReads

scaleReads?: Function | NodeRole

Scale reads to the node with the specified role.

Default

"master"

Optional scripts

scripts?: Record<string, {
    lua: string;
    numberOfKeys?: number;
    readOnly?: boolean;
}>

Custom LUA commands

Type declaration

  • lua: string
  • Optional numberOfKeys?: number
  • Optional readOnly?: boolean

Optional shardedSubscribers

shardedSubscribers?: boolean

Use sharded subscribers instead of a single subscriber.

If sharded subscribers are used, then one additional subscriber connection per master node is established. If you don't plan to use SPUBLISH/SSUBSCRIBE, then this should be disabled.

Default

false

Optional showFriendlyErrorStack

showFriendlyErrorStack?: boolean

Optional slotsRefreshInterval

slotsRefreshInterval?: number

The milliseconds between every automatic slots refresh.

Default

5000

Optional slotsRefreshTimeout

slotsRefreshTimeout?: number

The milliseconds before a timeout occurs while refreshing slots from the cluster.

Default

1000

Optional useSRVRecords

useSRVRecords?: boolean

Discover nodes using SRV records

Default

false

Settings

Member Visibility

Theme

On This Page

autoPipeliningIgnoredCommandsclusterNodeRetryStrategyclusterRetryStrategydnsLookupenableAutoPipeliningenableOfflineQueueenableReadyCheckhimportFieldsetskeyPrefixlazyConnectmaxRedirectionsnatMapredisOptionsresolveSrvretryDelayOnClusterDownretryDelayOnFailoverretryDelayOnMovedretryDelayOnTryAgainscaleReadsscriptsshardedSubscribersshowFriendlyErrorStackslotsRefreshIntervalslotsRefreshTimeoutuseSRVRecords