During the WebSphere® ESB version 6.2 upgrade,
the migration tools attempt to upgrade instances of Cloudscape that are accessed through the
embedded framework only. (The new version of Cloudscape is version 10.1.x, which is
based on Derby.) The automatic upgrade excludes Cloudscape instances that transact with
applications through the Network Server framework. This exclusion
eliminates the risk of corrupting third party applications that access
the same database instances as WebSphere ESB.
You must manually upgrade database instances that are accessed through
the Network Server framework. Do the same for databases that fail
the automatic migration.
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 instances of Cloudscape that
are accessed through the embedded framework, determine which instances
completely failed the automatic upgrade process and which ones were
only partially upgraded. The topic
Verifying the Cloudscape v10.1.x automatic migration documents how to uncover
database errors and diagnostic data from various migration logs. 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.
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 on the original
database.
About this task
The following section consists of steps to migrate Cloudscape instances that
are accessed through both frameworks: the embedded as well as the
Network Server framework. Steps that apply only to the Cloudscape Network Server framework are
marked accordingly. As a migration best practice, ensure that your
user ID has one of the following authorities:
- Administrator of the server that accesses the Cloudscape instance
- A umask that can access the database instance
Otherwise, you might see runtime errors about the database instance
being read-only.
Procedure
- Network Server framework only: Ensure that every
client of the Cloudscape database
can support Cloudscape v10.1.x. WebSphere ESB clients
of the database must run versions 6.0.1.x or higher of WebSphere ESB.
- Network Server framework only: Take the database
offline. No clients can access it during the migration process.
- Examine a sample Cloudscape migration
script that WebSphere ESB provides. Depending on your operating system, WebSphere ESB provides
one of the following migration scripts:

On Linux® and UNIX® platforms: Use the db2jmigrate.sh script,
located in the following directory: install_root/derby/bin/embedded/...
On Windows® platforms:
Use the db2jmigrate.bat script, located in the following
directory: install_root\derby\bin\embedded\...
You can modify the script according to the requirements
of your environment. Consult Migrating IBM Cloudscape to Version 10 for
information about options that you can use with the script. For example,
you can use the option -DB2j.migrate.ddlFile=filename to
specify the DDL file for the new database.
- To generate database debug logs when you run the migration
script, ensure that the debug migration trace is active. By default, this trace function is enabled. Reactivate the debug
trace if it is disabled.
- To set the trace options in the administrative console,
click Troubleshooting > Logging
and Tracing in the console navigation tree.
- Select the server name.
- Click Change Log Level Details.
- Optional: If All Components has
been enabled, you might want to turn it off, and then enable specific
components.
- Optional: Select a component or group name.
For more information see Log level settings in the WebSphere Application Server
Network Deployment, version 6.1 Information
Center. If the selected server is not running, you will not be able
to see individual component in graphic mode.
- Enter a trace string in the trace string box. In
this case, enter one of the following:
- all traces*=all
- com.ibm.ws.migration.WASUpgrade=all
For more information on tracing read Working with trace in the WebSphere Application Server
Network Deployment, version 6.1 Information
Center..
- Select Apply, then OK.
- Specify your old database name and the full postmigration
path of the new database name when you run the script. For
example: E:\WebSphere\ProcServer\derby\bin\embedded>db2jMigrate.bat myOldDB myNewDB The logs from the automatic migration provide the exact path
names to specify for both the old database and the target database.
You must use this target database name to specify the new database,
because your migrated Cloudscape data
sources (updated by the WebSphere ESB migration
utilities) now point to the target database name. The following sample
text demonstrates how log messages display target database names:
Cloudscape migration of database instance C:\temp\migration2\profiles\Srv01\
installedApps\ghongellNode01Cell\DynamicQuery.ear\EmployeeFinderDB to
new database instance C:\WebSphere\ESB
\profiles\Srv01\databases\C__WAS602_ProcServer_profiles_ProcSrv01_
installedApps_ghongellNode01Cell_DynamicQuery.ear_
EmployeeFinderDB failed, reason: java.sql.SQLException:
Failure creating target db
For instances of Cloudscape that are accessed through the
Network Server framework, input any name that you want for the new
database. Remember to modify your existing data sources to point to
the new database name.
- When the migration process ends, examine the database migration
log to verify the results. The path name of each database
migration log is install_root/logs/derby/myFulldbPathName_migrationLog.log.
For
a successful migration, the database migration log displays a message
that is similar to the following text:
Check E:\WebSphere\ESB\derby\myOldDB_migrationLog.log for progress
Migration Completed Successfully
E:\WebSphere\ESB\derby\bin\embedded>
Otherwise,
the log displays error messages in the format of the following example:
Check E:\WebSphere\ESB\derby\myOldDB_migrationLog.log for progress
ERROR: An error occurred during migration. See debug.log for more details.
ERROR XMG02: Failure creating target db
java.sql.SQLException: Failure creating target db
at com.ibm.db2j.tools.migration.MigrationState.getCurrSQLException(Unknown
Source)
at com.ibm.db2j.tools.migration.MigrateFrom51Impl.handleException(Unknown
Source)
at com.ibm.db2j.tools.migration.MigrateFrom51Impl.go(Unknown Source)
at com.ibm.db2j.tools.migration.MigrateFrom51Impl.main(Unknown Source)
at com.ibm.db2j.tools.MigrateFrom51.main(Unknown Source)
- For more data about a migration error, consult the debug
log that corresponds with the database migration log. The
full path name of a debug log file is install_root/logs/derby/myFulldbPathName_migrationDebug.log
The
following lines are a sample of debug text.
sourceDBURL=jdbc:db2j:E:\WebSphere\myOldDB
newDBURL=jdbc:derby:e:\tempo\myNewDB
ddlOnly=false
connecting to source db <jdbc:db2j:E:\WebSphere\myOldDB>
connecting to source db <jdbc:db2j:E:\WebSphere\myOldDB> took 0.611 seconds
creating target db <jdbc:derby:e:\tempo\myNewDB>
creating target db <jdbc:derby:e:\tempo\myNewDB> took 6.589 seconds
initializing source db data structures
initializing source db data structures took 0.151 seconds
recording DDL to create db <E:\WebSphere\myOldDB>
recording DDL to create db <E:\WebSphere\myOldDB> took 5.808 seconds
Results
As indicated in the previous steps, the database migration
log displays either a
Migration Completed Successfully message,
or a message containing migration failure exceptions.
What to do next
- For databases that fail migration, troubleshoot according to the
logged error data. Then rerun the migration script.
- To access successfully upgraded databases through the embedded
framework, modify your data sources to point to the new database names.
- To access successfully upgraded databases through the Network
Server framework, you can use either the DB2® Universal
JDBC driver or the Derby Client JDBC driver.