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.

Connecting to an external database

Updated on January 19, 2022

This content applies only to On-premises and Client-managed cloud environments

You can connect Pega Platform™ to any supported external database. External databases differ from the database that stores your Pega Platform application information. You configure external database connections for Pega Platform to accomplish the following items:

  • You have an existing or a new database for Pega Platform to access or configure.
  • You want to configure a target database and select the output formats for the manifest.

To make an external database connection using Pega Cloud® Services, see Connecting to an external database from your Pega Cloud environment.

Before you begin

  • If your external database uses Java Database Connectivity (JDBC) connection pools, ensure that your application server supports JNDI.
  • Use a database network connection to which Pega Platform can communicate.
  • If you are connecting to an external database using a JDBC URL that differs from the database hosting Pega Rules, 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 details, see Defining the Database Driver below.
    For details about database support and your driver Java compatibility, see the Platform Support Guide.

(Recommended) Using JDBC connection pools for application server-managed database connections

Specify a JDBC connection pool with a JNDI name to reference a database data instance for Pega Platform to access.

  1. In the navigation header of Dev Studio, click Create > SysAdmin > Database to create a new database connection.

  2. On the Create Database page, enter a Short description and a Database name for your new database connection data instance.

  3. Click Create and open. The Edit Database page appears.
  4. On the Edit Database page, enter the following information:

    1. Optional: Select an Integration system to associate with this database.  Integration systems organize the rules for integration connectors, data types, and data page sources.

    2. Under How to connect, click Use JDBC Connection Pool.

    3. In the JNDI name field, enter the name of a JNDI data source that has read and update permission.

      Note: Do not enter any further credentials or user information for the JDNI fields.  Your data source already contains the required information for this connection.
    4. Click Save.

  5. Click Test database connection at the bottom of page to ensure connectivity.

For more information, see: Creating a database instance for a JDBC connection pool.

Using JDBC URL for Pega-managed database connections 

Attention:

External databases do not release connections when not in use. Use Dynamic System Settings to edit the minimum value of connections opened per node (20). For details, see Modifying connection pools.

Define your database driver and JDBC URL to create a database data instance for Pega Platform to access. If the database to which you are connecting is the same type of database used by Pega Rules, proceed to Defining the JDBC URL.

Defining the Database Driver

  1. In the navigation header of Dev Studio, click Configure > Application > Distribution > Import to launch the wizard importing the downloaded JDBC driver.

  2. After importing the the JDBC driver, in the navigation header of Dev studio, click Create > SysAdmin > Dynamic System Settings to create a Dynamic System Setting for the JDBC driver.

  3. On the Create Dynamic System Settings page, enter the following required values:

    • Short description: prconfig/database/drivers/default
    • Owning Ruleset: Pega-Engine
    • Setting Purpose: prconfig/database/drivers/default
  4. Click Create and open. The Edit Dynamic System Settings page appears.

  5. In the Value field, copy the class name of the JDBC driver. Add multiple drivers using semi-colons to separate names as needed.
     Example:

    • For Oracle: enter oracle.jdbc.OracleDriver
    • For Microsoft SQL Server: enter com.microsoft.sqlserver.jdbc.SQLServerDriver
    • For IBM DB2: enter com.ibm.db2.jcc.DB2Driver
    • For postgreSQL: enter org.postgresql.Driver
  6. Click Save.
  7. Manually restart each node.
  8. After the nodes restart, define the external database JDBC URL.

For more information, see: Defining the database driver.

Defining the JDBC URL

  1. In the navigation header of Dev Studio, click Create > SysAdmin > Database to create a new database connection.  

  2. On the Create Database page, enter a Short description and a Database name for the data instance.

  3. Click Create and open. The Edit Database page appears.
  4. On the Edit Database page, enter the following information:

    1. Optional: Select an Integration system to associate with this database.  Integration systems organize the rules for integration connectors, data types, and data page sources.
    2. Under How to connect, select use JDBC URL listed below

    3. In the JDBC definition section, in the JDBC URL field, enter the platform-specific URL for the external database.
      Example:

      • Oracle:    jdbc:oracle:thin:@serverName:​1521:​service-name-or-SID

      • Microsoft SQL Server:     jdbc:sqlserver://servername:1433;​DatabaseName=dbname;​SelectMethod=cursor;​SendStringParametersAsUnicode=false

      • IBM Db2:     jdbc:db2://serverName:port/dbName:​fullyMaterializeLobData=true;​fullyMaterializeInputStreams=true;​progressiveStreaming=2;​useJDBC4ColumnNameAndLabelSemantics=2;

      • PostgreSQL:     jdbc:postgresql:​//serverName:5432/dbName

    4. In the Authentication section, add the required credentials to complete the external database connection.

      1. To add standard users, in the Username field, enter the name of a database user who has read and update permission, and in the Password field, enter the password for that user.

        Specify a user that is capable of accepting unqualified table names and converting 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.

      2. Optional: To add users with Administrator permissions, in the Admin username field, enter the name of a database user who has permission to alter and create tables, and in the Admin password field, enter the password for that user.

        Specify a user that is capable of to configuring tables that extend the data schema. The admin user is used for platform-generated schema changes, property optimization, and circumstance definitions.

      3. Optional: To add users with read-only permissions, in the Read-only username field, enter the name of a database user who has read-only permission, and in the Read-only password field, enter the password for that user.
        Specify a user that is capable of querying tables to pull database information, but cannot update, delete, change schemas, or otherwise interact with a database.
    5. Click Save.

  5. Click Test database connection at the bottom of the page to ensure connectivity.

For more information, see: Creating a database instance for a JDBC URL.

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.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us