Migrating the Jazz repository after upgrading the Jazz Team Server for System z

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 for System z from version X to version Y, where version Y has schema changes. Repository migration is also required if you are upgrading from Rational Team Concert™ to Rational Team Concert for System z®.
You must do data migration if there are any schema changes between the two Jazz Team Server for System z versions. You must have extracted the compressed files of Jazz Team Server for System z of both version X and Y or have both versions installed using IBM® Installation Manager in separate package groups or on separate systems.
Generally, data migration is a two step process:

repository migration diagram

You can use the repotools application for export and import operation.
Note: Jazz Team Server for System z must be stopped when you migrate the repository. Migration might take a long time depending on your system's configuration, operating system, database, and so on. Therefore, schedule your outage appropriately. For specific instructions on how to import and export databases on z/OS®, see Upgrading from Rational Team Concert for System z 1.0.1 on z/OS in Upgrading to Rational Team Concert for System z 2.0.0.2.

Jazz Team Server for System z migration is a very intensive process that can take a fair amount of time depending on the size of your data being migrated. Here is a checklist of things to look out for to avoid common pitfalls.

Operating system:
Jazz Team Server setup:
  • Setup 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 disabled this, DB2 should perform well out of the box.
  • To check the buffer pool, do the following:
    1. Connect to the Jazz database you want to import into by typing the following in the command prompt:
      db2 connect to <databaseName>
    2. Then, run the following command:
      db2 "select bufferpoolid, bpname from syscat.bufferpools"
      This will output a bufferpool identifier in this format:
      BUFFERPOOLID BPNAME
      ------------ ----------------------------------
                 1 IBMDEFAULTBP
      
        1 record(s) selected.
    3. In the above example, the buffer pool identifier is 1. Next, run the following command:
      db2mtrk -d
      This will output data similar to 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

To start the migration:

  1. Stop Jazz Team Server for System z of version X. To stop Jazz Team Server for System z, run server.shutdown.sh for Linux or server.shutdown.bat for Windows packaged in [installDir]/jazz/server.
  2. 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.
  3. 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.
  4. Run repotools to export the data in the repository. The scripts, repotools.sh for Linux and repotools.bat for Windows, 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.
  5. Copy the teamserver.properties file from [installDir]/jazz/server of version X to [installDir]/jazz/server of version Y.
  6. From version Y, run repotools to import the data from the TAR file to the repository.
    Example: repotools -import fromFile=./file_name.tar
    Note: The -import option logs information about the items imported and skipped, as well as errors during the import.
You can now start the Jazz Team Server for System z of version Y.

Feedback