Skip to main content

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

This content has been archived and is no longer being updated.

Links may not function; however, this content may be relevant to outdated versions of the product.

Configuring connectivity to the Pega Platform database

Updated on April 5, 2022

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. Connections that remain out of the pool for the duration of the leak detection value log a connection leak error. 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.

  • Leak detection threshold: 0 milliseconds (off)
  1. In the navigation pane of Dev Studio, click App.
  2. In the header of Dev Studio, click CreateSysAdminDynamic 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 by entering the following key string:

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

    3. Create a dynamic system setting for the leak detection threshold by entering the following key string:

      prconfig/database/databases/<database name>/leakDetectionThreshold/default

  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.
    • For the leak detection threshold 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)
  8. Click Save.
  9. To modify other connection pools or the timeout 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.

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