Skip to main content

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

Creating database instances for JDBC connection pools

Updated on July 8, 2022

Specify a Java Naming and Directory Interface (JNDI) name to create a database data instance so that Pega Platform can access a database via a JDBC connection pool.

Before you begin: This topic only applies to on-premises and client-managed cloud deployments. Pega Cloud Services environments do not support using JNDI.
  • If you are connecting to an Oracle database, the users that you use to connect to the database must receive the following privileges from an administrator:

    For additional database privilege requirements, see step 8a.

  • The application server that is running Pega Platform manages database connections created by specifying JDBC connection pools for improved connection configuration ability. As best practice, when deploying on-premises or using client-managed cloud systems, use JDBC connection pools to define database instances. When deploying on Pega Cloud Services environments, use JDBC URLs. For more information, see Creating and updating external database instances with JDBC URLs.

  • If you are connecting to an external database that differs from the internal PostgreSQL Pega Platform database, you must define the driver before making the database connection. To do so, you must download a JDBC driver version compatible with the Java version running on the Pega Platform application server, then define a new dynamic system setting for the driver. For more information, see Defining the database driver. For details about database support and your driver's Java compatibility, see the Platform Support Guide.

Connection pool configurations using JNDI depend on the version of the application server and the database platform that Pega Platform uses. Consult your database vendor documentation for more information.

  1. If the database platform of the additional database differs from the database platform of Pega Platform, or does not use postgresSQL, define Pega Platform the database driver. For more information, see Defining the database driver.
  2. In the header of Dev Studio, click CreateSysAdminDatabase.
  3. In the Create database tab, enter a short description, and in the Database field, enter a name for the external database.
    The database name is case-sensitive.
  4. Click Create and open.
  5. Optional: To indicate the system of record, in the Integration system field, press the Down arrow key, and then select the name of the integration system that you want to associate with this database.
    The value that you select is for informational purposes only, and does not affect the behavior of the database instance. You can use this value to organize rules for integration connectors, data types, and sources for data pages.
  6. In the How to connect list, click Use JDBC Connection Pool.
  7. Enter the JNDI names that have update permission, administrative permission, and read-only permission the data source.
    JNDI names correspond to the credentials that you enter in the next step. Note: Most use cases require a JNDI name only to pull information from the data source (step a)You should only complete the other fields (steps 7b through 8c) if you want to override the fields and credentials that Pega Platform imports from the data source. If you do not want to override the imported fields and credentials, proceed to step 9.
    1. In the JNDI name field, enter the name of a JNDI data source that has read and update permission.
    2. Optional: In the Admin JNDI name field, enter the name of a JNDI data source that has permission to alter and create tables.
    3. Optional: In the Read-only JNDI name field, enter the name of a JNDI data source that has read-only permission.
  8. In the Authentication section, add the required and optional credentials for the external database connection:
    • To add standard users, in the Username field, enter the name of a database user who has permissions to read and update the database, and then, in the Password field, enter the password for that user.

      Specify a user who can accept unqualified table names and convert them to fully qualified table names. If this database is to be accessed through Connect SQL rules, confirm that this database user has search, update, delete, and other permissions that support the SQL statements in those rules, and that this database is the default database of the user.

    • To add users with administrator permissions, in the Admin username field, enter the name of a database user who has permissions to alter and create tables, and then, in the Admin password field, enter the password for that user.

      The administrator user can configure tables that extend the Pega data schema, including schema changes that are generated by Pega Platform, property optimization, Query Inspector, Query Runner, Schema Tools, and circumstance definitions.

    • To add users with read-only permissions, in the Read-only username field, enter the name of a database user who has read-only permissions, and then, in the Read-only password field, enter the password for that user.
  9. Click Save.
  10. Optional: Click the Advanced tab.
  11. Leave the Failover options fields blank.
    The fields are reserved for future use.
  12. To specify a proxy class for determining access privileges to the Schema Tools, Query Inspector, and Query Runner landing pages, in the Proxyclass name field, enter the proxy class.

    The proxyclass is used with the read-only user that you define on the Database tab.

  13. If this database is used for tables that you have configured for use by Pega Platform and the BLOB user-defined function is installed on the database, select the Use UDF for property lookup check box for best performance of Pega:Lookup tag references.
  14. Optional: To specify the names of other database instances that views in this database can reach, on the Advanced tab, define the database parameters:
    1. In the Database Name list, click the Add item icon.
    2. In the Database Name field, press the Down arrow key, and then select the name of a database instance that views in the external database need to access.
    For example: This database instance describes the EXTERNAL1 database. To configure your application to access a view in EXTERNAL1 that joins data from the DATA1 and DATA2 databases, define database instances for DATA1 and DATA2, and then list DATA1 and DATA2 as other databases on the database instance for EXTERNAL1,
  15. Click Save.
  16. Optional: To test the database connection, on the Database tab, click Test connection.
    This test does not test the administrative user that you specify.
    1. Diagnostic information appears in a new window if the test fails.
    2. Modify the database instance until the test succeeds.

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