DBUpgrade troubleshooting

This command upgrades the databases. If you see an exception when you run this command, you can diagnose the problem by changing the log level to FINEST and running the command again.

Change the log level to FINEST as described in "Troubleshooting migration." After you run the command again, check the log file named DBUpgrade_timestamp.log. The file is found in deployment_manager_profile/logs/. If you cannot find the cause of the problem, you can provide the log to IBM support.

The command reads topology information from the properties file specified by the target.config.property.file property in the target_migration.properties file. The command reads database information from the WebSphere® Application Server data source, so if you find that the wrong database connection is used when you run DBUpgrade, check that the data source configuration is correct.

The DBUpgrade command automatically upgrades the schema and data for Process Server and Performance Data Warehouse, except for DB2 for z/OS databases.
Important: For DB2 for z/OS databases, the schema upgrade for Process Server and Performance Data Warehouse must be done manually.

DB2 SQL error

If you are running DB2, the DBUpgrade command might fail with the following database exception: 
Error executing SQL statement: DB2 SQL Error: SQLCODE=-964, SQLSTATE=57011, SQLERRMC=null
This error occurs when the database transaction log is full. Increase the size of the database transaction log and run the DBUpgrade command again.

Database customizations

If you customized the Process Server database for performance tuning, you might get exceptions when you run the DBUpgrade command. For example, if you added an index to the column of a table, the command also tries to add an index and you see a database exception similar to the following exception (for Oracle):
ORA-01408: such column list already indexed
Read the details in the DBUpgrade log and decide whether you want to keep the current index or drop the current index and create the Business Automation Workflow index later.

Not enough disk space to run the command

If you have a large amount of data, you might run out of disk space when you run the DBUpgrade command. This command migrates the BLOB data in the LSW_BPD_INSTANCE_DATA, LSW_TASK_EXECUTION_CONTEXT table, and also reorganizes the database. It requires about twice as much disk space as the original database.

DB2
With a DB2 database, you might see errors similar to the following error:
Executing upgrade step: Enable LOGGED for LOB columns
Error executing SQL statement: DB2 SQL Error: SQLCODE=-2216, SQLSTATE=01H52, SQLERRMC=-289, DRIVER=4.11.69
SQL statement that failed: call sysproc.admin_cmd('reorg table LSW_BPD_INSTANCE_DATA')
Make sure that there is enough free space on the database table space disk.
Oracle
With an Oracle database, you might see errors similar to the following error:
java.sql.BatchUpdateException: ORA-01653: unable to extend table schema_name.LSW_TASK_EXECUTION_CONTEXT by 1024 in tablespace tablespace_name
If the table space was set to AUTOEXTEND size, make sure that there is enough free disk space on the table space disk. If the table space was not set to AUTOEXTEND size, you might need to resize or add another data file.

Out-of-memory error

If you get an out-of-memory error that indicates too many or too large data records, you can increase the heap size of the JVM for the DBUpgrade command, or decrease the number of records to be updated as a batch.
  • To increase the heap size of DBUpgrade, you can configure it in the install_root/util/dbUpgrade/upgrade.properties file. For example:
    JVM_HEAPSIZE_OPTIONS="-Xms512m -Xmx2048m"
$JAVA_EXE $JVM_HEAPSIZE_OPTIONS -cp $CLASSPATH
    Or, you can increase the heap size as follows when you create the Java process. For example:
    %JAVA_HOME%\bin\java" -Xms512m -Xmx2048m
  • To decrease the number of records to be updated as a batch, configure the value of database.batch.size in the install_root/util/dbUpgrade/upgrade.properties file. For example: 
    database.batch.size=1000
    Lowering the value requires less memory but also lowers performance.

Low performance

If you are migrating from a version earlier than V8.0 and have an issue with low performance, and if you find that the database server input and output is not the issue, you can try increasing the number of threads to handle serializing and deserializing Java objects and updating the database. Complete the following steps:
  1. Open the install_root/util/dbUpgrade/upgrade.properties file.
  2. Increase the value of the worker.thread.size property. By default, the value is 4. The maximum number of threads depends on the processor number of the operating system that has IBM® Business Automation Workflow installed.

Manually running the schema upgrade for the Process Server and Performance Data Warehouse databases

By default, DBUpgrade updates both the database schema and the data for the Process Server and Performance Data Warehouse databases. If you want your database administrator to run the schema upgrade manually for these two databases, complete the following steps to separate the schema and data updates:
  1. Open the upgradeSchema_ProcessServer.sql file in target_deployment_manager_profile/dbscripts/Upgrade/cell_name.de_name/database_type/Process_Server_database_name.
  2. Find the phases in the file that correspond to your source. Each phase starts with /* START of phase ProcUpgradeToversion */ and ends with /* END of phase ProcUpgradeToversion */.

    For example, if your source version is V7.5.1, the database is upgraded to V8.0.0 first, and then to V8.0.1, V8.5.0, V8.5.5, and finally V8.5.6. In that case, you must copy the SQL statements from /* START of phase ProcUpgradeTo751 */ to the end of the file.

  3. Run the SQL statements in your preferred database tool to perform all the database schema updates.
  4. Open the upgrade.xml file in install_root/util/dbUpgrade. Search in the file for 
    <sysproperty key="data.upgrade" value="false" />
    By default, the value of the data.upgrade property is false, which means that both schema and data are upgraded. If the database schema has already been upgraded manually and you want to upgrade the data only, change this value to true before you run the DBUpgrade command. DBUpgrade will skip the schema upgrade and do the data upgrade only.