Step 1: Install Software

This tutorial requires the Java Development Kit (JDK) and the Apache Derby software.

First, this section describes which JDK release is required, asks you to install it if you haven't already, then shows you how to configure and verify your installation.

Next, it shows you how to install the Apache Derby software, configure your environment to use the Derby Embedded JDBC driver, and verify your installation with the Derby sysinfo tool.

Derby requires JDK 21 or higher. Only the Java Runtime Environment (JRE) is required to run Derby, but this tutorial compiles a Java application, so it requires the Java Development Kit (JDK).

If you already have a JDK installed, verify you are configured to use it, then proceed to the Apache Derby installation section.

Install JDK

If you have not already installed a JDK, download and install it now. No specific vendor implementation is required; the only requirement is that it be certified for J2SE 9 or higher. Java's reference implementation is at http://www.oracle.com/technetwork/java/javase/downloads/index.html. After installing the JDK of your choice, proceed to the next section.

Configure JDK

Set the JAVA_HOME environment variable to the root location of the JDK installation directory. The examples below use C:\jdk17 for Windows and /opt/jdk17 for UNIX, but be sure to use the actual location on your system. (e.g. The default installation location used by the JDK installer might be something like C:\Program Files\Java\jdk17.0_11-b21)

Windows: C:\> set JAVA_HOME=C:\jdk17

UNIX Korn Shell: $ export JAVA_HOME=/opt/jdk17

Next set the PATH environment variable to include the JDK bin directory. The PATH variable tells the operating system where to find the java interpreter and the javac compiler.

Windows: C:\> set PATH=%PATH%;%JAVA_HOME%\bin

In Windows, these environment variables can also be set from - right click "My Computer" -> Advanced -> Environment Variables.

UNIX Korn Shell: $ export PATH=$JAVA_HOME/bin:$PATH

Verify JDK

Use the java -version command, as shown below, to verify the installed release:

java -version openjdk version "17" 2021-09-14 OpenJDK Runtime Environment (build 17+35-2724) OpenJDK 64-Bit Server VM (build 17+35-2724, mixed mode, sharing)

The output you see may be different from what is shown above because the java -version command outputs vendor-specific information; however, if you don't see what looks like valid version information, then STOP! And don't proceed until you resolve that problem.

Download Derby

Download the binary Apache Derby distribution from the Derby web site at http://db.apache.org/derby/derby_downloads.html. These tutorial instructions use version 10.17.1.0 and assume you downloaded one of the binary distribution files listed in the table below:

If a more recent release is available, download that, then substitute that version number for 10.17.1.0 in the following instructions.

Install Derby

Choose the directory into which you want to install the Derby software. You must have write permissions to this directory. The sample instructions below use C:\Apache for Windows and /opt/Apache for UNIX; be sure to use your actual location. Copy the software distribution to the location you choose, then extract it as shown below.

Windows (use your extraction tool e.g. WinZip -- these instructions use mks unzip): mkdir C:\Apache copy db-derby-10.17.1.0-bin.zip C:\Apache cd C:\Apache unzip db-derby-10.17.1.0-bin.zip

UNIX: mkdir /opt/Apache cp db-derby-10.17.1.0-bin.tar.gz /opt/Apache cd /opt/Apache tar xzvf db-derby-10.17.1.0-bin.tar.gz

In both cases, the software will now be extracted into a subdirectory named db-derby-10.17.1.0-bin.

Set DERBY_INSTALL

Set the DERBY_INSTALL variable to the location where you installed Derby. Examples are shown below, but be sure to use the actual location on your system:

Windows: C:\> set DERBY_INSTALL=C:\Apache\db-derby-10.17.1.0-bin

UNIX Korn Shell: $ export DERBY_INSTALL=/opt/Apache/db-derby-10.17.1.0-bin

Configure Embedded Derby

To use Derby in its embedded mode set your CLASSPATH to include the jar files listed below:

• derby.jar: contains the Derby engine and the Derby Embedded JDBC driver
• derbytools.jar: optional, provides the ij tool that is used by a couple of sections in this tutorial

You can set your CLASSPATH explicitly with the command shown below:

Windows: C:\> set CLASSPATH=%DERBY_INSTALL%\lib\derby.jar;%DERBY_INSTALL%\lib\derbytools.jar;%DERBY_INSTALL%\lib\derbyoptionaltools.jar;%DERBY_INSTALL%\lib\derbyshared.jar;.

UNIX: $ export CLASSPATH=$DERBY_INSTALL/lib/derby.jar:$DERBY_INSTALL/lib/derbytools.jar:$DERBY_INSTALL/lib/derbyoptionaltools.jar:$DERBY_INSTALL/lib/derbyshared.jar:.

Notice that multiple entries in the class path are separated by a semicolon (;) on Windows and a colon (:) on UNIX.

