docs/interfaces/ClusterOptions.html
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;
}
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?
Optional autoPipeliningIgnoredCommandsautoPipeliningIgnoredCommands?: string[]
See Redis class.
[]Copy
Optional clusterNodeRetryStrategyclusterNodeRetryStrategy?: ((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.
- times: number
clusterNodeRetryStrategy: (times) => Math.min(times * 100, 3000)Copy
nullCopy
Optional clusterRetryStrategyclusterRetryStrategy?: ((times, reason?) => number | void)
See "Quick Start" section.
- times: number
- `Optional` reason: Error
(times) => Math.min(100 + times * 2, 2000)Copy
Optional dnsLookupdnsLookup?: 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.
require('dns').lookupCopy
Optional enableAutoPipeliningenableAutoPipelining?: boolean
See Redis class.
falseCopy
Optional enableOfflineQueueenableOfflineQueue?: boolean
See Redis class.
trueCopy
Optional enableReadyCheckenableReadyCheck?: boolean
When enabled, ioredis only emits "ready" event when CLUSTER INFO command reporting the cluster is ready for handling commands.
trueCopy
Optional Experimental himportFieldsetshimportFieldsets?: 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.
undefined@experimentalCopy
Optional keyPrefixkeyPrefix?: string
Optional lazyConnectlazyConnect?: 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.
falseCopy
Optional maxRedirectionsmaxRedirections?: 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.
16Copy
Optional natMapnatMap?: NatMap
Optional redisOptionsredisOptions?: Omit<RedisOptions, "path" | "host" | "port" | "readOnly" | "sentinels" | "retryStrategy" | "enableOfflineQueue" | "himportFieldsets">
Passed to the constructor of Redis
nullCopy
Optional resolveSrvresolveSrv?: 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.
require('dns').resolveSrvCopy
Optional retryDelayOnClusterDownretryDelayOnClusterDown?: number
When a CLUSTERDOWN error is received, client will retry if retryDelayOnClusterDown is valid delay time (in ms).
100Copy
Optional retryDelayOnFailoverretryDelayOnFailover?: 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).
100Copy
Optional retryDelayOnMovedretryDelayOnMoved?: 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.
0Copy
Optional retryDelayOnTryAgainretryDelayOnTryAgain?: number
When a TRYAGAIN error is received, client will retry if retryDelayOnTryAgain is valid delay time (in ms).
100Copy
Optional scaleReadsscaleReads?: Function | NodeRole
Scale reads to the node with the specified role.
"master"Copy
Optional scriptsscripts?: Record<string, {
lua: string;
numberOfKeys?: number;
readOnly?: boolean;
}>
Custom LUA commands
Optional numberOfKeys?: numberOptional readOnly?: booleanOptional shardedSubscribersshardedSubscribers?: 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.
falseCopy
Optional showFriendlyErrorStackshowFriendlyErrorStack?: boolean
Optional slotsRefreshIntervalslotsRefreshInterval?: number
The milliseconds between every automatic slots refresh.
5000Copy
Optional slotsRefreshTimeoutslotsRefreshTimeout?: number
The milliseconds before a timeout occurs while refreshing slots from the cluster.
1000Copy
Optional useSRVRecordsuseSRVRecords?: boolean
Discover nodes using SRV records
falseCopy
OSLightDark
autoPipeliningIgnoredCommandsclusterNodeRetryStrategyclusterRetryStrategydnsLookupenableAutoPipeliningenableOfflineQueueenableReadyCheckhimportFieldsetskeyPrefixlazyConnectmaxRedirectionsnatMapredisOptionsresolveSrvretryDelayOnClusterDownretryDelayOnFailoverretryDelayOnMovedretryDelayOnTryAgainscaleReadsscriptsshardedSubscribersshowFriendlyErrorStackslotsRefreshIntervalslotsRefreshTimeoutuseSRVRecords