Using A Derby Database Embedded In Your Java Application

Introduction

In a previous blog article, I explored how to use MyEclipse's Derby database server. The example application for that blog entry used Derby in its client/server mode, where the database was separate from the Java application and managed by the Derby database server. However, as I mentioned at the end of that article, Derby also has a mode where you can embed the complete database in your Java application. Then the user of the application does not need the separate Derby database server.

Example Application

I created a MyEclipse Java project (download an archive of the project) based on the example provided in the Derby documentation (see http://db.apache.org/derby/docs/dev/getstart/, self-study tutorial, activity 3). My example is IAW the Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0).

Key Points When Embedding The Database In A Java Application

The example from the Derby Getting Started documentation contains very good comments and should be easy to follow for experienced Java JDBC developers. Here are some key points:

Your program will need the derby.jar in its class path. I just copied the derby.jar into my source folder in the MyEclipse project and added it to the libraries in the Java Build Path settings in MyEclipse. The derby.jar file is included in the lib and bin distributions (see: http://db.apache.org/derby/derby_downloads.html). The derby.jar only adds around 2mb to your application's size, so embedding a completely functional relational database in your application isn't going to cause a big jump in size.

The connection URL is

connectionURL = "jdbc:derby:" + dbName + ";create=true";  

the create=true will cause Derby to create the database if it doesn't already exist. The database is created in your project's root folder. You can also specify where Derby's database engine should create/look for the database by adding an absolute or relative path. For example:

 connectionURL = "jdbc:derby:c:/derby/" + dbName + ";create=true";

The above would cause the Derby database engine to create and look for the database in the c:/derby/ folder.

You could also put your database on the class path or in a jar or zip file. Those databases would be read-only. See: http://db.apache.org/derby/docs/10.4/devguide/devguide-single.html#cdevdvlp34964 for more information about how and where you can specify the Derby database embedded in your application.

Your program must use the org.apache.derby.jdbc.EmbeddedDriver JDBC driver. Loading the driver starts the Derby database engine.

Be sure your application shuts down the Derby database engine and databases by using this code:

DriverManager.getConnection("jdbc:derby:;shutdown=true"); 

The shutdown=true will cause all databases to close properly.

Summary

The ability to easily integrate a database into your Java application by using Derby makes creating example or prototype applications that you want to share with others much simpler. Derby has an excellent tutorial series and documentation to assist Java developers in learning how to use Derby in their applications. The working with Derby wiki (http://wiki.apache.org/db-derby/WorkingWithDerby) has numerous examples of how to use Derby in various kinds of Java applications.

I ran across something I wasn't aware of as I was researching this article. Sun Microsystems has a version of Derby they call java DB and Sun now includes java DB (aka Derby) in JDK 6. See http://developers.sun.com/javadb/index.jsp for more information.

References

MyEclipse Java Project With Embedded Derby Database (archived project you can import into MyEclipse)

Apache Derby, http://db.apache.org/derby/

Working With Derby, http://wiki.apache.org/db-derby/WorkingWithDerby

Sun Microsystems java DB (aka Derby), http://developers.sun.com/javadb/index.jsp

Java Databasing With Derby, Pan Pantziarka, http://www.theregister.co.uk/2006/11/08/java_database_derby/