A simple Redis pool for node using generic-pool.





GitHub Stars



Last Commit

5mos ago








Type Definitions





DEPRECATED sol-redis-pool

No Maintenance Intended

A simple Redis pool for node using generic-pool.


npm install sol-redis-pool


Pull requests welcome...

Constructor: RedisPool(redis_settings, pool_settings)

Create a new Redis connection pool.

    // Configure the Redis client connection settings.
    var redisSettings = {
        host: "",
        port: 6379,
        password: "dingbats",
        db: 3 // Set the default DB number.
    // Configure the generic-pool settings.
    var poolSettings = {
        max: 10,
        min: 2
    var myPool = RedisPool(redisSettings, poolSettings);

Redis Client Settings.

Redis Connection Options

host127.0.0.1IP address of the Redis server
port6379TCP Port of the Redis server
pathnullThe UNIX socket string of the Redis server. e.g. /tmp/redis.sock.
urlnullThe URL of the Redis server. Format: [redis:]//[[user][:password@]][host][:port][/db-number][?db=db-number[&password=bar[&option=value]]] (More info avaliable at IANA).
passwordnullIf set, client will run Redis auth command on connect.
auth_passDeprecatedPlease use the password option instead.
unix_socketDeprecatedPlease use the path option instead.


The auth_pass option is deprecated. Please use the password option instead.

passwordIf set, the client will run redis auth command on connect.

Additional node_redis Settings.

When you acquire a new client these options can be passed to the Redis client. See for more details.

string_numbersnullSet to true, node_redis will return Redis number values as Strings instead of javascript Numbers. Useful if you need to handle big numbers (above Number.MAX_SAFE_INTEGER === 2^53). Hiredis is incapable of this behavior, so setting this option to true will result in the built-in javascript parser being used no matter the value of the parser option.
return_buffersfalseIf set to true, then all replies will be sent to callbacks as Buffers instead of Strings.
detect_buffersfalseIf set to true, then replies will be sent to callbacks as Buffers. This option lets you switch between Buffers and Strings on a per-command basis, whereas return_buffers applies to every command on a client. Note: This doesn't work properly with the pubsub mode. A subscriber has to either always return Strings or Buffers.
socket_keepalivetrueIf set to true, the keep-alive functionality is enabled on the underlying socket.
no_ready_checkfalseWhen a connection is established to the Redis server, the server might still be loading the database from disk. While loading, the server will not respond to any commands. To work around this, node_redis has a "ready check" which sends the INFO command to the server. The response from the INFO command indicates whether the server is ready for more commands. When ready, node_redis emits a ready event. Setting no_ready_check to true will inhibit this check.
enable_offline_queuetrueBy default, if there is no active connection to the Redis server, commands are added to a queue and are executed once the connection has been established. Setting enable_offline_queue to false will disable this feature and the callback will be executed immediately with an error, or an error will be emitted if no callback is specified.
retry_unfulfilled_commandsfalseIf set to true, all commands that were unfulfilled while the connection is lost will be retried after the connection has been reestablished. Use this with caution if you use state altering commands (e.g. incr). This is especially useful if you use blocking commands.
dbnullIf set, client will run Redis select command on connect.
familyIPv4You can force using IPv6 if you set the family to 'IPv6'. See Node.js net or dns modules on how to use the family type.
disable_resubscribingfalseIf set to true, a client won't resubscribe after disconnecting.
rename_commandsnullPassing an object with renamed commands to use instead of the original functions. See the Redis security topics for more info.
tlsnullAn object containing options to pass to tls.connect to set up a TLS connection to Redis (if, for example, it is set up to be accessible via a tunnel).
prefixnullA string used to prefix all used keys (e.g. namespace:test). Please be aware that the keys command will not be prefixed. The keys command has a "pattern" as argument and no key and it would be impossible to determine the existing keys in Redis if this would be prefixed.
retry_strategyfunctionA function that receives an options object as parameter including the retry attempt, the total_retry_time indicating how much time passed since the last time connected, the error why the connection was lost and the number of times_connected in total. If you return a number from this function, the retry will happen exactly after that time in milliseconds. If you return a non-number, no further retry will happen and all offline commands are flushed with errors. Return an error to return that specific error to all offline commands. Example below.

Retry Strategy

Note: The error value is set to null on the first failure.

// The first connection attempt.
{ attempt: 1,
  error: null,
  total_retry_time: 0,
  times_connected: 1 }
// The second attempt.
{ attempt: 2,
   { [Error: Redis connection to failed - connect ECONNREFUSED]
     code: 'ECONNREFUSED',
     errno: 'ECONNREFUSED',
     syscall: 'connect',
     address: '',
     port: 6379 },
  total_retry_time: 1000,
  times_connected: 1 }

A Simple Reconnect Strategy.

    retry_strategy: function (options) {
        if (options.attempt > 10) {
            // Stop retrying afer 10 attempts.
            return undefined;
        // Increase reconnect delay by 150ms.
        return options.attempt * 150;

No Reconnect Strategy

Use this strategy when you want to pool to not attempt reconnections.

    retry_strategy: function (options) {
        return undefined;

Generic Pool Settings

Supported generic-pool settings. See for more information.

nameoptionalName of the pool.
max1Maximum number of resources to create at a given time.
min0Minimum number of resources to keep in pool at any given time if this is set > max, the pool will silently set the min to factory.max - 1
refreshIdletrueBoolean that specifies whether idle resources at or below the min threshold should be destroyed/re-created. (Optional)
idleTimeoutMillis30000Max milliseconds a resource can go unused before it should be destroyed.
reapIntervalMillis1000Frequency to check for idle resources.
returnToHeadfalseBoolean, if true the most recently released resources will be the first to be allocated. This in effect turns the pool's behaviour from a queue into a stack.
priorityRange1Int between 1 and x - if set, borrowers can specify their relative priority in the queue if no resources are available.


acquire(callback, [priority])

Acquires a redis client from the pool. The callback is passed an err and client. The client object is a normal redis client. Make sure you release the client using the .release(client) method when you are done.

The pool now supports optional priority queueing. This becomes relevant when no resources are available and the caller has to wait. acquire() accepts an optional priority int which specifies the caller's relative position in the queue. This requires setting the pool option priorityRange. See for more information.

acquireDb(callback, db, [priority])

Same as the aquire method but allows you to select a DB.


This method will release your client object back into the pool. Use this method when you no longer need the client.


This method will drain the connection pool completely and execute the callback when finished. You should call this when you want to close your application. If you do not your application will continue to run forever.


Returns the for this pool.


Returns number of resources in the pool regardless of whether they are free or in use.


Returns number of unused resources in the pool.


Returns number of callers waiting to acquire a resource.


Additional events will be added.


This event is emitted when a Redis client emits an "error", connection error event. You still need to pay attention to the err passed to your callback when you issue an acquire. The error object contains an attribute named cid for tracking which client connection had an error.


The pool will emit reconnecting when trying to reconnect to the Redis server after losing the connection. Listeners are passed an object containing delay (in ms), attempt (the attempt #), and cid attributes.


This event is emitted when a Redis client is closed by the connection pool. The event will pass an error and cid value.


Examples are located in the examples/ folder in the repository. These examples will automatically close when done. If you change the min option for the pool the application will stay running forever.

  • authentication.js - shows an example using a redis password.
  • oversubscribe.js - shows what happens when you request more clients than you have in your pool.
  • ping-example.js - a simple example that issues a Redis PING command.
  • offline.js - shows how the enable_offline_queue option and recovery works.
  • retry.js - shows a retry_strategy option in action.
  • unix.js - shows a unix socket connection.


0.3.3 - April 28 2017

  • Added prefix option. #25

0.3.2 - October 23 2016

  • Added bluebird promise support for underlying redis connections in the pool. #21
  • Added the tls redis option. #22

0.3.1 - August 31 2016

  • Prevent the pool.release(client) method from releasing a disconnected client back into the pool. Fixes issue #19. Some users may need to watch their pool min value.
  • Added connection tracking to all clients int the pool. You may access the value using the client._sol_cid property. This value is passed to the destroy, reconnecting, and error events as well. This should help users with their application logging.
  • Improved the retry_strategy examples in the and fixed the retry.js example.
  • Fixed some examples.
  • Fixed a bug in the reconnecting event.
  • Updated redis-pool-spec.js file.
  • Moved older changes to

0.3.0 - August 28 2016

  • Client Connection Changes:
    • Replaced the auth_pass option with password.
    • Replaced the unix_socket option with path.
    • Added the url option for connections.
    • Fixed an issue with an extra select statement being sent on client connect when the db option is set.
  • Added support for the redis client retry_strategy option.
  • Removed deprecated options: 'parser', 'socket_nodelay', 'retry_max_delay', 'connect_timeout', 'max_attempts'
  • Added options: 'string_numbers', 'retry_unfulfilled_commands', 'disable_resubscribing', 'rename_commands'
  • Changed minimum redis client version to 2.6.2.
  • Added a reconnecting event.

Rate & Review

Great Documentation0
Easy to Use0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Unwelcoming Community0
No reviews found
Be the first to rate


No alternatives found


No tutorials found
Add a tutorial