Migrating Jazz repository after upgrading Jazz Team Server

Repository migration is the process of converting the contents of the database from one format to another. Repository migration is necessary when you are upgrading the Jazz™ Team Server from version X to version Y, where version Y has schema changes.

Before you begin

You must do data migration if there are any schema changes between the two Jazz Team Server versions. You must have extracted the compressed files of Jazz Team Server of both version X and Y or have both versions installed using IBM® Installation Manager in separate package groups or on separate systems.

About this task

Generally, data migration is a two step process:

Exporting data that is there in the version X of Jazz repository to a TAR file.
Importing data from the TAR file to the version Y of Jazz repository.

You can use the repotools application for export and import operation.

Note:

Jazz Team Server must be stopped when you migrate the repository. Migration might take a long time depending on the configuration of the server, operating system, database, and other items. Therefore, schedule your outage appropriately.

Migrating the full text directory

The Jazz Team Server manages a directory outside the database that stores all data that is necessary to process full text queries. The location of the directory is configured in the teamserver.properties file under the com.ibm.team.fulltext.indexLocation property. When migrating your database and you want to use the previous indexing directory, ensure that the location in -rebuildTextIndices matches the location used by the server. When starting the server or running the -rebuildTextIndices command, the absolute path to the location of the full text directory is printed in the log files. You can check the server log file and the repotools_rebuildTextIndicies log file to compare both directories.

Tip: If the configured directory in the teamserver.properties file is a relative path, a warning is printed in the log file. It is recommended to configure this property to be an absolute directory path.

For more information about creating full text indexes, see -rebuildTextIndices.

Operating system:

On Windows®, ensure that "write caching on disk" is specified for all disks involved
On Windows, disable the "Windows Indexing Service"
Ensure that your temp directory, database, and the .tar file are on the fastest drive (ideally, striped/RAID/10 disk)
On Linux® (for DB2®), ensure that you have properly tuned the kernel according to the DB2 administration topic here: http://publib.boulder.ibm.com/infocenter/db2luw/v9r5/topic/com.ibm.db2.luw.qb.server.doc/doc/t0008238.html

Jazz Team Server setup:

Set up the following properties (in teamserver.properties) to ensure that your fastest disk is being accessed:

com.ibm.team.repository.tmpdir
com.ibm.team.scm.vcs.tmpdir
com.ibm.team.scm.tmpdir
com.ibm.team.fulltext.indexLocation

DB2:

DB2 by default tries to grow the buffer pool size as large as necessary. Unless you have changed the buffer pool to limit the growth, DB2 performs well out of the box.

To check the buffer pool, do the following:

Connect to the Jazz database you want to import into by typing the following in the command prompt:
```
db2 connect to <databaseName>
```

Then, run the following command:

db2 "select bufferpoolid, bpname from syscat.bufferpools"

This command outputs a buffer pool identifier in this format:

BUFFERPOOLID BPNAME
------------ ----------------------------------
           1 IBMDEFAULTBP

  1 record(s) selected.

In the previous example, the buffer pool identifier is 1. Next, run the following command:

db2mtrk -d

This command outputs data like the following:

Tracking Memory on: 2009/06/04 at 22:19:17

Memory for database: <databaseName>
   utilh       pckcacheh   other       catcacheh   bph (1)     bph (S32K)
   64.0K       384.0K      128.0K      128.0K      95.4M       832.0K

   bph (S16K)  bph (S8K)   bph (S4K)   shsorth     lockh       dbh
   576.0K      448.0K      384.0K      64.0K       2.5M        20.8M

   apph (269)  apph (268)  apph (267)  apph (266)  apph (265)  apph (262)
   64.0K       64.0K       64.0K       64.0K       64.0K       64.0K

   appshrh
   128.0K

The bold output indicates the allocated buffer pool size for your database.

Oracle:

Disable recycle bin - this keeps track of all elements that get deleted, fills up the disk, and can effectively cause problems. Run the following commands in sqlplus:
```
"ALTER SYSTEM SET RECYCLEBIN" = 'OFF' 
"PURGE RECYCLEBIN"
```

Disable statistic history retention - this keeps track of the runtime of past methods:

"exec dbms_stats.ALTER_STATS_HISTORY_RETENTION (0)"
"exec dbms_stats.PURGE_STATS ( current_timestamp )"

Ensure that Oracle tablespace spans only a single file

Procedure

To start the migration:

Stop Jazz Team Server of version X. To stop Jazz Team Server, run server.shutdown.sh for UNIX or server.shutdown.bat for Windows packaged in [installDir]/jazz/server.
Make a backup of the Jazz repository. The backup is just a prevention measure in case something goes wrong with migration.
1. For Derby, make an archive copy of the entire database directory.
2. For DB2, use the DB2 backup command to generate a database archive file with date and time information in the specified target directory.
Make a backup of the full text index. The location of the full text index is specified in the com.ibm.team.fulltext.indexLocation property of the teamserver.properties file.
Run repotools to export the data in the repository. The scripts, repotools.sh for UNIX, repotools.bat for Windows, and repotools.qsh for IBM i, are packaged in [installDir]/jazz/server directory.
Example: repotools -export toFile=./file_name.tar

Note: Log information and error messages are displayed on the console and a log file. The log file contains debug information about number of items exported, time to export items, errors, and other useful information. The log file is created by default in the same directory as the repotools script. You can change the location of the log file by using the logFile parameter.
You have now exported the contents of the repository to a TAR file.
Copy the teamserver.properties file from [installDir]/jazz/server of version X to [installDir]/jazz/server of version Y.
From version Y, run repotools to import the data from the TAR file to the repository.
Example: repotools -import fromFile=./file_name.tar
Important: If your database is not Derby, you must create a new database before running the import tool.

Note: The -import option logs information about the items imported and skipped, as well as errors during the import.

What to do next

You can now start the Jazz Team Server of version Y.

Latest entries in the jazz.net library on install