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 from your Pega Cloud environment

Updated on February 25, 2022

This content applies only to Pega Cloud environments

You can connect your Pega Cloud® Services environments 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:

  • Access or configure an existing or new database.
  • Configure a target database and select the output formats for the manifest.

To make an external database connection for on-premises or client-managed cloud systems, see Connecting to an external database.

Before you begin

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

Using a JDBC URL for an external database instance

Caution: 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.

Specify a JDBC URL to create a database data instance for Pega Cloud 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 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.

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

        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. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us