Verifying Apache Derby automatic migration

WAS v8.5 > Migrate, coexist, and interoperate > Migrating Data access resources > Migrating data sources
Verifying Apache Derby automatic migration

v8.5 of the application server requires Apache Derby to run at a minimal version of v10.1.x. The migration tool upgrades databases that are accessed through the embedded framework by some internal components, such as the UDDI registry. The tool also upgrades Derby instances the applications access through the embedded framework. Verify the migration results for these backend databases.

WAS supports direct customer use of the Apache Derby database in test environments only. WAS v8.5 does not support direct customer use of Apache Derby database in production environments.
The migration tool attempts to upgrade Derby database instances that are accessed through the embedded framework only. You must manually upgrade Derby instances that transact with application servers on the Network Server framework. See the topic, Upgrading Derby manually. This requirement eliminates the risk of corrupting third party applications that use the Network Server framework to access the same database instances as WebSphere Application Server.
Other applications can access Apache Derby on Network Server because the framework provides the database with a foundation of connectivity software; the embedded framework does not. Derby Network Server can transact with multiple Java Virtual Machines (JVM) or application servers concurrently, whereas Derby on the embedded framework works with only a single JVM. Clustered or coexistence implementations of Application Server require Network Server.
For database instances the applications access through the embedded framework, the automatic migration can succeed completely, fail completely, or succeed with warnings. A migration that produces warning messages does create an Apache Derby database with your data, but does not migrate all of your configured logic and other settings, such as:

keys
checks
views
triggers
aliases
stored procedures
To distinguish between a partially and a completely successful migration, verify the auto-migration results by checking both the general post-upgrade log and the individual database logs. Performing these tasks gives you vital diagnostic data to troubleshoot the partially migrated databases as well as those that fail auto-migration completely. Ultimately, you migrate these databases through a manual process.
Open the post-upgrade log of each new profile for the application server. The path name of the log is app_server_root/profiles/profileName/logs/WASPostUpgrade.timestamp.log.
Examine the post-upgrade log for database error messages. These exceptions indicate database migration failures. The following lines are an example of post-upgrade log content, in which the database error code is DSRA7600E. The migration tool references all database exceptions with the prefix DSRA.
MIGR0344I: Processing configuration file /opt/WebSphere/AppServer/Derby
/db2j.properties.

MIGR0344I: Processing configuration file /opt/WebSphere/AppServer/config/cells
/migr06/applications/MyBankApp.ear/deployments/MyBankApp/deployment.xml.

DSRA7600E: Derby migration of database instance /opt/WebSphere61/Express
/profiles/default/databases/_opt_WebSphere_AppServer_bin_DefaultDB failed, 
reason: java.sql.SQLException: Failure creating target db

MIGR0430W: Derby Database /fvt/temp/BaseXExpress/PostUpgrade50BaseFVTTest9
/testRun/pre/websphere_backup/bin/DefaultDB failed to migrate <new database name>
Call IBM WAS Support if you see a migration failure message for a Derby instance that is accessed by a WebSphere internal component (that is, a component that helps comprise WAS rather than one of the applications).
Open the individual database migration log that corresponds with each of your backend Derby databases. These logs have the same timestamp as that of the general post-upgrade log. The 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.
Examine each database migration log for errors. For a completely successful migration, the log displays a message that is similar to the following text:
MIGR0429I: Derby Database F:\temp\BaseXExpress\PostUpgrade50BaseFVTTest2\testRun
\pre\websphere_backup\bin\DefaultDB was successfully migrated. See log C:\WebSphere61
\Express\profiles\default\logs\DefaultDB_migrationLogSun-Dec-18-13.31.40-CST-2005.log
Otherwise, the log displays error messages in the format of the following example:
connecting to source db <jdbc:db2j:/fvt/temp/BaseXExpress/PostUpgrade50BaseFVTTest9
/testRun/pre/websphere_backup/bin/DefaultDB> 
connecting to source db <jdbc:db2j:/fvt/temp/BaseXExpress/PostUpgrade50BaseFVTTest9
/testRun/pre/websphere_backup/bin/DefaultDB> took 0.26 seconds

creating target db <jdbc:derby:/opt/WebSphere61/Express/profiles/default/databases
/_opt_WebSphere_AppServer_bin_DefaultDB> 
 ERROR: An error occurred during migration. See debug.log for more details.

