Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Modifying connection pools

Updated on September 13, 2021


This content applies to On-premises, Client-managed cloud and Pega Cloud environments

External database connections through a Java Database Connectivity (JDBC) URL are managed by Pega Platform™ and use connection pools to handle connection traffic. Database connections remain open until Pega Platform stops running. On-premises or Pega Cloud clients can optimize the database connectivity for your environment by using dynamic system settings in Pega Platform to modify the connection pools settings for your database connection. Customizations include the ability to limit or increase connection pool size, timeout values, and leak detection threshold. As an alternative, clients with on-premises systems can accomplish the same goal by modifying the appropriate keystring values in the prconfig.xml file.

For more information about creating Pega-managed external database connections through a JDBC URL and referencing user types, see Connecting to an external database.

Connection pool sizes, connection timeout, and leak detection have the following default values:

  • Connection pools:
    • Standard user – 20 connections
    • Administrator – 5 connections (if an administrator is configured on the external database)
    • Read-only user – 5 connections (if a read-only user is configured on the external database)
  • Connection timeout value: 30000 milliseconds (30 seconds)
    The timeout value applies to all connections for this node.
  • Leak detection threshold: 0 milliseconds (off by default).

Before you begin

Gather the following information:

  • The name of the database that you created for an external database connection (see Using a JDBC URL for an external database connection).
  • Standard user credentials created on the external database.
  • Optional: Admin user and read-only user credentials if they have been configured on the external database.

Using dynamic system settings to modify connection pools

To create a customized dynamic system setting for your database connection pools, do the following:

  1. In the navigation pane of Dev studio, click App.
  2. Right-click your application, and then select New > SysAdmin > Dynamic System Settings.
  3. In the dynamic system settings Short Description field, enter a summary for the new setting.
  4. In the Owning Ruleset field, enter Pega-Engine
  5. In the Setting Purpose field, enter the key string for the database connection size and timeout value:
  • Create dynamic system settings for each database user connection pool by entering the following key strings:
    • Standard user: prconfig/database/databases/<database name>/connectionPoolSize/default
    • Administrator: prconfig/database/databases/<database name>/connectionPoolSize/admin/default
    • Read-only user: prconfig/database/databases/<database name>/connectionPoolSize/readonly/default
  • Create a dynamic system setting for the connection timeout, in miliseconds, by entering the following key string:
    • Timeout value: prconfig/database/databases/<database name>/maxConnectionsTimeout/default
  • Create a dynamic system setting for the leak detection threshold by entering the following key string:
    • Leak detection value: prconfig/database/databases/<database name>/leakDetectionThreshold/default
  1. Click Create
  2. On the Settings tab, in the Value field, enter the following values:
    • For the connection pool size dynamic system settings, enter the number of connection in the pool for a user type.
    • For the connection timeout value dynamic system setting, enter the number of milliseconds that Pega Platform waits to receive a connection from the pool before throwing an timeout error.
      • Minimum value: 250 (.25seconds)
    • For the leak detection dynamic system setting, enter the number of milliseconds a connection can remain out of the pool before logging a leak error message. The value must belong to the following set of integers:
      • 0 (no leak detection) 
      • Greater than or equal to 2000 (2 seconds)
  3. Click Save.
  4. Optional: To modify other connection pools or the connection timeout, repeat steps 1 through 7.
  5. Depending on your deployment type, complete the appropriate step:
    • For on-premises clients, restart the node.
    • For Pega Cloud® Services clients:
      1. Log in to your My Support Portal account.
      2. Select New request.
      3. File a cloud service request for applicable node restarts in your environment.

Editing the prconfig file to modify connection pools

Note: Pega Cloud Services customers cannot modify connection pool sizes by editing the prconfig.xml file.

On-premises and client-managed cloud clients can modify connection pool sizes by editing the prconfig.xml file for their Pega Platform web application. If you edit the prconfig.xml file in one node, you must make the same changes in the prconfig.xml file for all other nodes. 

To edit the prconfig.xml file for your Pega Platform web application, do the following:

  1. Extract the prconfigxml file. For more information, see Changing node settings by modifying the prconfig.xml file.
  2. Open the prconfig.xml in an XML or text editor.
  3. Modify the following settings:
  1. Modify the connection pool size (value="x") for the standard user, administrator, and read-only user by editing the following variables:
    • Standard user: <env name="database/databases/<database name>/connectionPoolSize"value="20"/>
    • Administrator: <env name="database/databases/<database name>/admin/connectionPoolSize"value="5"/>
    • Read-only: <env name="database/databases/<database name>/readonly/connectionPoolSize"value="5"/>
  2. Modify the connection timeout, in milliseconds (value="x"), through the following variable:
    Timeout: <env name="database/databases/<database name>/maxConnectionsTimeout"value="30"/>
  3. Modify the leak detection threshold, in milliseconds (value = "x"), through the following variable:
    Leak detection value: <env name="database/databases/<database name>/leakDetectionThreshold"value="0"/>
  1. Save and close the updated prconfig.xml file.
  2. Repeat steps 1 through 4 to duplicate edits for all other prconfig.xml files within your environment.
  3. Restart the environment.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us