Creating and updating 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 is optimized to connect to external databases via JDBC URLs.
When you deploy on Pega Cloud services environments, use JDBC URLs to define external database instances which your application uses to access and manage connections to that database.
To deploy on-premises or client-managed cloud systems, use JDBC connection pools. For more information, see Creating database instances for JDBC connection pools.
- In the header of Dev Studio, click .
- 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.
- Click Create and open.
- 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.
- In the How to connect list, click Use JDBC URL listed below.
- In the JDBC URL field, enter the JDBC URL.The format of the JDBC URL depends on the database platform. Precise syntax requirements and parameters vary depending on the server platform, database version, and JDBC client. Consult your database administrator for details.
- 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.
- 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.
- Click Save.
- Optional: To specify connection pool parameters and test connectivity to your database, click the Advanced tab.
- Leave the Connection count limit field blank. The field is reserved for future use.
- Leave the Failover options fields blank. The fields are reserved for future use.
- In the Connection pool parameters for HikariCP section,
specify your connection parameters for the JDBC URL database connection:
For more information, see the Hikari GitHub page for all HCP parameters.
- In the maximumConnectionTimeout field, enter the
connection timeout in milliseconds.If this time is exceeded without Pega Platform making a connection, Pega Platform logs a SQLException.
- Default: 30000 (30 seconds)
- Minimum: 250
- In the maximumPoolSize field, enter the maximum
size that Pega Platform allows the connection pool to
reach for both idle and in-use connections. If connection pools reach this size and do not contain any idle connections, Pega Platform then blocks calls to
getConnection*()for the time that you specify in the maximumConnectionTimeout parameter.- 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)
- In the maxLifetime field, enter the maximum
number of milliseconds that Pega Platform keeps an
unused connection in a pool. In-use connections retire only after Pega Platform closes them. Set the parameter several seconds shorter than any database-imposed lifetime limit.
- Default: 1800000 (30 minutes)
- Minimum: 30000 (30 seconds)
- When you set this parameter to 0, Pega Platform never retires a connection from a pool with the exception of connections that exceed the value for the idleTimeout parameter. For more information, see step 14.
- In the poolName field, enter a name for the
connection pool. Pega Platform uses this name in logs to identify pools and their configurations.
- Pega Platform auto-generates a name by default
- In the maximumConnectionTimeout field, enter the
connection timeout in milliseconds.
- In the Advanced parameters section, specify additional
parameters for the JDBC URL connection:
- In idleTimeout field, enter the maximum number
of milliseconds that a connection can sit idle in a connection pool. Pega Platform never retires connections before this timeout.
- Default: 600000 (10 minutes)
- Minimum: 10000 (10 seconds)
- When you set this parameter to 0, Pega Platform never removes connections from the pool.
When you set this parameter to 0, Pega Platform never removes connections from the pool. - In the minimumIdle field, enter the minimum
number of idle connections in a connection pool. Idle connections that fall below the maximumPoolSize value instruct Pega Platform to add additional connections to the pool. Leave the default value to permit a fixed size connection pool for maximum connectivity responsiveness.
- Default: Same as maximumPoolSize.
- If your database supports catalogs, in the
catalog field, define the metadata that contains
database definitions for objects, tables, indexes, and other
object.If you do not specify the catalog metadata, Pega Platform uses the driver default.
- Default: Uses the driver default if left unspecified.
- If your JDBC URL does not include the driver class name, in the driverClassName field, enter the name.
- In the leakDetectionThreshold field, enter the
number of milliseconds that a connection remains outside of the
connection pool before a potential leak is logged.
- Default: 0 (off by default)
- Minimum: 2000 (2 seconds)
- In the connectionTestQuery field, enter the
connection name that Pega Platform uses to validate a
live connection to the external database.
- In the initializationFailTimeout field, enter
the number of milliseconds Pega Platform tries to
acquire the first connection with an initialized connection pool before
throwing a timeout exception. Pega Platform does not start the connection pool if the first connection fails.This parameter causes the following system actions:
- When you set the parameter to 0, Pega Platform tries to obtain a connection.
- If Pega Platform obtains a connection, but fails validation, Pega Platform does not initialize the connection pool.
- If Pega Platform does not obtain a connection, Pega Platform still initializes the pool, but later connection attempts might fail.
- When you set the parameter to a value that is less than 0 (-x), Pega Platform bypasses initial connection attempts, and the connection pool immediately starts.
- When you set the parameter to 0, Pega Platform tries to obtain a connection.
- In the connectionInitSql field, enter an SQL statement that Pega Platform runs after creating a new connection before adding that connection to the pool.
- In the validationTimeout field, enter the
maximum duration in milliseconds that Pega Platform
sends a heartbeat to validate the connection and determine if the
connection is still active.
- Default: 5000 (5 seconds)
- Minimum: 250 (.25 seconds)
- In idleTimeout field, enter the maximum number
of milliseconds that a connection can sit idle in a connection pool.
- Optional: To specify the names of other database instances that views in this database
can reach, on the Advanced tab, define the database
parameters:
- In the Database Name list, click the Add item icon.
- 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.
- Click Save.
- Optional: To test the database connection, on the Database tab,
click Test connection.This test does not test the administrative user that you specify.
- Diagnostic information appears in a new window if the test fails.
- Modify the database instance until the test succeeds.
- Deleting dynamic system settings connection parameters
After you upgrade to Pega Platform version 8.6 or later, delete your previous connection parameters that you specified by using dynamic system settings (DSS) or the prconfig file, to avoid parameter overrides.
- Deleting connection parameters in the prconfig file
For Pega Platform versions that are earlier than 8.6, if you modified the connection parameters in your prconfig file, delete the parameters from the file to avoid parameter overrides.
Previous topic Creating database instances for prconfig references Next topic Deleting dynamic system settings connection parameters