During the WebSphere Application Server v6.1.x upgrade,
the migration tool attempts 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 Application Server. 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.
Supported configurations: 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.
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..
- You can investigate incompatibilities between Cloudscape v10.1.x
and v5.1.60x (plus versions prior to v5.1.60x) by following the IBM
Suggests link to an online Cloudscape migration document.
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 article
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 application 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 Application Server clients of the database must run
versions 6.1.x or 6.02.x of Application Server.
In the case of mixed-node cells,
remember that only nodes of WebSphere Application Server v6.02 or
later can use data sources that you create post-migration for access
to Cloudscape 10.1.x. Earlier versions of the product do not support
the new Cloudscape; when applications on pre-v6.02 nodes try to access
a cell-scoped Cloudscape 10.1.x data source, Application Server issues
run-time exceptions.
- Network Server framework only: Take the database
offline. No clients can access it during the migration process.
- Examine a sample Cloudscape migration script that Application
Server provides: either db2jmigrate.bat, or db2jmigrate.sh.
The path of both scripts is install_root\derby\bin\embedded\... .
You can modify the script according to the requirements of your
environment. Consult the Cloudscape migration document at http://publib.boulder.ibm.com/epubs/html/c1894711.html 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 application 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.
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.
- Select Apply, then OK.
- Specify your old database name and the full post-migration
path of the new database name when you run the script. For
example: E:\WebSphere\AppServer\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
Application Server migration utilities) now point to the target database
name. The following sample text demonstrates how log messages display
target database names:
DSRA7600E: Cloudscape migration of database instance C:\temp\migration2\profiles\AppSrv01\
installedApps\ghongellNode01Cell\DynamicQuery.ear\EmployeeFinderDB to new database instance
C:\WebSphere\AppServer\profiles\AppSrv01\databases\C__WAS602_AppServer_profiles_AppSrv01_
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\AppServer\derby\myOldDB_migrationLog.log for progress
Migration Completed Successfully
E:\WebSphere\AppServer\derby\bin\embedded>
Otherwise,
the log displays error messages in the format of the following example:
Check E:\WebSphere\AppServer\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.