Chapter 6. Database Configuration [DRAFT (1.1)]

Table of Contents

6.1. JDBC Drivers
6.1.1. Automatic JDBC Driver Installation
6.2. Database Pools as Connectors and the TranQL RAR
6.3. Easy Configuration and Deployment using the Console
6.3.1. Create a new JDBC Pool
6.3.2. Create a new XA Database Pool
6.3.3. Import a Pool from Another Application Server
6.3.4. Generate a Plan for an Application or Client Scoped Pool
6.3.5. Edit an Existing Pool
6.4. Manual Configuration and Deployment
6.4.1. Configuring a Database Pool
6.4.2. Deploying a Database Pool
6.5. Using a Database Pool
6.5.1. Updating the Module's Deployment Information
6.5.2. Application Code
6.6. Reconfiguring a Previously Deployed Pool

Most enterprise applications use a relational database in one way or another. Geronimo provides database connection pools, so you can bind a certain database into JNDI, access it from your applications, and reuse existing database connections rather than constantly closing and re-opening them. When mapped as application resources, these database connection pools can be accessed from:

Geronimo supports both standard JDBC connection pools with local transaction, and XA database pools supporting two-phase commit transactions. However, there are a limited number of supported XA drivers in Geronimo 1.0, whereas any JDBC driver should work for a normal JDBC pool.

Database connection pools may be configured at the server level, at the application level, or in the case of an application client, as a part of a single application module. Each of these deployment options works a little differently:

Server-Wide Deployment

The database connection pool can be started or stopped using the Geronimo console or deployment tools. Any application or module can declare a dependency on the connection pool module, and then use it via a resource reference.

Application-Scoped Deployment

The database connection pool is deployed as part of an application, and started or stopped when the application is started or stopped. Any module in the same application can use it via a resource reference. Other applications or modules can declare a dependency on this application in order to use the connection pool, and likewise use it via a resource reference. Note that application-scoped deployments are a convenience feature not a security feature -- other applications can always declare a dependency on the application containing the connection pool in order to access the pool.

Client-Scoped Deployment

Application clients cannot access database connection pools running in the server. However, the same configuration syntax can be used to deploy a database connection pool on the client side as part of the application client deployment. In this case, the database connection pool is visible only to the application client. Again, the client VM must be able to connect directly to the database server; the connections do not originate from the Geronimo application server but from the application client container.

This chapter covers configuring database connection pools in each of these ways.

6.1. JDBC Drivers

In order to deploy any database connection to Geronimo, you need to make a JDBC driver available to it. To make a JDBC driver available to Geronimo, it needs to be installed into the Geronimo repository. For JDBC drivers, there are three possible ways to do this:

  • Use the Database Pools wizard in the console to download and install the JDBC driver automatically.

  • Manually download or acquire the JDBC driver JARs, and use the Common Libs screen in the console to install each JAR into the repository.

  • Manually download or acquire the JDBC driver JARs, manually create the correct directories under geronimo-1.1/repository/, and copy the JARs into there with the correct name

These are listed in order of preference -- the automatic JDBC driver installation is the easiest, but only supports drivers that can be downloaded directly without logins or click-through licenses (the next section lists these). The Common Libs screen is the next best way, as you need only provide the Module ID for each JAR and the installation into the repository is handled by the console. The fully manual installation is more tedious, but may be required for example in Little G where the administration console is not available.

[Tip]Tip

For more information on installing JARs into the repository, including a walkthrough of installing a JDBC driver, see Section 5.2, “Adding JARs to the Repository”.

6.1.1. Automatic JDBC Driver Installation

While deploying a database pool through the console, Geronimo can automatically download certain JDBC drivers and install them into the repository. This is limited to drivers that can be directly downloaded without logins, license agreements, etc. Currently that includes drivers for:

  • HSQLDB 1.7.3 and 1.8.0

  • MaxDB (SAP DB) 7.5 and 7.6

  • McKoi 1.0.3

  • MySQL (JDBC driver version 3.0 and 3.1)

  • PostgreSQL 7.3 through 8.2

  • SQL Server (jTDS driver version 1.1 and 1.2)

  • Sybase (jConnect 5.5 and 6.0)

Also, note that Geronimo ships with drivers for the Derby database (both JDBC and XA).