Introduction

JNDI Datasource configuration is covered extensively in the
JNDI-Resources-HOWTO. However, feedback from tomcat-user has
shown that specifics for individual configurations can be rather tricky.

Here then are some example configurations that have been posted to
tomcat-user for popular databases and some general tips for db usage.

You should be aware that since these notes are derived from configuration
and/or feedback posted to tomcat-user YMMV :-). Please let us
know if you have any other tested configurations that you feel may be of use
to the wider audience, or if you feel we can improve this section in anyway.

Please note that JNDI resource configuration changed somewhat between
Tomcat 7.x and Tomcat 8.x as they are using different versions of
Apache Commons DBCP library. You will most likely need to modify older
JNDI resource configurations to match the syntax in the example below in order
to make them work in Tomcat 8.
See Tomcat Migration Guide
for details.

Also, please note that JNDI DataSource configuration in general, and this
tutorial in particular, assumes that you have read and understood the
Context and
Host configuration references, including
the section about Automatic Application Deployment in the latter reference.

DriverManager, the service provider mechanism and memory leaks

java.sql.DriverManager supports the
service
provider mechanism. This feature is that all the available JDBC drivers
that announce themselves by providing a META-INF/services/java.sql.Driver
file are automatically discovered, loaded and registered,
relieving you from the need to load the database driver explicitly before
you create a JDBC connection.
However, the implementation is fundamentally broken in all Java versions for
a servlet container environment. The problem is that
java.sql.DriverManager will scan for the drivers only once.

The JRE Memory Leak Prevention Listener
that is included with Apache Tomcat solves this by triggering the drivers scan
during Tomcat startup. This is enabled by default. It means that only
libraries visible to the listener such as the ones in
$CATALINA_BASE/lib will be scanned for database drivers.
If you are considering disabling this feature, note that
the scan would be triggered by the first web application that is
using JDBC, leading to failures when this web application is reloaded
and for other web applications that rely on this feature.

Thus, the web applications that have database drivers in their
WEB-INF/lib directory cannot rely on the service provider
mechanism and should register the drivers explicitly.

The list of drivers in java.sql.DriverManager is also
a known source of memory leaks. Any Drivers registered
by a web application must be deregistered when the web application stops.
Tomcat will attempt to automatically discover and deregister any
JDBC drivers loaded by the web application class loader when the web
application stops.
However, it is expected that applications do this for themselves via
a ServletContextListener.

Database Connection Pool (DBCP 2) Configurations

The default database connection pool implementation in Apache Tomcat
relies on the libraries from the
Apache Commons project.
The following libraries are used:

Commons DBCP

Commons Pool

These libraries are located in a single JAR at
$CATALINA_HOME/lib/tomcat-dbcp.jar. However,
only the classes needed for connection pooling have been included, and the
packages have been renamed to avoid interfering with applications.

Installation

Preventing database connection pool leaks

A database connection pool creates and manages a pool of connections
to a database. Recycling and reusing already existing connections
to a database is more efficient than opening a new connection.

There is one problem with connection pooling. A web application has
to explicitly close ResultSet's, Statement's, and Connection's.
Failure of a web application to close these resources can result in
them never being available again for reuse, a database connection pool "leak".
This can eventually result in your web application database connections failing
if there are no more available connections.

There is a solution to this problem. The Apache Commons DBCP can be
configured to track and recover these abandoned database connections. Not
only can it recover them, but also generate a stack trace for the code
which opened these resources and never closed them.

To configure a DBCP DataSource so that abandoned database connections are
removed and recycled, add one or both of the following attributes to the
Resource configuration for your DBCP DataSource:

removeAbandonedOnBorrow=true

removeAbandonedOnMaintenance=true

The default for both of these attributes is false. Note that
removeAbandonedOnMaintenance has no effect unless pool
maintenance is enabled by setting timeBetweenEvictionRunsMillis
to a positive value. See the
DBCP documentation for full documentation on these attributes.

Use the removeAbandonedTimeout attribute to set the number
of seconds a database connection has been idle before it is considered abandoned.

removeAbandonedTimeout="60"

The default timeout for removing abandoned connections is 300 seconds.

