Connection pool settings

Use this page to configure connection pool settings.

This administrative console page is common to JDBC data sources and JMS connection factories (unified, queue, or topic connection factories). To view this page, the path depends on the type of resource, but generally you select an instance of the resource type then click Connection Pool. For example:
  • Click Resources > JDBC > Data Sources > data_source > [Additional Properties] Connection pool properties
  • Click Resources > JMS->Queue connection factories->queue_connection_factory->[Additional Properties] Connection pool
Note: Connection pooling is not supported in an application client. The application client calls the database directly and does not go through a data source. If you want to use the getConnection() request from the application client, configure the JDBC provider in the application client deployment descriptors, using Rational® Application Developer or an assembly tool. The connection is established between application client and the database. Application clients do not have a connection pool, but you can configure JDBC provider settings in the client deployment descriptors.

Connection timeout

Specifies the interval, in seconds, after which a connection request times out and a ConnectionWaitTimeoutException is thrown.

This value indicates the number of seconds that a connection request waits when there are no connections available in the free pool and no new connections can be created. This usually occurs because the maximum value of connections in the particular connection pool has been reached.

For example, if Connection timeout is set to 300, and the maximum number of connections are all in use, the pool manager waits for 300 seconds for a physical connection to become available. If a physical connection is not available within this time, the pool manager initiates a ConnectionWaitTimeout exception. In most cases, you should not retry the getConnection() method; if a longer wait time is required you should increase the Connection timeout setting value. If a ConnectionWaitTimeout exception is caught by the application, review the expected connection pool usage of the application and tune the connection pool and database accordingly.

If the Connection timeout is set to 0, the pool manager waits as long as necessary until a connection becomes available. This happens when the application completes a transaction and returns a connection to the pool, or when the number of connections is less than the value of Maximum Connections, and a new physical connection is created.

If Maximum Connections is set to 0, an infinite number of physical connections are enabled, and the Connection timeout value is ignored.

Information Value
Data type Integer
Units Seconds
Default 180
Range 0 to max int

Maximum connections

Specifies the maximum number of physical connections that you can create in this pool.

These are the physical connections to the backend resource. When this number is reached, no new physical connections are created. The requester waits until a physical connection that is currently in use returns to the pool, or until a ConnectionWaitTimeoutException error displays. For example, if the Max Connections value is set to 5, and there are 5 physical connections in use, the pool manager waits for the amount of time specified in Connection timeout for a physical connection to become free.

Knowing the number of connection pools that can potentially request connections from the backend, such as a DB2® database or a CICS® server, helps you determine a value for the Maximum Connections property.

[AIX Solaris HP-UX Linux Windows][IBM i]For multiple stand-alone application servers that use the same data source configuration, or J2C connection factory configuration, a separate physical connection pool exists for each server. If you clone these same application servers, WebSphere® Application Server (base) implements a separate connection pool for each clone.

[z/OS]Consider the number of servants that access the same resource; at run time, this number essentially multiplies your Maximum Connections setting. When servants start the same JDBC data source or J2C connection factory configuration, WebSphere Application Server (base) implements a corresponding physical connection pool for every servant. Therefore the same connection pool exists, independently, in each servant. Your Maximum Connections setting applies to each one of these pools.

[AIX Solaris HP-UX Linux Windows][IBM i]All of these connection pools correspond to the same data source or connection factory configuration. Therefore all of these connection pools can potentially request connections from the same backend resource, at the same time. The single Maximum Connections value that you set on this console panel applies to every one of these connection pools. Consequently, setting a high Maximum Connections value can result in a load of connection requests that overwhelms your backend resource.

[z/OS]Potentially, every application that requires the data source or connection factory in these servants can attempt to use the resource simultaneously. Therefore the corresponding connection pools require connections from the same backend, at the same time. Do not set a Maximum Connections value that might cause the load of connection requests to overwhelm your database or other enterprise information system (EIS).

Information Value
Data type Integer
Default 10
Range 0 to maximum integer

If Max Connections is set to 0, the Connection timeout value is ignored.

