The migration tools migrate any IBM® Cloudscape® database instances to Apache
Derby instances in the new configuration, and they copy any Apache
Derby instances that are stored in the previous release's WebSphere® Application Server configuration
tree to the new release's configuration tree. After you use the migration
tools, you should verify the results of the database migration and
manually migrate any Cloudscape database instances
or copy any Derby database instances that are not automatically migrated
or copied by the tools.
About this task
WebSphere Application Server Version 7.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.
For help, read Troubleshooting migration.
Avoid trouble:
- 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 you roll back to the
previous release, any updates to the database that you made after
migration are not reflected in the previous installation.
- Before you migrate an application server with a Derby database,
shut down the application server that you are migrating to the newer
version. If you migrate a running application server using the WASPreUpgrade command
with a Derby database that is stored under a profile, you might incur
data loss or corruption. You might encounter one of the following
problems, which do not manifest themselves until after the application
server is fully migrated and restarted:
- The application server lists Derby database access issues in the
log files.
- Database access issues are manifested by applications, services,
or both.
- Database information is missing. The data loss occurs because
the WASPreUpgrade command takes a snapshot of the
Derby database during the migration process.
You can use the -requireEmbeddedDBMigration parameter
for the WASPreUpgrade command to avoid data loss
or database corruption. By default, the parameter value is set to true.
With this default setting, if an exception occurs during the migration
process for embedded databases, the WASPreUpgrade command
fails. Then, you can evaluate the exceptions before reattempting the
migration process. However, you might continue to encounter exceptions
if the database is in use, encryption is enabled, or authentication
is enabled. For more information, see the WASPreUpgrade command
documentation.
gotcha
Procedure
- Migrate the configuration to Version 7.0.
- Verify the automatic migration of Cloudscape database
instances or copying of Derby database instances.
When
you migrate from WebSphere Application Server Version 5.1.x
or Version 6.x to Version 7.0, the migration tools automatically upgrade
Cloudscape or Derby database instances that are accessed through the
embedded framework by some internal components such as the UDDI registry.
The tools also attempt to upgrade Cloudscape or
Derby instances that your applications access through the embedded
framework. You must verify these migration results after running the
migration tools.
- To distinguish between a partially and a completely successful
Cloudscape-to-Derby migration, verify the automatic-migration results
by performing the following tasks:
- 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.
- 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 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.
- Look at 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 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, you 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 you must use to run the manual migration. Note these new path
names precisely. For more information, see the verifying the Cloudscape automatic migration documentation.
- Verify that any Derby database instances that are stored in the
previous release's WebSphere Application Server
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.
.
- Manually migrate Cloudscape database instances
or copy Derby database instances where necessary.
- The Version 7.0 migration tools do not attempt to migrate database
instances that transact with applications through the Cloudscape Network
Server or 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 WebSphere Application
Server.
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.
For more information, see the Upgrading Cloudscape manually
documentation.
- The Version 7.0 migration tools do not copy any Derby database
instances outside the WebSphere Application Server
configuration tree.
If migration does not copy a Derby database
instance automatically, copy the database instance manually.
- Manually migrate your UDDI registry if it uses a database
on the Cloudscape Network Server or the Apache
Derby Network Server framework.
For more information,
see the Migrating the UDDI registry documentation.
What to do next
Service integration bus-enabled Web services use a Service
Data Objects (SDO) repository for storing and serving WSDL definitions.
If you migrate a configuration that uses a Cloudscape database as
the SDO repository, the SDO application will still be configured to
use Cloudscape in the new configuration. Migration converts the Cloudscape
database to Derby, but you must still update any SDO application's
backend ID to use the new database. After you migrate all of the
nodes on a server with an SDO repository application that uses Cloudscape,
perform the following actions to reset the database type used by the
SDO application on the new configuration to Derby:
- Read about the basic usage for the installSdoRepository.jacl script
inside the script file.
- Run the installSdoRepository.jacl script by changing to the app_server_root/bin/ directory
and running the following command:
wsadmin.extension -f app_server_root/bin/installSdoRepository.jacl -editBackendId DERBY_V10
For more information on upgrading the SDO repository application
to Version 7.0, see the following documentation:
- Installing and configuring the SDO repository
- Verifying Cloudscape automatic migration
- Upgrading Cloudscape manually
- Migrating the UDDI registry