The logAbandoned attribute can be set to true
if you want DBCP to log a stack trace of the code which abandoned the
database connection resources.

2. Context configuration

Configure the JNDI DataSource in Tomcat by adding a declaration for your
resource to your Context.

For example:

<Context>
<!-- maxTotal: Maximum number of database connections in pool. Make sure you
configure your mysqld max_connections large enough to handle
all of your db connections. Set to -1 for no limit.
-->
<!-- maxIdle: Maximum number of idle database connections to retain in pool.
Set to -1 for no limit. See also the DBCP documentation on this
and the minEvictableIdleTimeMillis configuration parameter.
-->
<!-- maxWaitMillis: Maximum time to wait for a database connection to become available
in ms, in this example 10 seconds. An Exception is thrown if
this timeout is exceeded. Set to -1 to wait indefinitely.
-->
<!-- username and password: MySQL username and password for database connections -->
<!-- driverClassName: Class name for the old mm.mysql JDBC driver is
org.gjt.mm.mysql.Driver - we recommend using Connector/J though.
Class name for the official MySQL Connector/J driver is com.mysql.jdbc.Driver.
-->
<!-- url: The JDBC connection url for connecting to your MySQL database.
-->
<Resource name="jdbc/TestDB" auth="Container" type="javax.sql.DataSource"
maxTotal="100" maxIdle="30" maxWaitMillis="10000"
username="javauser" password="javadude" driverClassName="com.mysql.jdbc.Driver"
url="jdbc:mysql://localhost:3306/javatest"/>
</Context>

That JSP page makes use of
JSTL's
SQL and Core taglibs. You can get it from
Apache Tomcat Taglibs - Standard Tag Library
project — just make sure you get a 1.1.x or later release. Once you have
JSTL, copy jstl.jar and standard.jar to your web app's
WEB-INF/lib directory.

Finally deploy your web app into $CATALINA_BASE/webapps either
as a warfile called DBTest.war or into a sub-directory called
DBTest

Once deployed, point a browser at
http://localhost:8080/DBTest/test.jsp to view the fruits of
your hard work.

Oracle 8i, 9i & 10g

0. Introduction

Drivers for older Oracle versions may be distributed as *.zip files rather
than *.jar files. Tomcat will only use *.jar files installed in
$CATALINA_HOME/lib. Therefore classes111.zip
or classes12.zip will need to be renamed with a .jar
extension. Since jarfiles are zipfiles, there is no need to unzip and jar these
files - a simple rename will suffice.

For Oracle 9i onwards you should use oracle.jdbc.OracleDriver
rather than oracle.jdbc.driver.OracleDriver as Oracle have stated
that oracle.jdbc.driver.OracleDriver is deprecated and support
for this driver class will be discontinued in the next major release.

1. Context configuration

In a similar manner to the mysql config above, you will need to define your
Datasource in your Context. Here we define a
Datasource called myoracle using the thin driver to connect as user scott,
password tiger to the sid called mysid. (Note: with the thin driver this sid is
not the same as the tnsname). The schema used will be the default schema for the
user scott.

Use of the OCI driver should simply involve a changing thin to oci in the URL string.

PostgreSQL

0. Introduction

PostgreSQL is configured in a similar manner to Oracle.

1. Required files

Copy the Postgres JDBC jar to $CATALINA_HOME/lib. As with Oracle, the
jars need to be in this directory in order for DBCP's Classloader to find
them. This has to be done regardless of which configuration step you take next.

2. Resource configuration

You have two choices here: define a datasource that is shared across all Tomcat
applications, or define a datasource specifically for one application.

2a. Shared resource configuration

Use this option if you wish to define a datasource that is shared across
multiple Tomcat applications, or if you just prefer defining your datasource
in this file.

This author has not had success here, although others have reported so.
Clarification would be appreciated here.

4. Accessing the datasource

When accessing the datasource programmatically, remember to prepend
java:/comp/env to your JNDI lookup, as in the following snippet of
code. Note also that "jdbc/postgres" can be replaced with any value you prefer, provided
you change it in the above resource definition file as well.

Non-DBCP Solutions

These solutions either utilise a single connection to the database (not recommended for anything other
than testing!) or some other pooling technology.

Oracle 8i with OCI client

Introduction

