Ant tasks for database migration

Your installation provides Ant tasks to copy the contents of an old database into the new schema, and to grant the required privileges to the database user referenced in the data source.

The following table describes the Ant tasks for migrating the database.

Table 1. Ant tasks for migration
Ant Task Purpose
gen-migrationXX-role Creates an SQL script that grants required privileges to the database user referenced in the data source. The role has select permission on all required tables of the old database. You can execute this role task against any database, not just those requiring specific privileges. However, you do not have to use the generated script with all databases.
gen-migrationXX-script Creates the SQL script used to copy the old database content into the new schema.
gen-prog-migrationXX-script To migrate part of your database until you are ready to migrate the rest.

The XX in the script name represents the version from which you are migrating. For example, use:

Note: Migration from V8.6 or V8.7 is optional, but provides the following functionality:
  • Improved database locking mechanism.
  • Larger server names.
  • Larger deployment error messages.
  • User management through the Business console.

In addition, if you do not migrate from version 8.6 and want to use the metrics with your simulations in the Business console, then you need to run an SQL script to add the domain metric for simulation.

You do not need to migrate the database incrementally. Each version provides one Ant task, which migrates your version to the current version. For example, the Ant task gen-migration71-script migrates a database from V7.1 to V8.9.0.

The Ant tasks for migration take the following parameters:

-Dserver.url=<new server url>

-DdatasourceName=<JNDI name of the new data source>

-DoldDatabaseSchemaName=<database schema name used in previous data source>

MySQL does not support database schemas. However, you can achieve the same behavior by using a different database for the new release. Therefore, with MySQL, you must call Ant tasks by using the old database name instead of the old schema name.

The Ant tasks produce SQL scripts that you can execute by using the execute-schema Ant task.

To migrate your database:
  1. Verify which datasource schema version you need to use.

    To verify which Ant task to use, go to the About page in the Enterprise console to confirm the datasource schema version.

  2. Ensure you are an administrator.
  3. Use the gen-migrationXX-role Ant task.
  4. Execute the generated script to grant to required privileges to the database user referenced in the data source.
  5. Use the gen-migrationXX-script Ant task, even if you are migrating only part of the database.

    For databases using sequences (for instance Oracle or DB2), the migration script should be executed immediately after it is generated so that the original repository is not updated after the script is generated. This is because if the sequence values to use are specified in the migration script, then they should not get updated. This restriction does not apply to databases for which sequences are not used.

  6. Execute the generated script to copy the old database content into the new schema.
If you want to migrate only part of the database, you will also need to use the gen-prog-migrationXX-script Ant task. See Migrating the database progressively for more information.

Running the migration script may require some time, and it may hit the application server timeouts if it is executed using the execute-schema Ant task. In this case, you may consider running it using your favorite database tool (for instance sqlplus for Oracle) instead of using the execute-schema Ant task.