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:

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 the configuration of the server, operating system, database, and other items. Therefore, schedule your outage appropriately.
  • Migration of the Jazz Team Server running on IBM i is an intensive process that can take a fair amount of time depending on the size of your data being migrated. 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. 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 IBM i, run CL command CHGSYSVAL SYSVAL(QJOBMSGQFL) VALUE(*WRAP) to avoid the migration problem that might occur when the job message queue becomes full.
  • 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 is ready to use as is.
  • To check the buffer pool, do the following:
    1. Connect to the Jazz database you want to import into by typing the following command in the command prompt:
      db2 connect to <databaseName>
    2. Then, run the following command:
      db2 "select bufferpoolid, bpname from syscat.bufferpools"
      This command returns a buffer pool identifier in this format:
      BUFFERPOOLID BPNAME
      ------------ ----------------------------------
                 1 IBMDEFAULTBP
      
        1 record(s) selected.
    3. In the previous example, the buffer pool identifier is 1. Next, run the following command:
      db2mtrk -d
      This command returns data like the following example:
      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 text indicates the allocated buffer pool size for your database.
Oracle:
  • Disable recycle bin - the recycle bin tracks 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 - the statistic history tracks the run time of past methods:
    "exec dbms_stats.ALTER_STATS_HISTORY_RETENTION (0)"
    "exec dbms_stats.PURGE_STATS ( current_timestamp )"
  • Ensure that Oracle table space spans only a single file

Procedure

To start the migration:

  1. 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. To stop Jazz Team Server running on IBM i, see Starting and stopping the team server on IBM i.
  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 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 workstation screen and in 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 database before running the import tool.
    Note: The -import option logs information about the items imported and skipped, and any errors during the import.

What to do next

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

Feedback