Configuring connection pools for an external database

External database connections through a Java Database Connectivity (JDBC) URL are managed by Pega Platform and use connection pools to handle requestor traffic. You can modify the default connection pools to limit or increase connections and their timeout value that is created for each database user to optimize connectivity for your environment.

Note: This task applies to databases that use connection pooling that are managed by Pega Platform. This task does not apply to databases that use Java Naming Directory Interface (JNDI) data sources. For more information about creating an external database connection, see Creating database instances for JDBC URLs.
Before you begin: 

Gather the following information:

  • The name of the database that you created for an external database connection.
  • Standard user credentials created on the external database.
  • Optional: Administrator and read-only user credentials if they have been configured on the external database.

The pool keeps idle connections ready. The system creates additional connections when all existing connections are busy until they reach the connection pool size value. When a requestor arrives and the maximum number of connections are busy, the requestor waits until reaching the connection timeout value. Database connections remain open until Pega Platform stops running.

Connection pool sizes and the connection timeout 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: 300 seconds

    The timeout value applies to all connection pools on this node.

  1. In the navigation pane of Dev Studio, click App.
  2. In the header of Dev Studio, click Create > SysAdmin > Dynamic System Settings.
  3. In the dynamic system settings Short Description field, enter a summary of 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:
    1. Create dynamic system settings for each database user connection pool by entering the corresponding key strings.
      Use 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
    2. Create a dynamic system setting for the connection timeout in seconds by entering the following key string:

      prconfig/database/databases/<database name>/MaxConnectionTime

  6. Click Create.
  7. 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 pools that can be active for a user type.
    • For the connection timeout value dynamic system setting, enter the number of seconds that an idle requestor remains open.
  8. Click Save.
  9. To modify other connection pools or the time-out threshold for other users, repeat step 1 through 8.
  10. For on-premises clients, restart the node:
    1. For Pega Cloud Services clients, log in to your My Support Portal account.
    2. On the Support Request tab, file a cloud service request for applicable node restarts in your environment by clicking Create.
    CAUTION:
    Do not set connection limits too low to avoid deadlocks and poor response time. You can set a threshold for PEGA0026 alerts to detect long waits.