DBUpgrade command-line utility

Use the DBUpgrade command-line utility to upgrade previous versions of database schemas and data to the current version of IBM® BPM.

The DBUpgrade command updates the following items in the databases to IBM BPM V8.6.0:

System Data toolkit
Process Portal process application
Hiring Sample tutorial process application
Topology information in the Business Process Choreographer database
Schema and data for Process Server and Performance Data Warehouse databases, except for DB2 for z/OS databases. To manually run the schema update separately, see the instructions at the end of this topic.

Notes:

Although the DBUpgrade utility updates the System Data toolkit to IBM Business Process Manager V8.6.0, it does not automatically update existing dependencies. The dependencies are updated as part of the postmigration procedures.
If you already have a version of Db2 installed and you create the deployment environment without deferring schema creation, you must have Db2® AWSE 10.5.0.0 or above. Otherwise, the database version validation will fail with an error; for example CWMCB0316E: Your database system is not the required version. The minimum supported version is 10.5.0.0 but the current version is 10.1.0.2.

You must run the DBUpgrade command once for each deployment environment.

You can also run the DBUpgrade command with the -validate option to check that your configured database user has the correct permissions to perform an upgrade.

Prerequisites

The following conditions must be met:

Before running the DBUpgrade command, make sure that the servers and cluster members are stopped.
If you are migrating from an earlier version, the user name and password are taken from the target_migration_properties_file. The user name must have various WebSphere privileges. The WebSphere primary administrative user has them all. In the source environment, you can find the primary administrative user name in the administrative console by going to Users and Groups > Administrative user roles. In the target environment, if you do not have access to the administrative console, you can find bpm.de.authenticationAlias.#.name=CellAdminAlias in the BPMConfig properties file. Use the user name and password for that alias.
In a DB2 high availability disaster recovery (HADR) environment, remove the following line from the upgradeSchema_ProcessServer.sql script in target_deployment_manager_profile/dbscripts/Upgrade/cell_name.de_name/database_type/Process_Server_database_name before running the command.
```
"ALTER TABLE psbpmdb.LSW_PO_VERSIONS ACTIVATE NOT LOGGED INITIALLY"
```
By default, the DB2 blocknonlogged parameter is set to Yes for HADR that causes failure of the ALTER TABLE statement with the NOT LOGGED INITIALLY parameter. For more information, see the blocknonlogged - Block creation of tables that allow non-logged activity configuration parameter topic.

Location

The DBUpgrade command is in the install_root/bin directory, where install_root is the installation location of IBM Business Process Manager.

The logs are saved under the profile_root/logs directory in files named DBUpgrade_TimeStamp.log and bootstrapProcesServerData.AppClusterName.log or bootstrapProcesServerData.log, where profile_root is the root of the stand-alone or deployment manager profile, or the profile directory that you specified for the profile.name property in the target_migration.properties file.

Syntax

There are two ways to run the DBUpgrade command, depending upon the task that you want to accomplish.

To migrate from an earlier version to IBM Business Process Manager V8.6.0:

DBUpgrade 
-propertiesFile target_migration_properties_file 
-backupFolder snapshot_folder

To upgrade from IBM Business Process Manager V8.5.x to V8.6.0:
- You can first run the DBUpgrade - validate command to make sure that your configured database user has the correct permissions to perform an upgrade. The bpmSchemaAdminUser needs read access to the database catalog to check the permissions of the configured database user.
```
DBUpgrade -validate
-profileName deployment_manager_profile 
[-de deployment_environment_name]
-bpmSchemaAdminUser admin_user
-bpmSchemaAdminPassword admin_password
```
- IBM BPM Advanced or Standard:
```
DBUpgrade  
-profileName deployment_manager_profile 
[-de deployment_environment_name]
```
- IBM BPM Express:
```
DBUpgrade  
-profileName stand-alone_profile 
[-de deployment_environment_name]
```

Parameters

-propertiesFile

This parameter is the full path to the target migration properties file in which you specified the configuration information for the target environment. The sample file is found in install_root/util/migration/resources/migration.properties. Ensure that the value of the target.config.property.file property is set to the full path of the configuration properties file that you used to create your target environment. You must also set the value of profile.name. This parameter is required if you are migrating.

-backupFolder

This parameter is the snapshot directory that contains the information that was extracted from the source environment by the BPMExtractSourceInformation utility. This parameter is required if you are migrating from IBM BPM Advanced or WebSphere® Process Server.

-profileName

