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.
Supported configurations: ![[Updated in November 2010]](../../delta.gif)
WebSphere Application
Server supports direct customer use of the Cloudscape database in
test environments only. The product does not support direct customer
use of Cloudscape database in
production environments.
![[Updated in November 2010]](../../deltaend.gif)
nov2010
sptcfg
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.