Database form - Completing the Database tab

Complete this tab to specify database connection information. You can specify the connection details or you can inherit the connection details from an existing connection. After you complete and save the form, click Test Connection to confirm database connectivity.

External database configuration

If this instance is to connect to an external database, you must ensure that the driver files for the type of the external database are available to Pega Platform :

  1. Make sure the appropriate driver JAR file in on the Java class path, for example ojdbc6.jar for Oracle, sqljdbc4.jar for MS SQL, or db2jcc.jar for Db2. See your database vendor documentation to confirm the appropriate driver file.
  2. Add the database/drivers setting to the prconfig.xml file. The driver cannot be specified using a Dynamic System Setting. The value for the setting is a comma-separated list of driver Java class names.

Database

Select Specify connection details to enter connection details for this database instance. Select Inherit from existing connection to use the same connection details as an existing database instance.

Connection details field descriptions

These fields are displayed when you select Specify connection details in the Database section.

Field Description
Database  
How to Connect Select one of the following options.
  • Use configuration in preferences to refer to a database/databases/pegarules element in the prconfig.xml file that defines the location, TCP/IP port, account name and password of a relational database.
  • Use JDBC Connection Pool to use a connection pool defined by a Java Naming and Directory Interface (JNDI) facility. Complete the JNDI Name field.
  • Use JDBC URL listed below to use a Universal Resource Locator to find the Java Database Connectivity information. Complete the JDBC URL field.
  • Use Couchbase cluster configuration listed below to connect to a NoSQL Couchbase database.
  • Use Cassandra cluster configuration listed below to connect to a NoSQL Apache Cassandra database.
Note: The Use JDBC Connection Pool approach offers the most flexibility to accommodate later changes in the systems environment and is a best practice. In contrast, the JDBC URL listed below approach may require updates to this form when system details change.

Pega Platform may open more than one connection to a database. When using WebSphere's pooled connection facility, a general guideline for production systems is to set the maximum number of connections for the PegaRULES database to about one-third to one-fifth of the number of simultaneous requestors (and adjust the PegaRULES database settings to allow the same number of connections. Don't forget to count listeners and agents as requestors.

Use configuration in preferences

For example, connection to a Microsoft SQL Server database can be defined in the prconfig.xml file as: 


                  <env name="database/databases/Northwind/url" value= "jdbc:microsoft:sqlserver://shelpnt:1433; SelectMethod=cursor"/> 
                  <env name="databases/databases/Northwind/userName" value="Smith" /> 
                  <env name="database/databases/Northwind/password" value="password" /> 
                  <env name="database/databases/Northwind/maxConnections" value="3" />

In this example, the database name is Northwind and the user name (account) is Smith with password password . The database is located on the server SHELPNT using TCP/IP port 1433 .

Pega Platform may open more than one database connection with this user name. To provide good performance, the system creates a pool of connections over time. (This internal connection pooling is an alternative to facilities provided by WebSphere or WebLogic.).

Note: The maxConnections entry is optional. For the PegaRULES database, if you use this entry, set the value to 2 or more. See Limiting connections to the PegaRULES database.

Account and password security

If you choose Use JDBC URL below or Use JDBC Connection Pool for the How to Connect field, you can later delete any elements of the prconfig.xml file that contain the account and password for a database.

If you choose Use configuration in preferences, the database password must remain in the prconfig.xml file, but you can encrypt this password in that file through a special advanced configuration.

JDBC Definition  
JDBC URL This field appears only when you select Use JDBC URL below for the How to Connect field.

Enter the full URL. For example:

Database URL
SQL Server 2000 jdbc:microsoft:sqlserver:// 127.0.0.1:1433 ; DatabaseName=Northwind;SelectMethod=cursor
SQL Server 2005 jdbc:sqlserver:// 127.0.0.1:1433 ; DatabaseName=Northwind;SelectMethod=cursor
Oracle jdbc:oracle:thin:@// serverName : 1521 / service-name-or-SID
IBM Db2 jdbc:db2: //serverName:port/dbName :fullyMaterializeLobData=true; fullyMaterializeInputStreams=true; progressiveStreaming=2;progressiveLocators=2; useJDBC4ColumnNameAndLabelSemantics=false;
Note: This example code string has been manually shortened to better fit within the space provided.
Sybase jdbc:sybase: 127.0.0.1

where 127.0.0.1 is the node name or IP address of the server hosting the database, and 1433 or 1521 is the TCP/IP port number for database access.

Note: Precise syntax requirements vary depending on server platform, database version, and JDBC client; additional parameters may be required. Consult your database administrator (DBA) for details.

If this Data-Admin-DB-Name instance is to connect to the PegaRULES database, consult the Installation Guide for your platform. If your PegaRULES database is hosted by Oracle 9, the Type 2 (OCI or thick client) driver is required; the thin client (Type 4) works with Oracle 10g.