Tip: For better performance, set the connection pool to a value less than the value for the maximum thread pool connections of the web container. To configure the maximum threads for the web container, click Servers > Server types > WebSphere application servers > server > Thread Pools, and modify the web container property. Lower settings, such as 10 - 30 connections, perform better than higher settings, such as 100.
In some situations, a different setting is better:
  • When two or more connections are used on the same thread.

    For each web container thread used, a connection pool thread must be available. With asynchronous beans, more than one connection pool thread might be required per web request. As a result, make the connection pool maximum threads count higher than the web container thread pool.

  • When two or more connections are used for each web container thread.

    Set the web container thread pool to two times the maximum thread pool connections of the web container.

You can use the Tivoli® Performance Viewer to find the optimal number of connections in a pool. If the number of concurrent waiters is greater than 0, but the processor load is not close to 100%, consider increasing the connection pool size. If the Percent Used value is consistently low under normal workload, consider decreasing the number of connections in the pool.

Minimum connections

Specifies the minimum number of physical connections to maintain.

If the size of the connection pool is the same or smaller than the minimum connection pool size, the Unused timeout thread does not discard physical connections. However, the pool does not create connections solely to ensure that the minimum connection pool size is maintained. Also, if you set a value for Aged timeout, connections with an expired age are discarded, regardless of the minimum pool size setting.

For example, if the Minimum Connections value is set to 3, and one physical connection is created, the Unused timeout thread does not discard that connection. By the same token, the thread does not automatically create two additional physical connections to reach the Minimum Connections setting.

Information Value
Data type Integer
Default [8.5.5.9 or later]0

V8.5.5.8 and earlier: 1

Range 0 to max int

Reap time

Specifies the interval, in seconds, between runs of the pool maintenance thread.

For example, if Reap Time is set to 60, the pool maintenance thread runs every 60 seconds. The Reap Time interval affects the accuracy of the Unused timeout and Aged timeout settings. The smaller the interval, the greater the accuracy. If the pool maintenance thread is enabled, set the Reap Time value less than the values of Unused timeout and Aged timeout. When the pool maintenance thread runs, it discards any connections remaining unused for longer than the time value specified in Unused timeout, until it reaches the number of connections specified in Minimum Connections. The pool maintenance thread also discards any connections that remain active longer than the time value specified in Aged timeout.

The Reap Time interval also affects performance. Smaller intervals mean that the pool maintenance thread runs more often and degrades performance.

To disable the pool maintenance thread, set Reap Time to 0, or set both Unused timeout and Aged timeout to 0. The recommended way to disable the pool maintenance thread is to set Reap Time to 0, and Unused timeout and Aged timeout are ignored. However, if Unused Timeout and Aged Timeout are set to 0, the pool maintenance thread runs. Physical connections which timeout due to non-zero timeout values are discarded as well as those connections that reside in a used pool (or shared pool) because they have been held longer than the time interval set for Aged Timeout.

Information Value
Data type Integer
Units Seconds
Default 180
Range 0 to max int

Unused timeout

Specifies the interval in seconds after which an unused or idle connection is discarded.

Set the Unused timeout value to a value that is larger than the Reap timeout value for optimal performance. Unused physical connections are only discarded if the current number of connections exceeds the Minimum Connections setting. For example, if the unused timeout value is set to 120, and the pool maintenance thread is enabled (Reap Time is not 0), any physical connection that remains unused for 2 minutes is discarded.

The accuracy and performance of this timeout are affected by the Reap Time value. See Reap time for more information.

Information Value
Data type Integer
Units Seconds
Default 1800
Range 0 to max int

Aged timeout

Specifies the interval in seconds before a physical connection is discarded.

Setting Aged timeout to 0 supports active physical connections remaining in the pool indefinitely. Set the Aged timeout value to a value that is larger than the Reap timeout value for optimal performance.

For example, if the Aged timeout value is set to 1200, and the Reap Time value is not 0, any physical connection that remains in existence for 1200 seconds (20 minutes) is discarded from the pool. The only exception is if the connection is involved in a transaction when the aged timeout is reached, the application server will not discard the connection until after the transaction is completed and the connection is closed.

The accuracy and performance of this timeout are affected by the Reap Time value. See Reap time for more information.

Information Value
Data type Integer
Units Seconds
Default 0
Range 0 to max int

Purge policy

Specifies how to purge connections when a stale connection or fatal connection error is detected.

Valid values are EntirePool and FailingConnectionOnly.

Information Value
Data type String
Defaults EntirePool