This parameter is the name of the deployment manager profile for IBM BPM Advanced or Standard, and the stand-alone profile for IBM BPM Express. This parameter is required if you are upgrading from IBM BPM V8.5.x.

-de

This parameter is the deployment environment name. This parameter is required only if you are upgrading from IBM BPM V8.5.x and you have more than one deployment environment configured in your WebSphere cell.

-generateSQLOnly

Use this parameter to generate the SQL files without running them. You can then edit the generated SQL files manually and run the DBUpgrade command again with the -omitSQLGeneration parameter to upgrade the database using the modified files.

-omitSQLGeneration

Use this parameter to run the DBUpgrade command without generating new SQL files. If you previously ran DBUpgrade with the -generateSQLOnly parameter and manually modified the files, use this parameter to upgrade the database using the modified files.

-validate

This option validates whether your configured database user has sufficient permissions to upgrade the database. If the validation fails, the missing privileges are listed. Ask the database administrator to grant those privileges before the user runs the DBUpgrade command. The following table shows how the privileges are validated.

Database	How the command validates
DB2	Validates the authorities that are directly and indirectly granted to the Process Server and Performance Data Warehouse database user for the Create Table, Alter Table, Drop Table, Create Index, Drop Index, Create Procedure, and Drop Procedure statements. If the authority validation fails, checks the privileges that are granted directly and indirectly to the user on the schema level.
Oracle	Checks all the privileges that are granted to the Process Server and Performance Data Warehouse database user, including privileges that are granted directly and privileges that are granted through roles. Validation succeeds if all the required privileges are found. Otherwise, it fails.
SQL Server	Checks all the privileges that are granted to the Process Server and Performance Data Warehouse database user, including privileges that are granted directly and privileges that are granted through roles. Validation succeeds if all the required privileges are found. If any of the required privileges are denied, validation fails. If any of the required privileges are not granted, the command continues to check if the user is a member of one of the fixed roles: db_ddladmin, db_datareader, or db_datawriter. Validation succeeds if the user is a member of one of those fixed roles. Otherwise, it fails.

-bpmSchemaAdminUser

This parameter is a database user with permission to read the database catalog tables. This parameter is required only with the -validate option.

Database	Required privileges
DB2	read access to system tables: SYSCAT.SCHEMAAUTH, SYSCAT.ROUTINEAUTH execute privilege on built-in DB2 table functions: SYSPROC.AUTH_LIST_AUTHORITIES_FOR_AUTHID, SYSPROC.AUTH_LIST_GROUPS_FOR_AUTHID, SYSPROC.AUTH_LIST_ROLES_FOR_AUTHID
Oracle	read access to system tables: DBA_SYS_PRIVS, DBA_ROLE_PRIVS
SQL Server	read access to system tables: DATABASE_PERMISSIONS, DATABASE_PRINCIPALS, DATABASE_ROLE_MEMBERS

-bpmSchemaAdminPassword

This parameter is the password for the bpmSchemaAdminUser. This parameter is required only with the -validate option.

Examples

For migrating from IBM BPM Advanced or WebSphere Process Server:

install_root/bin/DBUpgrade.sh -propertiesFile /opt/BPM/util/migration/resources/target_migration.properties -backupFolder /tmp/snapshot

install_root\bin\DBUpgrade.bat -propertiesFile "C:\IBM BPM\util\migration\resources\target_migration.properties" -backupFolder C:\snapshot

For migrating from IBM BPM Standard or WebSphere Lombardi Edition:

install_root/bin/DBUpgrade.sh -propertiesFile 
/opt/BPM/util/migration/resources/target_migration.properties

install_root\bin\DBUpgrade.bat -propertiesFile 
"C:\IBM BPM\util\migration\resources\target_migration.properties"

For upgrading from V8.5.x:

install_root/bin/DBUpgrade.sh -profileName DmgrProfile

install_root\bin\DBUpgrade.bat -profileName DmgrProfile -de DE1

For upgrading from V8.5.x:

install_root/bin/DBUpgrade.sh -validate 
-profileName DmgrProfile -bpmSchemaAdminUser SchemaAdminUser 
-bpmSchemaAdminPassword SchemaAdminPassword

install_root/bin/DBUpgrade.sh -profileName DmgrProfile

install_root\bin\DBUpgrade.bat -validate 
-profileName DmgrProfile -bpmSchemaAdminUser SchemaAdminUser
-bpmSchemaAdminPassword SchemaAdminPassword -de DE1

install_root\bin\DBUpgrade.bat -profileName DmgrProfile 
-de DE1