Migrate Apache Derby databases

The migration tools migrate any Apache Derby instances to the new configuration, and they copy any Apache Derby instances stored in the previous release's WebSphere Application Server configuration tree to the new release's configuration tree. After we use the migration tools, verify the results of the database migration and manually migrate any database instances or copy any Derby database instances that the tools do not automatically migrate or copy.

For resources to help us plan and perform our migration, visit Knowledge Collection: Migration planning for WAS.

Before running the migration tools, ensure any application servers hosting applications that are using a Derby database are closed. Otherwise, the database migration will fail.

Before running the migration tools, ensure that the debug migration trace is active.

By default, this trace function is enabled. To reactivate the debug migration trace if it is disabled, set one of the following trace options:

• all traces*=all
• com.ibm.ws.migration.WASUpgrade=all

WAS v9.0 requires Apache Derby Version 10.3 or later. Apache Derby Version 10.3 is a pure Java database server that combines the Derby runtime with the opportunity to use the full services of IBM Software Support. For comprehensive information about Apache Derby Version 10.3, read the Apache Derby Web site.

Important: Derby-to-Derby migration performs a file-system copy of the data at a given point in time. This snapshot will not remain in sync with the database in the previous installation. If we roll back to the previous release, any updates to the database that we made after migration will not be reflected in the previous installation.

Tasks

1. Migrate the configuration to v9.0.

2. Verify that the Derby database instances have been copied.

   When we migrate from WAS v7.0 or later to v9.0, the migration tools automatically upgrade Derby database instances accessed through the embedded framework by some internal components such as the UDDI registry. The tools also attempt to upgrade Derby instances that the applications access through the embedded framework. We must verify these migration results after running the migration tools.

   • To distinguish between a partially and a completely successful Derby migration, verify the automatic-migration results by performing the following tasks:

     1. Check the general migration post-upgrade log for database error messages.

        These exceptions indicate database migration failures. The migration tool references all database exceptions with the prefix DSRA.

     2. Check the individual database migration logs.

        These logs have the same timestamp as that of the general migration post-upgrade log. The individual logs display more detail about errors listed in the general post-upgrade log as well as expose errors that are not documented by the general log.

        The path name of each database log is...

        app_server_root/profiles/profileName/logs/myFulldbPathName_migrationLogtimestamp.log

     3. Look at the debug log that corresponds with the database migration log.

        The WAS migration utility triggers a debug migration trace by default; this trace function generates the database debug logs.

        The full path name of each debug log is...

        app_server_root/profiles/profileName/logs/myFulldbPathName_migrationDebugtimestamp.log

     Performing these tasks gives you vital diagnostic data to troubleshoot the partially migrated databases as well as those that fail automatic migration completely. Ultimately, we must migrate databases that were not completely migrated automatically through a manual process. The log messages contain the exact old and new database path names that we must use to run the manual migration. Note these new path names precisely.

   • Verify any Derby database instances stored in the previous release's WAS configuration tree were copied to the new release's configuration tree

     Check the general migration post-upgrade log for database error messages. These exceptions indicate database migration failures. The migration tool references all database exceptions with the prefix DSRA.

3. Manually copy Derby database instances where necessary.

   • The v9.0 migration tools do not attempt to migrate database instances that transact with applications through the Apache Derby Network Server framework. This exclusion eliminates the risk of corrupting third-party applications that access the same database instances as those accessed by WAS.

     To minimize the risk of migration errors for databases that were only partially upgraded during the automatic migration process, delete the new database. Troubleshoot the original database according to the log diagnostic data, then perform manual migration of the original database.

   • The v9.0 migration tools do not copy any Derby database instances outside the WAS configuration tree.

     If migration does not copy a Derby database instance automatically, copy the database instance manually.

4. Manually migrate the UDDI registry if it uses a database on the Apache Derby Network Server framework.

What to do next

Read Install and configuring the SDO repository in the documentation for more information on upgrading the SDO repository application to v9.0.

Knowledge Collection: Migration planning for WAS

Apache Derby website