Whilst not strictly addressing the creation of a JNDI DataSource using the OCI client, these notes can be combined with the
Oracle and DBCP solution above.

In order to use OCI driver, you should have an Oracle client installed. You should have installed
Oracle8i(8.1.7) client from cd, and download the suitable JDBC/OCI
driver(Oracle8i 8.1.7.1 JDBC/OCI Driver) from otn.oracle.com.

After renaming classes12.zip file to classes12.jar
for Tomcat, copy it into $CATALINA_HOME/lib.
You may also have to remove the javax.sql.* classes
from this file depending upon the version of Tomcat and JDK you are using.

Putting it all together

Ensure that you have the ocijdbc8.dll or .so in your $PATH or LD_LIBRARY_PATH
(possibly in $ORAHOME\bin) and also confirm that the native library can be loaded by a simple test program
using System.loadLibrary("ocijdbc8");

You should next create a simple test servlet or jsp that has these
critical lines:

where database is of the form host:port:SID Now if you try to access the URL of your
test servlet/jsp and what you get is a
ServletException with a root cause of java.lang.UnsatisfiedLinkError:get_env_handle.

First, the UnsatisfiedLinkError indicates that you have

a mismatch between your JDBC classes file and
your Oracle client version. The giveaway here is the message stating that a needed library file cannot be
found. For example, you may be using a classes12.zip file from Oracle Version 8.1.6 with a Version 8.1.5
Oracle client. The classesXXX.zip file and Oracle client software versions must match.

A $PATH, LD_LIBRARY_PATH problem.

It has been reported that ignoring the driver you have downloaded from otn and using
the classes12.zip file from the directory $ORAHOME\jdbc\lib will also work.

Next you may experience the error ORA-06401 NETCMN: invalid driver designator

Ed. Hmm, I don't think this is really needed if you sort out your TNSNames - but I'm not an Oracle DBA :-)

Common Problems

Here are some common problems encountered with a web application which
uses a database and tips for how to solve them.

Intermittent Database Connection Failures

Tomcat runs within a JVM. The JVM periodically performs garbage collection
(GC) to remove java objects which are no longer being used. When the JVM
performs GC execution of code within Tomcat freezes. If the maximum time
configured for establishment of a database connection is less than the amount
of time garbage collection took you can get a database connection failure.

To collect data on how long garbage collection is taking add the
-verbose:gc argument to your CATALINA_OPTS
environment variable when starting Tomcat. When verbose gc is enabled
your $CATALINA_BASE/logs/catalina.out log file will include
data for every garbage collection including how long it took.

When your JVM is tuned correctly 99% of the time a GC will take less
than one second. The remainder will only take a few seconds. Rarely,
if ever should a GC take more than 10 seconds.

Make sure that the db connection timeout is set to 10-15 seconds.
For the DBCP you set this using the parameter maxWaitMillis.

Random Connection Closed Exceptions

These can occur when one request gets a db connection from the connection
pool and closes it twice. When using a connection pool, closing the
connection just returns it to the pool for reuse by another request,
it doesn't close the connection. And Tomcat uses multiple threads to
handle concurrent requests. Here is an example of the sequence
of events which could cause this error in Tomcat:

Request 1 running in Thread 1 gets a db connection.
Request 1 closes the db connection.
The JVM switches the running thread to Thread 2
Request 2 running in Thread 2 gets a db connection
(the same db connection just closed by Request 1).
The JVM switches the running thread back to Thread 1
Request 1 closes the db connection a second time in a finally block.
The JVM switches the running thread back to Thread 2
Request 2 Thread 2 tries to use the db connection but fails
because Request 1 closed it.

Here is an example of properly written code to use a database connection
obtained from a connection pool:

Context versus GlobalNamingResources

Please note that although the above instructions place the JNDI declarations in a Context
element, it is possible and sometimes desirable to place these declarations in the
GlobalNamingResources section of the server
configuration file. A resource placed in the GlobalNamingResources section will be shared
among the Contexts of the server.

JNDI Resource Naming and Realm Interaction

In order to get Realms to work, the realm must refer to the datasource as
defined in the <GlobalNamingResources> or <Context> section, not a datasource as renamed
using <ResourceLink>.