Version 7.0 of
the application server requires Cloudscape™ or
Apache Derby to run at a minimal version of v10.1.x. During the application
server upgrade to Version 7.0,
the migration tool automatically upgrades the database instances that
are accessed through the embedded framework by some internal components,
such as the UDDI registry. The tool also attempts to upgrade Cloudscape or Derby instances that your
applications access through the embedded framework. You must verify
the migration results for these backend databases.
Before you begin
Do not use Apache Derby or Cloudscape as
a production database. Use it for development and test purposes only.
The
migration tool attempts to upgrade Cloudscape database
instances that are accessed through the embedded framework only. You
must manually upgrade Cloudscape instances that
transact with application servers on the Network Server framework.
See the topic, Upgrading Cloudscape 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 or Cloudscape on Network Server
because the framework provides the database with a foundation of connectivity
software; the embedded framework does not. Derby Network Server or Cloudscape Network Server can transact
with multiple Java™ Virtual Machines (JVM) or application
servers concurrently, whereas Cloudscape or Derby on the
embedded framework works with only a single JVM. Clustered or coexistence
implementations of Application Server require Network Server. For
more information, consult the IBM® Cloudscape Information
Center. Find the link in the following IBM Suggests
section.
About this task
For database instances that your 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 or Cloudscape 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, you must 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.
Procedure
- 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/WebSphere51/AppServer/cloudscape
/db2j.properties.
MIGR0344I: Processing configuration file /opt/WebSphere51/AppServer/config/cells
/migr06/applications/MyBankApp.ear/deployments/MyBankApp/deployment.xml.
DSRA7600E: Cloudscape migration of database instance /opt/WebSphere61/Express
/profiles/default/databases/_opt_WebSphere51_AppServer_bin_DefaultDB failed,
reason: java.sql.SQLException: Failure creating target db
MIGR0430W: Cloudscape Database /fvt/temp/51BaseXExpress/PostUpgrade50BaseFVTTest9
/testRun/pre/websphere_backup/bin/DefaultDB failed to migrate <new database name>
Important: Call IBM WebSphere Application Server Support if you
see a migration failure message for a Cloudscape instance
that is accessed by a WebSphere internal component
(that is, a component that helps comprise WebSphere Application Server rather than one
of your applications).
- Open the individual database migration log that corresponds
with each of your backend Cloudscape databases.
These logs have the same timestamp as that of the general post-upgrade
log. The logs display more detail about errors that are 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: Cloudscape Database F:\temp\51BaseXExpress\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/51BaseXExpress/PostUpgrade50BaseFVTTest9
/testRun/pre/websphere_backup/bin/DefaultDB>
connecting to source db <jdbc:db2j:/fvt/temp/51BaseXExpress/PostUpgrade50BaseFVTTest9
/testRun/pre/websphere_backup/bin/DefaultDB> took 0.26 seconds
creating target db <jdbc:derby:/opt/WebSphere61/Express/profiles/default/databases
/_opt_WebSphere51_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 WebSphere Application Server 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 that is referenced in the previous sample
of database migration log data.
java.sql.SQLException: Database_opt_WebSphere51_AppServer_bin_DefaultDB already exists. Aborting migration
at com.ibm.db2j.tools.migration.MigrateFrom51Impl.go(Unknown Source)
at com.ibm.db2j.tools.migration.MigrateFrom51Impl.doMigrate(Unknown Source)
at com.ibm.db2j.tools.MigrateFrom51.doMigrate(Unknown Source)
at com.ibm.ws.adapter.migration.CloudscapeMigrationUtility.migr
Results
- The migration utility for the application server changes your
Apache Derby or Cloudscape JDBC configurations whether
or not it successfully migrates the database instances that are accessed
by your applications. The tool changes the class paths for the Derby
or Cloudscape JDBC provider, data source
implementation classes, and data source helper classes.
Table 1. 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 your 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:
Avoid trouble: For both partial and failed migrations,
the log messages contain the exact old and new database path names
that you must use to run the manual migration. Note these new path
names precisely.
gotcha
What to do next
If you experience a partial migration, attempt to troubleshoot
the Cloudscape or Derby database only if you have expert knowledge
of these database types. Otherwise, delete the new database. Perform
the manual migration procedure on the original database, just as you
do for each database that completely fails auto-migration. See the
topic, Upgrading Cloudscape manually, for instructions.
For successfully migrated Derby
or Cloudscape instances, be aware that new
cell-scoped data sources can only be used by nodes that run version
6.0.2 or later of the application server. Earlier versions of the
product do not support the new versions of Derby or Cloudscape.
When applications on nodes that are earlier than version 6.0.2 try
to access a Cloudscape or Derby data source, the application
server will issue exceptions at run time.
After a successful
database migration, reboot the database and compress tables to improve
performance. See the Apache Derby documentation for instructions.