+

Search Tips   |   Advanced Search

Upgrading Cloudscape manually


During the upgrade of the appserver, the migration tool attempts to upgrade instances of Cloudscapethat are accessed through the embedded framework only. 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 the appserver. You must manually upgrade database instances that are accessed through the Network Server framework. Do the same for databases that fail the automatic migration.

Do not use Apache Derby V10.1.x or Cloudscape v10.1.x as a production database. Use them for development and test purposes only. 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 on verifying the Cloudscape 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 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.

The following section consists of steps to migrate Cloudscape instances that are accessed through both the embedded framework 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 the user ID has one of the following authorities:

Otherwise, we might see runtime errors about the database instance being read-only.

 

  1. Network Server framework only: Ensure that every client of the Cloudscape database can support Cloudscape v10.1.x or Apache Derby. Application Server clients of the database must run versions 6.02.x or later of the appserver.

    In the case of mixed-node cells, remember that only nodes of V6.02 or later of the appserver can use data sources created post-migration for access to Cloudscape 10.1.x or Apache Derby. Earlier versions of WAS do not support Cloudscape 10.1x or Apache Derby. When applications on nodes that are earlier than v6.02 try to access a cell-scoped Cloudscape 10.1.x or Apache Derby data source, the appserver will issue exceptions at run time.

  2. Network Server framework only: Take the database offline. No clients can access it during the migration process.

  3. Examine a sample Cloudscape migration script that the application server provides, either db2jmigrate.bat or db2jmigrate.sh. The path of both scripts is APP_ROOT\derby\bin\embedded. We can modify the script according to the requirements of the environment. Consult the Cloudscape migration document for information about options that we can use with the script. For example, we can use the following option to specify the DDL file for the new database: 

    -DB2j.migrate.ddlFile=filename

  4. To generate database debug logs when you run the migration script, verify the debug migration trace is active. By default, this trace function is enabled. Reactivate the debug trace if it is disabled.

    1. To set the trace options in the admin console, click Troubleshooting > Logging and Tracing

    2. Select the appserver name.

    3. Click Change Log Level Details.

    4. If All Components has been enabled, we might want to turn it off, and then enable specific components.

    5. Select a component or group name. For more information see the topic on log level settings. If the selected server is not running, you will not be able to see individual component in graphic mode.

    6. 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

      See on tracing read the topic on working with trace.

    7. Select Apply, then OK.

  5. Specify the 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. Use this target database name to specify the new database, because the migrated Cloudscape data sources (updated by the WAS 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 PROFILE_HOME\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 the existing data sources to point to the new database name.

  6. When the migration process ends, examine the database migration log to verify the results. The path name of each database migration log is APP_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)
    ...

  7. 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 APP_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.

 

Next steps


Transaction type and connection behavior

 

Related tasks


Verifying the Cloudscape automatic migration
Working with trace

 

Related


Data source minimum required settings, by vendor
Log level settings

 

Related information


IBM Cloudscape product Web pages
Cloudscape migration document