shutting down databases 
shutting down databases took   0.055 seconds
For more data about a migration error, consult 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 a debug log is app_server_root/profiles/profileName/logs/myFulldbPathName_migrationDebugtimestamp.log.
The following lines are a sample of debug text. The lines display detailed exception data for the error referenced in the previous sample of database migration log data.
java.sql.SQLException: Database_opt_WebSphere_AppServer_bin_DefaultDB already exists. Aborting migration  at com.ibm.db2j.tools.migration.MigrateFromImpl.go(Unknown Source)
 at com.ibm.db2j.tools.migration.MigrateFromImpl.doMigrate(Unknown Source)
 at com.ibm.db2j.tools.MigrateFrom.doMigrate(Unknown Source)
 at com.ibm.ws.adapter.migration.DerbyMigrationUtility.migr
Results

The migration utility for the application server changes your Apache Derby JDBC configurations whether or not it successfully migrates the database instances that are accessed by the applications. The tool changes the class paths for the Derby JDBC provider, data source implementation classes, and data source helper classes. The following table depicts these changes:
New class information. The following table depicts those changes mentioned in the previous section.

Class type Old value New value
JDBC provider class path ${CLOUDSCAPE_JDBC_DRIVER_PATH}/db2j.jar ${DERBY_JDBC_DRIVER_PATH}/derby.jar

Where DERBY_JDBC_DRIVER_PATH is the WebSphere environment variable that defines your Cloudscape JDBC provider
Where derby.jar is the base name of the JDBC driver class file (In the environment, reference the JDBC driver class file by the full path name.)

Data source implementation class: Connection pool com.ibm.db2j.jdbc.DB2jConnectionPool DataSource org.apache.derby.jdbc.EmbeddedConnection PoolDataSource
Data source implementation class: XA com.ibm.db2j.jdbc.DB2jXADataSource org.apache.derby.jdbc.EmbeddedXADataSource
Data source helper class com.ibm.websphere.rsadapter.Cloudscape DataStoreHelper com.ibm.websphere.rsadapter.Derby DataStoreHelper
Additionally, the db2j.properties file changes:

The name app_server_root/cloudscape/dbj.properties changes to app_server_root/derby/derby.properties
Within the file, property names change from db2j.drda.* to derby.drda.*

A partial or a completely successful database migration changes the location and name of the database according to the following example:

Old database name: c:\temp\mydb
New database name: The new name includes a hash code that combines the entire path name of the old database and the migration time stamp. The new name also includes the old database name and time stamp exactly. For example:
app_server_root\profiles\profile_name\databases\my_database_hashCode_timestamp

For both partial and failed migrations, the log messages contain the exact old and new database path names that use to run the manual migration. Note these new path names precisely.

If we experience a partial migration, attempt to troubleshoot the Derby database only if we have expert knowledge of these database types. Otherwise, delete the new database. Perform the manual migration procedure on the original database, just as we do for each database that completely fails auto-migration.
After a successful database migration, reboot the database and compress tables to improve performance. See the Apache Derby documentation for instructions.

Related concepts:

Transaction type and connection behavior

Related

Upgrading Apache Derby manually

Related information:

IBM Cloudscape product web pages

Cloudscape Information Center

Apache Derby

+
Search Tips | Advanced Search

Class type	Old value	New value
JDBC provider class path	${CLOUDSCAPE_JDBC_DRIVER_PATH}/db2j.jar	${DERBY_JDBC_DRIVER_PATH}/derby.jar Where DERBY_JDBC_DRIVER_PATH is the WebSphere environment variable that defines your Cloudscape JDBC provider Where derby.jar is the base name of the JDBC driver class file (In the environment, reference the JDBC driver class file by the full path name.)
Data source implementation class: Connection pool	com.ibm.db2j.jdbc.DB2jConnectionPool DataSource	org.apache.derby.jdbc.EmbeddedConnection PoolDataSource
Data source implementation class: XA	com.ibm.db2j.jdbc.DB2jXADataSource	org.apache.derby.jdbc.EmbeddedXADataSource
Data source helper class	com.ibm.websphere.rsadapter.Cloudscape DataStoreHelper	com.ibm.websphere.rsadapter.Derby DataStoreHelper