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.
About this task
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 must be stopped when you migrate the repository. Migration might take a long time depending on your machine's configuration, operating system, database, and so on. 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 want to use the previous directory that was used for indexing, you must ensure that the location used in the -rebuildTextIndices repository tool 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 will be 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 indices, see -rebuildTextIndices.

Jazz Team Server 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 of version X. To stop Jazz Team Server, 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
    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.

Feedback

Did this help? You can provide feedback at Jazz.net (registration required): Comment in the forums or submit a bug