Data Management

Get your feet wet with Sun's tiny Java DB

Java DB is a lightweight database management system (DBMS) that is written completely in Java. Peter Mikhalenko describes the technology behind the DBMS and explains how to start using it.

Java DB is a lightweight database management system (DBMS) that is written completely in Java. It only needs 2 MB of memory, and it makes it very easy to embed a fully functional database directly into your application. Java DB is also standards-based, supports SQL and the JDBC API, and easily integrates with J2EE. Beginning with the release of Java 6, Sun started packaging Java DB in the JDK.

The technology behind the DBMS

Apache Derby is the core technology of Java DB. Derby's database engine is a fully functioning relational embedded database engine. JDBC and SQL are the main programming APIs.

Another core component that supplements the Java DB is the Derby network server. The network server extends the reach of the Derby database engine by providing traditional client server functionality. The network server allows clients to connect over TCP/IP using the standard DRDA protocol; it also allows the Derby engine to support networked JDBC, ODBC/CLI, Perl, and PHP.

Derby has three useful utilities: ij, dblook, and sysinfo.

  • ij is a tool that allows SQL scripts to execute against any JDBC database.
  • dblook is a schema extraction tool for a Derby database.
  • sysinfo is a utility that allows you to display version numbers and class path.

Multithreading concerns

When an application accesses the Derby database using the Embedded Derby JDBC driver, the Derby engine does not run in a separate process, and there are no separate database processes to start up and shut down. Instead, the Derby database engine runs inside the same Java Virtual Machine (JVM) as the application; the Derby actually becomes part of the application just like any other jar file that the application uses.

Derby supports multiple connections to a given database. An example of an embedded application that manages concurrent users is a Tomcat or Geronimo application server that embeds Derby. Any number of users can execute Web applications that access a database through that Web server. Only one JVM may boot ("open") that database, so multiple applications running in different JVMs cannot access the same database.

Get started with Java DB

In order to start using the DBMS, you need to download Java DB from the Sun Developer Network. The binary distribution provides everything you need to begin working with embedded database applications.

After you download the binary distribution, the Java DB directory structure contains these subdirectories: demo, frameworks, javadoc, docs, and lib.

  • demo has two demonstration programs. One example shows how to create a trivial embedded application, and the other example shows how to use Java DB in a client-server environment.
  • frameworks contains utilities for setting up environment variables and for creating and working with databases. (I do not use this subdirectory in the demo I outline in this article because our application will be entirely self-contained. No outside utilities will be used for the Address Book application.)
  • javadoc contains API documentation. This subdirectory is particularly useful if you configure your IDE to point to it as the Java DB API Javadoc.
  • docs contains documentation about the Java DB product setup, administrator, and reference guides.
  • lib contains the Java DB libraries packaged as JAR files.

(Read the Java DB documentation to find out about the various libraries.)

For an embedded database application, I will use only the derby.jar library file; to install Java DB for development, it only requires that you make the derby.jar file part of your application classpath.

