If you are a Managed Hosting customer, this topic doesn't apply to you.

Establishing a connection from the application container to the database server is time consuming. As a result, JDBC connection pooling is widely used in Blackboard Learn.

Blackboard Learn has multiple schemas that are used for a variety of functions. The core schema is BBLEARN (legacy: BB_BB60), which is where the bulk of key database objects and access reside. The BBLEARN_ADMIN schema is an administrative schema accessed by the start-up utilities and some administrative functions. The BBLEARN_STATS (legacy: BB_BB60_STATS) schema is an operational data store that is used for reporting to ease demand on BBLEARN (legacy: BB_BB60). BBLEARN_STATS (legacy: BB_BB60_STATS) is not accessible using the Blackboard Learn User Interface (UI).

Connections from the Apache™ Tomcat to the database are managed using parameters in the bb-config.properties file.

Database parameters in bb-config.properties

The following table provides recommended settings for the four key bbconfig.database parameters. For steps to edit the bb-config.properties file, see bb-config.properties File.

Database Parameter Recommended Settings
Parameter Name Description Recommended Setting
bbconfig.appserver.minthreads Minimum number of threads created for Tomcat 100
bbconfig.appserve.maxthreads Maximum number of threads allocated to Tomcat for 64-bit 4 GB RAM in the heap space

This setting limits the number of requests that can be simultaneously processed by Tomcat.

If fronting Blackboard Learn with Apache™ HTTP Server, this value should match the bbconfig.unix.httpd.maxclients setting.

To learn more, see Sizing the Maximum Thread Count.

<= 400
Maximum number of connections waiting to serve database requests

The BBLEARN (legacy: BB_BB60) connection pool is the primary database connection pool interface for the Blackboard schema in Tomcat. Blackboard recommends that this value be sized conservatively based on need and usage. Start with a maximum value of 100, and then increase the maximum size as the Tomcat application threads increase.

Optimally, this value should be equal to, but not greater than, the bbconfig.appserver.maxthreads parameter setting.

JDBC connection consumption is a symptom of a performance issue or degradation. Increasing the JDBC connection count will not always solve a performance issue. Performance issues should be diagnosed by identifying bottlenecks at their source.

<= 400
Number of connections waiting to serve database requests 10
Initial number of connections waiting to serve database requests for SQL Server 10
bbconfig.database.instance.timeout Time window in which database transactions must be processed before a timeout occurs 60-300

Database connection pool

Starting with the Learn 9.1 April 2014 release, the Tomcat JDBC pool has been configured as the default connection pool for the SQL Server and Oracle Learn deployments. The Tomcat JDBC pool provides a long list of configurable parameters that can be tweaked to change the pool's behavior. For most purposes, the default values are sufficient and should not be changed.

Changing the values of some properties can impact performance and should not be done in a production deployment.

One such good example is the logAbandoned property. If it's required to override the default value of a property, you can complete the following steps.

  • Suppose that you are overriding the validationInterval property from its default value of 30 sec to 10 sec. In bb-datastores.xml.bb, add the property element <property name="validationInterval" value="10000"/> as a child of the the pool-global tag. If the change is required for the standalone tools like Command Line Snapshot, your changes need to be made in the bb-datastores-standalone.xml.bb file.

    <pool-global classname="blackboard.db.impl.TomcatConnectionPool">
       <property name="testOnBorrow"         value="true"/>
       <property name="logAbandoned"         value="false"/>
       <property name="validationInterval"   value="10000"/>

  • Run PushConfigUpdates for the change to take effect.

Note that the pool properties defined under the pool-global tag override the pool properties for all of the databases. If you need to override the pool behavior for just one database, the changes must be made under the pool tag defined for the particular data-store.

For a list of all of the Tomcat JDBC properties, visit https://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html.

The default jdbcInterceptors property should not be overridden.