Upgrading Derby 10.0 to 10.1 – Very Simple!

Overview

Upgrading your application to use Derby 10.1 with an existing 10.0 database is extremely easy. There are two options:

Soft Upgrade - Use when your application is not changing but you want to use the new version of Derby.
Full Upgrade - Use when you want to take advantage of all of Derby 10.1's new features!

The official Derby 10.1 release is available at the Derby downloads page. These instructions, though, apply to any 10.1 release, including the up-coming 10.1.2 bug fix release.

$/!\$ Taking a backup before an upgrade is a good precaution.

Soft Upgrade

Soft upgrade allows you to run your application with Derby 10.1 while leaving the option to revert to 10.0 should you discover any issues.

Three simple steps:

Shutdown the application running Derby
Change the application to use the Derby 10.1 jar files
- Either by changing the class path to point to the 10.1 jar files instead of the 10.0 jar files,
- Or replace all the 10.0 jar files the application is using with the 10.1 jar files.
Restart your application.

That's it , your application is now running using the 10.1 jar files.

You may switch your application back to 10.0 at any time by following an identical procedure, swapping 10.0 and 10.1.

Selected 10.1 New Features

Soft upgrade does allow your application to use selected new features, but obviously if you modify your application to use them, then application will no longer run against 10.0.

The new features are:

New open source Derby network client driver
Support for J2ME/CDC/Foundation with JSR-169 JDBC subset
XA support for Network Server
Increased identifier lengths to 128 characters for all identifiers
JDBC Updatable Result Sets
ORDER by expressions

Full Upgrade

Full upgrade allows your application to take full advantage of Derby 10.1's new features, but means that you can no longer revert to 10.0 for the database.

Three simple steps:

Shutdown the application running Derby
Change the application to use the 10.1 jar files
- Either by changing the class path to point to the 10.1 jar files instead of the 10.0 jar files,
- Or replace all the 10.0 jar files the application is using with the 10.1 jar files.
Ensure that the first connection request includes the attribute upgrade set to true.
- Either by connecting using ij with a JDBC URL like: jdbc:derby:mydb;upgrade=true
- Or by running a simple Java JDBC program that connects to the database setting the upgrade attribute
  - ```
      // Using JDBC URLs
      String dbURL = "jdbc:derby:mydb";
      Properties connProps = new Properties();
      connProps.put("upgrade", "true");
      ... set any other properties
      Connection conn = DriverManager.getConnection(dbURL, connProps);
```
- Setting the Java Bean property for the Derby DataSource connectionAttributes to include upgrade=true in its value.
- Or by including an upgrade feature in your application that allows the user to select upgrade and connects to the databse with the upgrade attibute. This application code would use one of the three methods above.

That's it , your application is now running using the 10.1 jar files.

If you attempt to boot 10.0 against the database just upgraded, then the boot will fail.

ERROR XJ040: Failed to start database 'cs', see the next exception for details.
ERROR XSLAN: Database at C:\_work\derby\cs has an incompatible format with the current version of the software.  The database was created by or upgraded by version 10.1.

Enabled 10.1 New Features

In addition to the features listed in Soft Upgrade, these new features are enabled by full upgrade: