Create a World Database in Derby

1. Install Derby in your software library.

Unzip the db-derby-X.Y.Z.zip file to a directory where you store software. You should use
a short path without spaces because the path will be accessed via an environment variable (spaces
and long paths usually work, but why ask for problems?).
Good examples are d:\lib\db-derby on Windows and /opt/db-derby on Linux. The
ZIP file contains the following directories and files. There are lots of useful tools here; explore the
directories.
db-derby/
bin/
Programs and scripts, such as ij
ij
Command line SQL client program
demo/
Demo programs with source code, demo databases
docs/
Documentation as HTML and PDF
pdf/
adminguide/
Administrator's guide
devguide/
Developer's guide
getstart/
Getting started, has code examples and tutorials
tools/
How to use derby tools
html/
various/
Documentation in HTML format.
javadoc/
JavaDoc, of course
lib/
JAR files, e.g. derby.jar, derbyrun.jar
derby.jar
Derby JDBC driver for embedded mode database
derbyclient.jar
Derby JDBC driver for Client-Server mode
derbyLocale_XX.jar
Language localization files, not needed.
test/
2. Set the DERBY_HOME environment variable.
Set this for your operating system or shell. You can also type in on the command line:
DOS> set DERBY_HOME=d:\lib\db-derby
3. Start a Windows cmd window or Linux shell, and change directory to a place where you will store
the world database. You should not use the derby installation directory.
DOS> mkdir \database
4. Run the Derby "ij" command. There are a couple of ways to run this. The simplest is:
DOS> %DERBY_HOME%\bin\ij
ij>
"ij" is a command script ("ij" on Linux, "ij.bat" on Windows).
"ij" runs Derby using the command: java -jar %DERBY_HOME%/lib/derbyrun.jar ij
5. Create a world database and connect to it. Derby creates a directory for each database (don't
create it yourself). Here we will use directory \database\world. Using the ij command, enter:
ij> CONNECT 'jdbc:derby:/database/world;create=true';

Derby Database

-1-

The syntax of the CONNECT command is:

CONNECT 'url;options'
URL syntax for JDBC is covered in my Java DatabaseTutorial.
If Derby prints the message "No suitable driver found for database type derby", it means
derby.jar is not on the CLASSPATH. You can add it to the CLASSPATH like this:
set CLASSPATH=d:/lib/db-derby/lib/derby.jar;%CLASSPATH%
or edit the file derby\bin\derby_common.bat and add it to the LOCALCLASSPATH variable,
or specify it as a command line argument to java or ij: java -cp d:/lib/db-derby/lib/derby.jar
Derby will create a directory named /database/world and store database files, indices,
transactions, and logs in this directory.
6. The schema for the world database is in the SQL file world-schema-derby.sql. This file
contains SQL CREATE TABLE commands to define the tables and columns in the database. (Derby
and MySQL use different database types and different syntax for auto-indexed keys, so there are
separate schema files for Derby and MySQL).
ij> run '/temp/world-schema-derby.sql';
Check the output for ERROR messages. If there are any errors, fix them before going on.
7. Add Country data to the database using the file country-data.sql. This file contains SQL
INSERT commands with Country data.
ij> run '/temp/country-data.sql';
Add the City data using the file city-data.sql:
ij> run '/temp/city-data.sql';
8. Verify that the correct number of countries were created:
ij> SELECT count(*) FROM Country;
239
ij> SELECT count(*) FROM City;
4079
ij> SELECT count(*) FROM Countrylanguage;
986 (answer may differ slightly. I corrected a few errors in the world data.)

Optional: Move the derbyLocale JAR files

derby.jar references a resource bundle for translations of Derby messages and locale-based
formatting. It doesn't have a Thai locale. When you add derby.jar to an Eclipse project, it also
adds all the derbyLocale jars. You can make your project smaller by moving the derbyLocale_XX
jar files to another directory before creating projects. I used a subdirectory named Locale:

Derby Database

-2-

