Close popover

Table of Contents

Creating external database instances with JDBC URLs

Specify a JDBC URL to create a database data instance so that Pega Platform can access a supported external database.

Pega Platform manages the database connections you create by specifying a JDBC URL. As best practice, when deploying on Pega Cloud Services environments, use JDBC URLs to define database instances. When deploying on-premises or using client-managed cloud systems, use JDBC connection pools. For more information, see Creating database instances for JDBC connection pools.

  • 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:
    • select on sys.v_$parameter
    • alter session

    For additional database privilege requirements, see step 8a.

  • 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.
  • Pega Cloud only: External database instances require a VPN connection. Ensure that the CIDR range added to a list of allowed connections on the VPN for your VPC includes the network for your database endpoints.

By default, one base user per node creates a default connection pool of 20, and other users (admin and read-only) create 5. External databases do not release connections when not in use. For more information for configuring database connection pools created on each node, see Configuring connectivity parameters for an external Pega Platform database.
  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 Create SysAdmin Database .

  3. Enter a short description, and in the Database field, enter a name for the additional database.

    The database name is case-sensitive.

  4. Click Create and open. The Edit <YourNewDatabaseName> Database page appears.

  5. Optional:

    To indicate the system of record, in the Integration system field, press the Down arrow key and select the name of the integration system 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 URL listed below.

  7. In the JDBC URL field, enter the JDBC URL.

    The format of the JDBC URL depends on the database platform. Precise syntax requirements vary depending on the server platform, database version, and JDBC client. Additional parameters may also be required. Consult your database administrator for details. The following table shows some examples of JDBC URLs.

    Database URL
    Oracle jdbc:oracle:thin:@serverName:​1521:​service-name-or-SID
    Microsoft SQL Server jdbc:sqlserver://127.0.0.1:1433;​DatabaseName=database;​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
  8. In the Authentication section, add the required and any optional credentials for 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.

      The admin user is used to configure tables that extend the Pega data schema. The admin user is used for platform-generated schema changes, property optimization, Query Inspector, Query Runner, Schema Tools, 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.

  9. Click Save.

  10. Optional:

    Click the Advanced tab.

  11. Leave the Connection count limit field blank. It is reserved for future use.

  12. Leave the Failover options fields blank. They are reserved for future use.

  13. Optional:

    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.

  14. Optional:

    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.

  15. Optional:

    On the Advanced tab, specify the names of other database instances that should be reachable by views in this database.

    1. Under the Database Name list, click the Add item icon.

    2. In the Database Name field, press the Down arrow key, and select the name of a database instance that views in the external database need to access.

    This database instance describes the EXTERNAL1 database. Your Pega application needs to access a view in EXTERNAL1 that joins data from the DATA1 and DATA2 databases. Do the following steps:
    • Define database instances for DATA1 and DATA2.
    • On the database instance for EXTERNAL1, list DATA1 and DATA2 as other databases.
  16. Click Save.

  17. To test the database connection, on the Database tab, click Test connection.

    • If the test fails, diagnostic information appears in a new window. Modify the database instance until the test succeeds.
    • This test does not test the administrative user, if any, that you might have specified.

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

  • Database data instances

    You can configure Pega Platform to connect to databases in addition to the PegaRULES and PegaDATA databases. After you install a database driver and define a database data instance, you can create additional rules, such as integration connectors and Connect SQL rules, to access the database.

  • Creating database data instances

    Create a database data instance so that Pega Platform can access a database in addition to PegaRULES and PegaDATA. To improve performance, you can create Pega classes and data types in a separate database, or use a separate database for Prediction Studio or for running reports. You can also create a database instance to access an external database.

  • Integration systems

    An integration system is a system that can be used when creating data types, integration connectors, and databases to indicate the system of record. Integration systems make system configuration easier because they are reusable and selectable when creating data types, integration connectors, and databases.

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