[frs-289] Using the JDBC Wrapper with Apache Derby Database on ColdFusion

This technote is about using the JDBC Driver Wrapper with the Apache Derby database (either in client-server mode, or embedded mode) on Adobe ColdFusion.

Wrapping the datasource

The simplest way to wrap an existing Apache Derby datasource is to use the FusionReactor wrapper tool. This can be downloaded from here.

Use this tool to create a wrapped version of the embedded datasource.

N.b. because the wrapper doesn't initially know about the driver itself, the wrapper tool may raise a Verification Exception:

java.sql.SQLException: FusionReactor JDBC: [6] Wrapper – Driver class org.apache.derby.jdbc.EmbeddedDriver could not be found and loaded.
The root cause was that: java.sql.SQLException: FusionReactor JDBC: [6] Wrapper – Driver class org.apache.derby.jdbc.EmbeddedDriver could not be found and loaded.

Even if this does not occur, you will need to edit the datasource. Go to the ColdFusion Administrator -> Data Sources and edit the new _WRAPPED driver.

Add the following two options to the JDBC URL:

  • cp=C:ColdFusion9libderby.jar – this tells the wrapper where the Derby driver is located.
  • autocommit=false – this tells the wrapper not to enable autocommit for the driver. This option is required by ColdFusion.

You may have to adjust the path to the jar, depending on the install location of your ColdFusion instance. Once you've added these options, you should have a complete JDBC URl which looks something like this:


Save the data source definition in the ColdFusion Administrator.

CF may have problems 'starting' the database (for embedded derby). This is because only one driver at once can start and use an embedded apache database, and if the unwrapped driver is still present, it may have opened the database first. In this case, derby will raise an EmbedSQLException

Connection verification failed for data source: cfbookclub_WRAPPED
org.apache.derby.impl.jdbc.EmbedSQLException: Failed to start database 'C:ColdFusion9dbbookclub'.

To avoid this error:

  • Ensure your application does not use the unwrapped driver prior to it using the wrapped driver. The easiest way to do this is to only use the wrapped driver.

You may wish to simply delete the unwrapped version of the driver, in order to ensure that nothing is using it.

Sharing Connections

If you mix wrapped and unwrapped embedded datasources, FusionReactor 4.5.0 will attempt to mediate connections it opens and wraps with unwrapped datasources, in an attempt to alleviate the problem. This is, however, done on a 'best effort' basis and is not a supported configuration. In production, you should not mix wrapped and unwrapped embedded drivers on the same database.

To reset the status of the drivers, restart ColdFusion. The Wrapped datasource can then be verified and used.

Issue Details

Type: Technote
Issue Number: FRS-289
Components: JDBC
Resolution: Fixed
Last Updated: 16/May/12 3:28 PM
Affects Version:
Fixed Version: 4.5.0
Server: ColdFusion 8, ColdFusion 9
Related Issues:

Comments are closed.