After you install the binary distribution and include derby.jar into your classpath (if you've already installed Java 6, simply include the derby.jar into your classpath), you can start using Java DB just like you would any other JDBC-compliant database.

Driver management

You can start using the DBMS by loading the JDBC technology driver. (Java DB's drivers come with the derby.jar file, so you don't need to download anything else.) To load the driver, reference it using the Class.forName method. The embedded driver name is org.apache.derby.jdbc.EmbeddedDriver, and you can load it as you would other JDBC drivers:


When you want to retrieve a connection from the driver manager, you simply provide a URL string that identifies the database and a set of properties that influence the connection's interaction with the database. A very common use of properties is to associate a user name and password with a connection. The dbName portion of the URL identifies a specific database. A database can be in one of many locations, including: the current working directory, a JAR file, a specific Java DB database home directory, an absolute location on your file system, or on the classpath.

The easiest way to manage your database location in an embedded environment is to set the derby.system.home system property; this property tells Java DB the default home location of all databases. The optional propertyList is a set of properties that you can pass to the database system. You can pass properties into the Java DB system either on the URL or as a separate Properties object. If properties are part of the URL, a semicolon (;) should precede each property. Here are the most common properties:






Once the application specifies where all databases will exist, it can retrieve a database connection.

private void setDBSystemDir() {

    // Decide on the db system directory: <userhome>/.addressbook/

    String userHomeDir = System.getProperty("user.home", ".");

    String systemDir = userHomeDir + "/.addressbook";

    // Set the db system directory.

    System.setProperty("derby.system.home", systemDir);


Connection dbConnection = null;

String strUrl = "jdbc:derby:DefaultAddressBook;user=dbuser;password=dbuserpwd";

try {

    dbConnection = DriverManager.getConnection(strUrl);

} catch (SQLException sqle) {



Have fun with this tiny database, which lives directly in your application.

Peter V. Mikhalenko is a Sun certified professional who works as a business and technical consultant for several top-tier investment banks.


Get Java tips in your inbox Delivered each Thursday, our free Java Developer newsletter provides insight and hands-on tips you need to unlock the full potential of this programming language. Automatically subscribe today!

The frameworks directory (with scripts) has been deprecated for a while now, and will most likely disappear in the next release of Derby. If you want to use scripts, use the ones in the bin directory instead.

Martin Simons
Martin Simons

This create=true databaseName=nameOfDatabase user=userName password=userPassword shutdown=true comes directly from the Sun tutorial for this, and it makes the same mistake that you've made here. Presenting the options as a list in this manner implies that you should (or at least could) use/include all of them at the same time. In reality, the shutdown option must be presented alone (and you don't even need to use a dbname/sid when you do so). Presenting tht option, along with the others, will prevent you from ever getting a connection to the DB, as you will be shutting it down every time you make an attempt.


i'm a legacy programmer was working on mainframe. i need to learn java, i need help and instructions for how to begin, what is the staring points and what sofrware needed. i saw thousand of java products but which one is good for corporate use. thanks


Thanks for this, Martin, good note


I found the following two sites to be very useful - A very good tutorial site for beginner and advanced level java developers - A very good site for various technical tutorials on video. It has extensive list of technical subjects including various programming languages, databases, softwares, hardwares etc.


You will find that learning Java is the easy part. It is the toolset were you will run into trouble. There is a lot of good training out there for Java, find one that works. I operate mostly in the mainframe world and I have found that the tools used for Java are poorly documented and training is even worse. Most businesses will spend a lot of money on the teaching of a language, but will spend zilch on the tools training.


Sun has EXCELLENT java training courses. SL275 is designed for programmers who need to learn java. The instructors are really good at teaching java concepts and relating them to other languages. The closest training site is in Dubai. If you want to learn java without paying much money, download Sun's NetBeans IDE and purchase a copy of "Head-First Java". It's one of the best books for learning java concepts.


I was a legacy programmer for years. I would go to the Java website the have loads of tutorials. And I would look to learning the JEE version. That is their enterprise version, then work your way into all the different permutations. Good Luck.


I'm just a java hobyist, but I think you should try either Eclipse or Netbeans IDE. Personnally I like Netbeans and there a number of great tutorials on the site... probably the same goes for the eclipse site. Both are free. After that, there's alot of stuff on the web, and books to choose from.


I bought the book Head First Java based on a recomendation by our vendor IBM "software architect". It really is what molshansky said. If you like cartoons, analogies and a more human approach you will love this book. I don't think many IDE's come with spell or grammar check though. Based on what I read, that may be a consideration you need to use. Also, I'm a rookie but my java experience so far is that you must compile before you run, and the suggested technique is change code/run test/change code/run test.


did u try it yourself or this is just an advice. if u did, would u tell me how u swich to java and how long it takes u to experience it. thanks any way

Editor's Picks