The Derby software provides another way to set CLASSPATH, using shell scripts (UNIX) and batch files (Windows). This tutorial shows how to set CLASSPATH explicitly and also how to use the Derby scripts to set it.

Change directory now into the DERBY_INSTALL/bin directory. The setEmbeddedCP.bat (Windows) and setEmbeddedCP (UNIX) scripts use the DERBY_INSTALL variable to set the CLASSPATH for Derby embedded usage. You can edit the script itself to set DERBY_INSTALL, or you can let the script get DERBY_INSTALL from your environment. Since you already set DERBY_INSTALL in the "Set DERBY_INSTALL" section above, you don't need to edit the script, so go ahead and execute it as shown below:

Windows: C:\> cd %DERBY_INSTALL%\bin C:\Apache\db-derby-10.17.1.0-bin\bin> setEmbeddedCP.bat

UNIX: $ cd $DERBY_INSTALL/bin $ . setEmbeddedCP

Verify Derby

Run the sysinfo command, as shown below, to output Derby system information:

java org.apache.derby.tools.sysinfo

Successful output will look something like this:

------------------ Java Information ------------------ Java Version: 17 Java Vendor: Oracle Corporation Java home: /Users/rhillegas/sw/java/jdk-17.jdk/Contents/Home Java classpath: /Users/rhillegas/sw/zz/db-derby-10.17.1.0-bin/lib/derbyrun.jar OS name: Mac OS X OS architecture: x86_64 OS version: 11.2.3 Java user name: rhillegas Java user home: /Users/rhillegas Java user dir: /Users/rhillegas/derby/mainline java.specification.name: Java Platform API Specification java.specification.version: 17 java.runtime.version: 17+35-2724 --------- Derby Information -------- [/Users/rhillegas/sw/zz/db-derby-10.17.1.0-bin/lib/derby.jar] 10.17.1.0 - (1901046) [/Users/rhillegas/sw/zz/db-derby-10.17.1.0-bin/lib/derbytools.jar] 10.17.1.0 - (1901046) [/Users/rhillegas/sw/zz/db-derby-10.17.1.0-bin/lib/derbynet.jar] 10.17.1.0 - (1901046) [/Users/rhillegas/sw/zz/db-derby-10.17.1.0-bin/lib/derbyclient.jar] 10.17.1.0 - (1901046) [/Users/rhillegas/sw/zz/db-derby-10.17.1.0-bin/lib/derbyshared.jar] 10.17.1.0 - (1901046) [/Users/rhillegas/sw/zz/db-derby-10.17.1.0-bin/lib/derbyoptionaltools.jar] 10.17.1.0 - (1901046) ------------------------------------------------------ ----------------- Locale Information ----------------- Current Locale : [English/United States [en_US]] Found support for locale: [cs] version: 10.17.1.0 - (1901046) Found support for locale: [de_DE] version: 10.17.1.0 - (1901046) Found support for locale: [es] version: 10.17.1.0 - (1901046) Found support for locale: [fr] version: 10.17.1.0 - (1901046) Found support for locale: [hu] version: 10.17.1.0 - (1901046) Found support for locale: [it] version: 10.17.1.0 - (1901046) Found support for locale: [ja_JP] version: 10.17.1.0 - (1901046) Found support for locale: [ko_KR] version: 10.17.1.0 - (1901046) Found support for locale: [pl] version: 10.17.1.0 - (1901046) Found support for locale: [pt_BR] version: 10.17.1.0 - (1901046) Found support for locale: [ru] version: 10.17.1.0 - (1901046) Found support for locale: [zh_CN] version: 10.17.1.0 - (1901046) Found support for locale: [zh_TW] version: 10.17.1.0 - (1901046) ------------------------------------------------------ ------------------------------------------------------

The output on your system will probably be somewhat different from the output shown above, but it should reflect the correct location of jar files on your machine and there shouldn't be any errors. If you see an error like the one below, it means your class path is not correctly set:

$ java org.apache.derby.tools.sysinfo Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/derby/tools/sysinfo

Echo your CLASSPATH, as shown below, then double check each entry in your class path to verify that the jar file is where you expect it:

Windows: C:\> echo %CLASSPATH% C:\Apache\DB-DER~1.1-B\lib\derby.jar;C:\Apache\DB-DER~1.1-B\lib\derbytools.jar;C:\Apache\DB-DER~1.1-B\lib\derbyoptionaltools.jar;C:\Apache\DB-DER~1.1-B\lib\derbyshared.jar;

UNIX: $ echo $CLASSPATH /opt/Apache/db-derby-10.17.1.0-bin/lib/derby.jar:/opt/Apache/db-derby-10.17.1.0-bin/lib/derbytools.jar:/opt/Apache/db-derby-10.17.1.0-bin/lib/derbyoptionaltools.jar:/opt/Apache/db-derby-10.17.1.0-bin/lib/derbyshared.jar:

If sysinfo outputs valid information, you're ready to move to "Step 2: ij Basics".