JedisPool resource pool optimization

Usage

This example uses Jedis 2.9.0. Maven dependency:

<dependency>
    <groupId>redis.clients</groupId>
    <artifactId>jedis</artifactId>
    <version>2.9.0</version>
    <scope>compile</scope>
</dependency>

Jedis uses Apache Commons-pool2 for pool management. The key parameter class is GenericObjectPoolConfig:

GenericObjectPoolConfig jedisPoolConfig = new GenericObjectPoolConfig();
jedisPoolConfig.setMaxTotal(...);
jedisPoolConfig.setMaxIdle(...);
jedisPoolConfig.setMinIdle(...);
jedisPoolConfig.setMaxWaitMillis(...);
...

Initialize a JedisPool:

// redisHost is the IP address of the instance. redisPort is the port of the instance. redisPassword is the password of the instance. timeout is both the connection timeout and the read/write timeout.
JedisPool jedisPool = new JedisPool(jedisPoolConfig, redisHost, redisPort, timeout, redisPassword);
// Execute commands as follows.
Jedis jedis = null;
try {
    jedis = jedisPool.getResource();
    // Specific commands.
    jedis.executeCommand()
} catch (Exception e) {
    logger.error(e.getMessage(), e);
} finally {
    // In JedisPool mode, the Jedis object is returned to the resource pool.
    if (jedis != null) 
        jedis.close();
}

Parameters

JedisPool manages Jedis connections in a thread-safe, bounded pool. A proper GenericObjectPoolConfig configuration improves Redis performance and reduces resource overhead. The following tables describe key parameters and recommended settings.

The following four parameters control idle connection detection.

JedisPoolConfig extends GenericObjectPoolConfig with these idle detection defaults:

public class JedisPoolConfig extends GenericObjectPoolConfig {
  public JedisPoolConfig() {
    setTestWhileIdle(true);
    setMinEvictableIdleTimeMillis(60000);
    setTimeBetweenEvictionRunsMillis(30000);
    setNumTestsPerEvictionRun(-1);
    }
}

Recommended settings for key parameters

maxTotal (maximum connections)

Consider the following factors when setting maxTotal:

• Expected Redis concurrency.

• Client-side command execution time.

• Available Redis resources. The number of nodes (application ECS instances) multiplied by maxTotal must not exceed the maximum connections allowed for the instance. Check the instance details page for this limit.

• Resource overhead from idle connections and frequent pool scaling.

Example: if average command time (borrow + execute + network) is 1 ms, one connection handles ~1,000 QPS. For a target of 50,000 QPS on a single instance (total QPS / number of shards), the theoretical maxTotal is 50,000 / 1,000 = 50.

Add a buffer above the theoretical value. However, oversizing maxTotal wastes client and server resources and does not help when large commands cause blocking.

maxIdle and minIdle

maxIdle represents the actual peak connections your workload needs, while maxTotal provides a buffer. Avoid setting maxIdle too low — this forces the pool to frequently create new Jedis connections. minIdle controls idle resource detection.

Best performance occurs when maxTotal equals maxIdle, which avoids pool scaling overhead. Set them equal if your workload has traffic spikes. If concurrency is low or maxIdle is too high, idle connections are wasted.

Estimate pool size per node based on total QPS and the number of client instances.

Use monitoring to obtain reasonable values

In production, use JMX or other monitoring to determine optimal values based on actual usage patterns.

FAQ

Insufficient resources

The following cases prevent obtaining a resource from the pool.

• Timeout:

  redis.clients.jedis.exceptions.JedisConnectionException: Could not get a resource from the pool
  …
  Caused by: java.util.NoSuchElementException: Timeout waiting for idle object
  at org.apache.commons.pool2.impl.GenericObjectPool.borrowObject(GenericObjectPool.java:449)

• The blockWhenExhausted parameter is set to false, so the call does not wait for a resource to be released:

  redis.clients.jedis.exceptions.JedisConnectionException: Could not get a resource from the pool
  …
  Caused by: java.util.NoSuchElementException: Pool exhausted
  at org.apache.commons.pool2.impl.GenericObjectPool.borrowObject(GenericObjectPool.java:464)

This exception is not always caused by an insufficient pool size. It can also result from network issues, misconfigured pool parameters, JMX monitoring, missing jedis.close() calls, slow queries, or DNS problems. Recommended settings for key parameters.

Warming up JedisPool

JedisPool does not eagerly create connections on initialization. The first request triggers a new Jedis connection, which adds latency. With a small timeout, this may cause timeouts at startup. To avoid this, prefetch connections based on minIdle after pool creation:

List<Jedis> minIdleJedisList = new ArrayList<Jedis>(jedisPoolConfig.getMinIdle());

for (int i = 0; i < jedisPoolConfig.getMinIdle(); i++) {
    Jedis jedis = null;
    try {
        jedis = pool.getResource();
        minIdleJedisList.add(jedis);
        jedis.ping();
    } catch (Exception e) {
        logger.error(e.getMessage(), e);
    } finally {
    }
}

for (int i = 0; i < jedisPoolConfig.getMinIdle(); i++) {
    Jedis jedis = null;
    try {
        jedis = minIdleJedisList.get(i);
        jedis.close();
    } catch (Exception e) {
        logger.error(e.getMessage(), e);
    } finally {
    
    }
}

For other errors, see Common errors.