Upgrading Derby 10.x – Very Simple!

Overview

Upgrading your application to use a new Derby version with an existing 10.x database is extremely easy. There are two options:

The latet Derby release is available at the Derby downloads page. These instructions, though, apply to any 10.x release.

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

Soft Upgrade

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

Three simple steps:

  1. Shutdown the application running Derby
  2. Change the application to use the new Derby jar files
    • Either by changing the class path to point to the new jar files instead of the previous 10.x jar files,
    • Or replace all the old derby jar files the application is using with the new Derby jar files.
  3. Restart your application.

That's it :-) , your application is now running using the new jar files.

You may switch your application back to at any time by following an identical procedure, swapping the old jars for the new. It is perfectly fine to skip versions and upgrade directly from 10.1 to 10.6 for instance and back again from soft upgrade.

Selected New Features

Soft upgrade does allow your application to use selected new features,and take advantage of bug fixes, but obviously if you modify your application to depend upon them, then application will no longer run against the previous version. Generally, features can be used in soft upgrade if they don't modify the system catalogs. For example in 10.6, you cannot use UDT's in soft upgrade mode from a previous version, but the new CROSS JOIN syntax will work in soft upgrade.

Full Upgrade

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

Three simple steps:

  1. Shutdown the application running Derby
  2. Change the application to use the new Derby jar files
    • Either by changing the class path to point to the new Derby jar files instead of the Derby old jar files,
    • Or replace all the old Derby jar files the application is using with the new jar files.
  3. 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 new Derby jar files and can take full advantage of the new features.

If you attempt to boot the old Derby version against the database was just hard 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

UpgradingTen (last edited 2010-09-02 13:23:20 by KatheyMarsden)