[Db-derby Wiki] Update of "UpgradingTen" by DanDebrunner

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Db-derby Wiki" for change notification.

The following page has been changed by DanDebrunner:
http://wiki.apache.org/db-derby/UpgradingTen

New page:
= 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 [http://db.apache.org/derby/releases/release-10.1.1.0.cgi official Derby 10.1 release] is available at the [http://db.apache.org/derby/derby_downloads.html 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:

  1. Shutdown the application running Derby
  1. 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.
  1. 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:

  1. Shutdown the application running Derby
  1. 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.
  1. 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 Data''''''Source {{{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:

    * Online compress functionality for reclaiming disk space during operation
    * Increased identifier lengths to 128 characters for all identifiers
    * Added SQL: INTERSECT and EXCEPT
    * Added SQL: SYNONYM
    * Allow insertions into an identity column