db-derby/
bin/
lib/
JAR files, e.g. derby.jar, derbyrun.jar
derby.jar
embedded mode Derby JDBC driver
derbyclient.jar
client mode Derby JDBC driver
derbyLocale_cs.jar
derbyLocale_de_DE.jar
MOVE derbyLocale files to a new directory.
derbyLocale_XX.jar
derbyLocale_zh_ZH.jar
Locale/

Embedded Mode and Client-Server Mode

Derby has two modes of operation: Embedded mode and Client-Server mode.
In Client-Server mode, the database server runs as a separate process and listens for client
connection requests. Clients can connect from the local machine or over a network. MySQL, Oracle,
and DB2 use client-server mode. The server runs continuously, even if there are no clients connected.
In Embedded mode, the database server and client are embedded into an application as a single
component or process. There is no separate server, and only one application can use the database at a
time (that is, only one connection).
In embedded mode, you don't need to install and run a separate database server. The application
contains its own database server, and can create its own database as needed. Embedded mode is
useful for development, demonstrations, and testing, since you don't need to install and run a separate
server, and don't consume memory running a server when its not needed.
Two popular embedded databases are Derby and HSQLDB.

Using Derby in Embedded Mode

In embedded mode, Derby provides direct access to the database and only one application can access
the database simultaneously. This mode is convenient for use in Java apps where only one application
accesses the database, since you don't need to run a separate database manager.
The embedded mode JDBC driver class is org.apache.derby.jdbc.EmbeddedDriver and
the JAR file is db-derby/lib/derby.jar.
URL to Embedded Mode Database: The JDBC URL for connecting to the database is:
jdbc:derby:/path/databasename
for example:
jdbc:derby:/database/world
You can append attributes to this URL. To create a new database add: ;create=true

How to Create a Database at Runtime

To create a database at runtime ";create=true" to the database URL. This creates an empty
database, only if the database doesn't exist.
For example:
jdbc:derby:/d:/database/world;create=true
creates an empty database. Your app must create the database schema. Some JPA implementations
(such as Eclipselink) and Hibernate can create schema at run time.
Derby Database

-3-

Using Derby in Client-Server Mode

Derby can run as a server that accepts client connection locally or via a network (like the way MySQL
works). You start and stop the server (and client) using scripts in the bin/ directory. There is also
a separate client JDBC driver for client-server mode.
To start a Derby server on port 3301 that accepts connections only from localhost, use:
> startNetworkServer -p 3301
You can omit "-p 3301" and Derby will listen on the default port 1527.
To start a server that accepts connections from any host on port 1527 use:
> startNetworkServer -h 0.0.0.0
For a server that accepts connections only from localhost or the host hacker.ku.ac.th use:
> startNetworkServer -h hacker.ku.ac.th
You can also start a server using the derbyrun.jar file. For example:
> java -jar %DERBY_HOME%\lib\derbyrun.jar server start

JDBC Driver for Client Connections

The JDBC driver for client mode is org.apache.derby.jdbc.ClientDriver in the JAR
file derbyclient.jar.
In client-server mode, the client and server may be on different machines, so the URL should include
the hostname and port where the server is running. The JDBC URL for connecting to a Derby server
is:
jdbc:derby://hostname:port/databasename
For example, jdbc:derby://myhost.com/database/world. Here we use the default port
(1527). If the server is running on the local machine and using port 3301, the client URL is:
jdbc:derby://locahost:3301/databasename

Connecting to a Server using the "ij" command

Once the server is running, you can connect using ij or other SQL client.
cmd> ij
ij> connect 'jdbc:derby://localhost:1527/database/world';
ij> show tables;
ij> describe City;
ij> select count(*) from city;
ij> quit;

"ij" can be used to connect to other databases: (a) put the database JDBC driver on the classpath, (b)
use the correct database URL in the connect command.

Resources
1. Derby Tutorial on vogella.de (this site has many good tutorials).
http://www.vogella.de/articles/ApacheDerby/article.html
2. Derby home page on Apache http://derby.apache.org.
3. Derby manuals are included in the Derby download package. The getstartderby.pdf and
devguide/derbydev.pdf manuals have many examples.
Derby Database

-4-