Page History

...

External database connection pool

Note: The following uses Tomcat 7 as an example and links to documentation pertaining to that version of Tomcat. Consult the Tomcat migration guide on the specific requirements for your environment.

Before it builds a pool of database connections, DSpace always tries to look up an existing, pre-configured pool in a directory service (if such a service is provided). Many web application containers supply such a service and can be configured to provide the connection pool to DSpace. If DSpace does not find a pre-configured pool, each web application will fall back to creating its own pool using the settings in local.cfg.

There are some advantages to using an external database pool:

• You can The ability to share one pool among several of DSpace's web applications—or even all of them. This can help economize database connections when one application uses many and another few. For example, if XMLUI needs 30 connections to run well at your site under peak load and OAI-PMH needs 5, you could connect them both to a pool of 35 connections, instead of letting each take 30 for a total of 60.
• You can The ability to have different pool sizes for the web applications and the command line tools. For example, configure an external pool with generous settings for the web applications, and a much smaller pool for the command line applications in local.cfg. Note: the command line tools cannot use an externally configured pool, and always use the settings in local.cfg to build their own pool.
• External database pooling often allows for more granular configuration of pool parameters and can even provide better performance than DSpace's fallback pooling (see the Tomcat JDBC Connection Pool documentation for more information).

DSpace applications will specifically look for an object named jdbc/dspace. The name is not configurable, but is specified in config/spring/api/core-hibernate.xml if you must know. You must configure the name of the directory object provided to your web application context(s) to match this. See below for an example in Tomcat 7.

An example in Tomcat 7 running on Ubuntu 16.04

First, you must make the JDBC driver for your database available to Tomcat. For example, the latest PostgreSQL JDBC driver can be downloaded from the PostgreSQL project website and placed in Tomcat's lib directory. The exact location of this directory varies depending on your operating system and Tomcat version, but on Ubuntu 16.04 with Tomcat 7 the location would be /usr/share/tomcat7/lib.

...

  <GlobalNamingResources>
...

    <Resource
        name='jdbc/instance'
<!-- Note that the following applies to Tomcat version 7
         to review description='Our DSpace DBMS connection pool'
differences between Tomcat versions, consult
         type='javax.sql.DataSource'http://tomcat.apache.org/migration.html -->

        auth='Container'<Resource
        username='USER'name="jdbc/instance"
        description="Our DSpace DBMS connection pool"
        type="javax.sql.DataSource"
        auth="Container"
        username="USER"
        password='"SECRET'"
        driverClassName='"org.postgresql.Driver'"
        url='"jdbc:postgresql://dbms.example.com:5432/dspace'"
        initialSize='"5'"
        maxTotal='"50'"
        maxIdle='"15'"
        minIdle='"5'"
        maxWaitMillis='"5000'"
        />
...
  </GlobalNamingResources>

Then add a <ResourceLink> to each web application's context configuration. The name parameter here is local to the application context, and must be jdbc/dspace:

<Context
...<Context>
...

  <!-- Note that the following applies to Tomcat version 7
       to review differences between Tomcat versions, consult
       http://tomcat.apache.org/migration.html -->

  <ResourceLink
    name='"jdbc/dspace'"
    global='"jdbc/instance'"
    type='"javax.sql.DataSource'"
   />
...
</Context>

Notice that the global parameter in the ResourceLink matches the name of the global Resource. See the JNDI Datasource HOW-TO for more information about this configuration.

...