Sybase databases are accessible only through Connect SQL rules. Sybase is not supported as a host for the PegaRULES database.

Do not place any spaces or other extraneous characters before or after the JDBC URL value.
JDBC Datasource  
JNDI Name This field appears only when you select Use JDB Connection Pool for the How to Connect field.

Enter the JNDI name of the data source for your connection pool. The procedure for defining a connection pool depends on two factors:

  • Which application server you use (Apache Tomcat, Oracle, IBM WebSphere, or Oracle WebLogic, for examples)
  • Which database vendor and version is in use (Oracle, Microsoft SQL Server, IBM Db2, IBM UDB and others)
Note: If during installation of Pega Platform the installer specified a JDBC Datasource for connecting to the PegaRULES database, the username and password for that data source may appear in the prconfig.xml file. These two entries are not necessary; you can delete them from the prconfig.xml file. During startup, Pega Platform obtains the username and password for the database from authentication facilities of Tomcat (or your hosting application server).
Admin JNDI Name Optional. Leave blank unless (1) this database name instance is to access the PegaRULES database using JNDI, (2) the primary database user account that you entered in the JNDI name field above does not have the ALTER TABLE and CREATE TABLE capabilities, and you want developers to have any of these capabilities:

(Some of these capabilities have additional prerequisites.)

Identify a second, distinct data source for the JNDI location (typically jdbc/AdminPegaRULES) that defines a PegaRULES database connection for which the account does have both the ALTER TABLE and CREATE TABLE capabilities. (This ordinarily is distinct from database account used by most application users, who only insert, update, and delete rows). Consult the Installation Guide (for your platform) for additional information on this field.

Alternatively, you can specify the username and password in the prconfig.xml file.
  For any database specified by a JDBC URL, its driver class must be included in the (semicolon-delimited) list of driver classes specified by the prconfig.xml setting "database/drivers".
Read-only JNDI name Optional. If you are using an external database and want to use the Schema Tools, Query Inspector, or Query Runner landing pages for performing database operations, enter the read-only JNDI name.

Enter the proxy class to use for determining access privileges for this account in the Proxyclass name field on the Advanced tab.

Authentication  
Username Optional. Enter the user or account name for this database, if required. Use a database 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 ( Rule-Connect-SQL rule type), confirm that this database user has search, update, delete, and other capabilities that support the SQL statements in those rules, and that this database is the default database of the user.

Password Optional. If the database account requires a password, enter the password. If this field is blank, the system expects to obtain a password from a text file named pegarules.keyring , which can contain this password in encrypted form.

For more information on the keyring approach, which requires familiarity with encryption technologies, contact Global Customer Support.
Admin Username Optional. The Admin User Name and Admin Password field provide an alternative way to specify a PegaRULES database account for specific capabilities.

Leave blank unless (1) this database name instance is to access the PegaRULES database using JNDI, (2) the primary database user account identified through does not have the ALTER TABLE and CREATE TABLE capabilities, and you want developers to have any of these capabilities:

Identify a PegaRULES database account (referenced by the Admin JNDI Name field) that has the ALTER TABLE and CREATE TABLE capabilities. (This account ordinarily is distinct from database account used by most application users, who only insert, update, and delete rows in the database).

Alternatively, you can specify the username and password in the prconfig.xml file.

Consult the Installation Guide (for your platform) for additional information on this field.

Admin Password Optional. Leave blank unless you have supplied an Admin Username value.

Enter a password for the database account identified in the Admin Username field.
Read-only Username Optional. If you are using an external database and want to use the Schema Tools, Query Inspector, or Query Runner landing pages for performing database operations, enter the username of the account to use.

Enter the proxy class to use for determining access privileges for this account in the Proxyclass name field on the Advanced tab.

Read-only Password Optional. Enter a password for the database account identified in the Readonly Username field.
Couchbase Cluster  
Bucket Name Enter the name of the bucket used by the Couchbase Server database to save your data.
Bucket Password Enter the password for accessing the bucket.
Couchbase timeout (global) Enter the connection timeout, in milliseconds.
Cassandra Hostnames and Ports  
Hostname Enter the host name or IP address of a node in the cluster.
Port Enter the port number to use to connect to the database.
Test Connection  
Test Connection After you complete and save the form, click to test connectivity to the database. If the test fails, diagnostic information appears in a new window. (This test does not try the alternate account to the PegaRULES database, if any, specified in the Admin Username and Admin Password fields).

See PDN article Troubleshooting JDBC problems with tools from Pegasystems and others for advice on researching JDBC issues.

Existing connection inheritance

In the Use connection details of field, select the database instance whose connection details you want to use. Chained connections are not allowed. Only database instances that do not inherit from an existing connection are available in the dropdown list.