Skip to main content

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

Configuring connectivity parameters for an external Pega Platform database

Updated on August 25, 2021

External database connections through a Java Database Connectivity (JDBC) URL are managed by Pega Platform and use connection pools to handle connection traffic. You can modify the default parameters of the connection pools to limit or increase connections, edit their timeout value, and create a new schema name for each database user to optimize connectivity for your external database connection. You can also request to add additional connectivity parameters specific to your external database vendor through My Support Portal.

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 and updating external database instances with 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 connection request arrives at the external database and the maximum number of connections are busy, the connection waits until reaching the connection timeout value before throwing a timeout error. Database connections remain open until Pega Platform stops running. A connection that leaves the pool stays out until reaching the leak detection threshold value, upon which a log error appears in connection logging.

Pega Cloud clients can add additional connection parameters to their external database connection by making a request that specifies which database-specific connection parameters you want to configure. Contact your regional Pega Support representative by using the Support Requests tab in My Support Portal. Pega Cloud Services creates the connection parameter in your instance of Pega Platform that initiates upon restart of your Pega Cloud environment. For more information about parameters for your external database, refer to your database documentation.

Connection pool sizes, connection timeouts, leak detection threshold 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: 3000 milliseconds

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

  • Leak detection threshold: 0 milliseconds (off by default).

    The amount of time a connection remains outside of the connection pool before Pega Platform logs a potential leak.

  • Database schema: Name of the database schema.

    The name of the default database schema to which you want to add your database tables.

  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 in seconds by entering the following key string:

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

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

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

    4. Create a dynamic system setting for the default schema by entering the following key string:

      prconfig/database/databases/<database name>/defaultSchema/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 connections 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 a timeout error.
      • Minimum value: 250 (.25 seconds)
    • 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)
    • For the default schema name, enter a name of the schema that contains the tables associated with this external database connection.
  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. Select New request.
    3. File a cloud service request for applicable node restarts in your environment.
    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.
  • Previous topic Creating and updating external database instances with JDBC URLs
  • Next topic Creating database instances for JDBC connection pools

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