WebSphere Application Server Version 6.1.x requires Cloudscape
to run at a minimal version of v10.1.x. (Note that Cloudscape v10.1.x is comprised
of the code base from Apache Derby Version 10.1.) During the Application Server
v6.1.x upgrade, 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 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 Cloudscape v10.1.x as a production
database. Use it for development and test purposes only.
Learn more: The new version of Cloudscape combines the Derby runtime with
additional benefits, such as IBM Quality Assurance (QA) and national language
support (NLS). For information about the Cloudscape v10.1.x open source code
base, see the Cloudscape product Web pages link in the following IBM Suggests
section.
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 Upgrading Cloudscape manually article.)
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 Cloudscape
on Network Server because the framework provides the database with a foundation
of connectivity software; the embedded framework does not. Cloudscape Network
Server can transact with multiple Java Virtual Machines (JVM)s (or application
servers) concurrently, whereas Cloudscape 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 a Cloudscape v10.1.x 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 WebSphere Application Server
Version 6.1x profile. The path name of the log is WAS_HOME/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 WAS_HOME/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 WAS_HOME/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
What to do next
If you experience a partial migration, attempt to troubleshoot the
new v10.1.x database only if you have expert knowledge of Cloudscape. 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.
Consult
Upgrading Cloudscape manually for instructions.
For
successfully migrated 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 Cloudscape; when applications on pre-version 6.0.2 nodes try to access
a Cloudscape 10.1.x data source, the application server will issue exceptions
at run time.