Demo Derby 3

What Demo Derby 3 Actually Is

Demo Derby 3 is a demonstration application bundled with Apache Derby that shows how to run a lightweight Java database in embedded mode. It came out around 2006 alongside Derby 10.2.x and is not meant for production use in any shape or form. It exists to give developers a running example they can point at and say "this is how the API works." You need the full Apache Derby distribution, not just the database jar. Grab the binary from the Apache mirrors and unpack it somewhere reasonable. The classpath needs derby.jar, derbytools.jar, and derbynet.jar all on it. If you skip derbynet.jar you will spend twenty minutes debugging a ClassNotFoundException that looks nothing like what you expect. Create a directory for your work. Copy the demo folder from the distribution into it. Then run the server with:

java -cp .;%DERBY_HOME%\lib\derby.jar;%DERBY_HOME%\lib\derbytools.jar;%DERBY_HOME%\lib\derbynet.jar;org.apache.derby.tools.derby That last class name is the actual entry point. On Linux you swap the semicolons for colons. If you are on Windows and use forward slashes in your path, the command still works but it looks wrong enough that you will second-guess yourself three times before it runs. Once the server starts, open a second terminal and run ij or connect directly from your application code. The default connection string is jdbc:derby://localhost:1527/demoDB. It will create the database automatically on first connect if it does not exist. This auto-create behavior is documented but people miss it and then wonder why their database seems to appear out of nowhere.

Common Problems People Hit

The biggest issue I ran into years ago involved locking. Demo Derby 3 uses the default Derby locking scheme, which means every connection that modifies data holds locks until commit. If you opened two embedded connections to the same database in the same JVM and tried to write from both simultaneously, one would block. I spent an afternoon thinking my code was broken when the real problem was that I had left two connection pools initialized in a test runner without closing them properly. The fix was adding a finally block to close both connections and setting the isolation level to read_committed so other tests could proceed without deadlocking. Another thing that catches people out is the classpath ordering. Derby checks the classpath for driver registration. If you have multiple versions of derby.jar on it, the wrong one wins and you get cryptic schema errors. Pin your classpath to exactly one version and stop chasing phantom bugs.

When to Use It and When to Walk Away

Demo Derby 3 works fine for local development, unit testing, and proof of concept work where you need a real SQL database without installing anything heavy. It shuts down fast, stores data in flat files, and is completely self-contained. If your project requires replication, clustering, or concurrent write access across multiple nodes, this tool will not help you. Derby's network server mode handles modest concurrency but it still lacks features you would take for granted in PostgreSQL or MySQL. For anything production adjacent, consider pointing your team toward a proper managed instance instead. Demo Derby 3 is educational. It demonstrates the API surface, shows basic SQL compliance, and gives you a sandbox. That is it. If you want the download, go to the Apache Derby website and grab the latest distribution. The Demo Derby 3 files come included inside. There is no separate installer. Unpack, set your classpath, and run the demo script that ships with it. Everything else is up to you.