Close popover

Table of Contents

Configuring connectivity parameters for an external Pega Platform database

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.

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 external database instances with JDBC URLs.

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 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

    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.

    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.

  • Configuring read-only database access for Query Runner

    For query results to be returned when testing queries on the Query Runner landing page, you must have configured read-only user credentials for the database. Use the following procedure for configuring read-only user credentials for PegaRULES and PegaDATA databases. If you are using an external database, see Accessing database administration opera

  • Managing database performance

    You can make changes to database tables to support your Pega Platform needs. Because Data-Admin-DB-Table and Data-Admin-DB-Name instances control how the Pega Platform finds objects within the Pega Platform database, changes to the database table structure must be coordinated with changes to these data instances.

  • Managing your Pega Platform database

    The Pega Platform relational database holds the rules, data instances, work items, history, and other concrete objects from the internal classes of your Pega Platform system. External classes, by definition, correspond to tables in other databases and are not part of the Pega Platform database.

  • Configuring dynamic system settings

    As a best practice, set system configuration settings by using dynamic system settings data instances. For example, you can use a dynamic system settings to configure which fields are available in full-text search. Dynamic system settings are stored in the Pega Platform database and are used by all nodes that share that database.

Suggest Edit

Have a question? Get answers now.

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