How to Copy a 5.1 or 5.2 StarTeam Repository with a SQL Database Backend.



How to Copy a 5.1 or 5.2 StarTeam Repository with a SQL Database Backend.


Information in this Brief applies to:

  • StarTeam 5.1 and 5.2 Server with a SQL Server 2000 Database
  • Microsoft Windows (all supported)


Sometimes it may be important to move or copy a StarTeam Repository or its parts to a new Physical Server machine. To successfully achieve this goal you will need to copy all the essential StarTeam Repository and Database files to the target destination recreating the same configuration on a new machine. It is recommended that the Repository be copied as opposed to moved, to minimize the down time and assure that the target destination is fully functional before deleting the original repository files.

Please carefully test your modified repository configuration before disabling or deleting the old repository and configuration.

The steps for moving a 5.1 or 5.2 repository are slightly different than moving 3.x and 4.x repositories.


It is best, to move all of the repository to the same relative location. For example, on a Windows platform, you would want to copy the entire repository from its old location C:\Starteam_Repository on the original server machine to the new Starteam server at the same relative location C:\Starteam_Repository. The StarTeam Repository is the startup path location for the Starbase Server configuration, it is where the Server.Log will be created and all of the Vault Archive Files, Attachments and Vault Cache files are kept.

1. Before you move a Repository, make certain all the appropriate Repository items are backed up. The back up of the Database on SQL Server and the File System (Attachments, Logs and Vault files) should all be backed up at the same time. It is important that this back up occurs while StarTeam is either locked or ideally, not running so no one is using the Starbase server.

1a. Make sure that you are backing up the database at the same time you are copying the Repository, it is imperative that these two separate parts remain completely synchronized.

2. Verify and note the Repository path and the relative location of all the folders and child folders. Once you change this information in StarTeam it may be difficult to locate the files and folders you need to move.

To verify the startup path and folder locations:

2a. Display the Server Administration dialog by doing one of the following:

2a i. From the StarTeam Client, select Tools\Server Administration from the menu.
2a ii. On the computer where Starbase Server is installed, start the Server Administration tool.

2b. From the Server Administration dialog?s left pane, select the server configuration you anticipate moving.
2c. Click the Configure Server button. The Starbase Server Configuration dialog opens.
2d. Make a note of the path information in the following text boxes:

2d i. General Tab: Server Startup Log Path and Attachments Path
2d ii. Vault tab: Vault Path, Disk Cache Path, and Archive Path

2e. At this time it is important to also open the "Server Tools" application, by going to the Starteam Server machine, go to the Windows, Start -> Programs -> Starteam Server -> Starteam Server option, make a note of the information from the Properties button under the Database tab: Database server/DSN.

3. Make certain that Starbase server is installed on the target system. Ensure the Starbase server is not running.

4. Copy all the important files and folders to the target destinations. These files/folders should include:

4a. StarbaseServer.ini (by default located in the installation folder of Starbase Server). You will need this file moved to the different server computer at the same time as the copy of the Repository.
4b. The StarTeam Vault folder and all its folder/file contents (Archive and Cache folders and contents)
4c. The StarTeam Attachments folder and all its file contents
4d. With MS SQL, you will need to make sure that the Database Server is backed up and restored to the new SQL Server if you are also changing the SQL Server at this time.

5. When setting up your SQL Server to restore this Starteam Server configuration on, there are a few things that you"ll need to take into account. Borland recommends installing StarTeam Server on a dedicated application server and the database on a separate server as you are well aware.

  • Please follow the recommendations outlined by Microsoft for the hardware specification for the SQL Server version you decide to implement, modified by the number of expected Starteam users. If you plan to run Starteam Server and SQL Server on the same machine, please remember that the system requirements demanded by this machine are going to literally be a combination of the requirements of these 2 systems. You can install SQL Server with default settings of your Starteam or Dedicated SQL Server, your Authentication method can be either Mixed Mode or identification provided by the user.
  • Borland currently recommends Windows 2000 Service Pack 3 for both Windows 2000 and Professional, and we highly recommend SQL Server 2000 with Service Pack 3 because of the presence of the "Slammer Virus".

Note** When you copy the database it was most likely backed up into 1 file that contains the data and log files with which the database was created. SQL Server as well as many other systems was likely set up with a Log file and a Data file, but quite often they can be set up with multiple files. The first step you need to do when restoring this database is to create the database with the same number of files.

Open the Enterprise Manager and drill down to the Server. Under that you should see a list of Folders, the top one is called "Databases". Right click on the Databases folder and select the "New Database" option. A "Database Properties" dialog will appear, enter a name for the Database, you must avoid strange characters such as full stops, tildes etc. and spaces, they will not be acceptable to connection protocol.

You can choose a custom location for the Data and Log files. In this example I have a database with 3 Log and Data files, so there must be 3 of each:

Log files:


Each file in this example has unrestricted file growth, with an allocated starting space of 500MB.

When you restore the database you will right click the cylindrical database Icon for the new Database and choose the option for "All tasks" and pick the option from that list for Restore Database. On the restore DB dialog you will have to click the "from device" option and then the "select device" option.

Hit the "Add" button and browse to a location on this machine where the Starteam.bak file is residing. Hit OK to return to the restore DB screen. Go to the options tab. You will need to click the option to "force restore over existing database" and under the column for "move to physical file name" you will have to describe the location and names of the new files you just created for this SQL database. When you see the list the first time you will see under this column X:\Program Files\Microsoft\MSSQL\... Etc. change this to location you chose for your test and append this location with the names you created the files with.

After this is done the database should be restored with no errors.

Next, enter the contents of the enclosed StarbaseServer.ini into your StarbaseServer.ini. Then verify or recreate the ODBC connection on the SQL Server:

5a. From the Windows Start button go to Settings and navigate to the Control Panel and to the Data Sources ODBC.
5b. In the ODBC controls, select the System DSN tab.
5c. Click on the Add button.
5c i. Select the SQL Server driver from the list.
5c ii. Click on Finish
5c iii. Enter the Data Source Name. Make sure you select the Starteam Database from the drop down list on the third page.

6. At this time, because you have copied the StarbaseServer.ini from the original Server Machine, the configuration will show up in Server Tools as it did on the original machine. Select the Configuration which you have copied/relocated. You may need to edit some of the fields in the INI file, all the relevant fields can be edited through the Server Tools Application via the "Properties" button and the "Start with override" button.

After all the Starteam Server and Database components have been copied/relocated to the new machine do not create a "new configuration" of the same name and point it to the original database, as it will not start, if the Starteam Configuration does not appear in the list of configurations, please re-copy the StarbaseServer.ini to the new machine.

Take these steps before starting StarTeam.

6a. Click on the Configuration Properties button.
6b. With the General tab selected, click on the Verify. You generally need to know the Cipher Phrase to successfully complete this step.

Contact StarTeam Support if you do not know your Cipher Phrase. Just login to and create a case with the subject line "Cipher Name Decryption Requested" and just attach the StarbaseServer.ini file with an official request for Starbase to decrypt the Cipher Phrase from the file enlcosed and send it back.

6c. After a successful verification of the Cipher Phrase, select the Database tab and click on the Verify Connection. If you have problems with this check your connectivity with the Database either through the ODBC/DSN. If you still have problems contact StarTeam Support at (714) 445-4460.
6e. You can now start the Starbase Server.

7. If you have copied one or more of the repository folders to different relative locations you will need to redefine those locations before the server is started.

7a. From Server Tools, click on the "Start with Override..." button.
7b. Browse to or type the new path information for the repository items.
7c. Click on OK.
7d. Test to make certain that your move is totally successful. Consider adding a test file to a project and check the archive directory for a new file entry matching the appropriate date/timestamp.

While it is usual to move the entire repository, you can move individual parts:

The Attachments Path. StarTeam allows you to attach files to change requests, tasks, or topics. These files are stored in a separate folder on the server. By default this folder is the Attachments folder and is a child of the folder specified for the repository. It has three child folders whose names should not be changed: Changes_Attachments (for change requests), StTasks_Attachments (for tasks), and Topics_Attachments (for topics). If you move this folder, you must also move the currently attached files to that new location. Do so while the server configuration is shut down.

The Vault Path. By default this folder is the Vault folder and is a child of the folder specified for the repository. The Vault folder initially has two child folders: one for the disk cache and the other for the archive. Changing the Vault path does not change the path to either the disk cache or the archive. You do not have to move the Cache and Archive folders unless you change their paths, too.

The Disk Cache Path. The disk cache folder contains copies of the most recently checked-out file revisions. If a user checks out a revision that is already in the cache, the file is copied from the cache rather than from the archive. This speeds up the check out process. The maximum cache size determines how many files can be stored. By default this folder is the Cache folder and is a child of the folder specified for the vault. If you move this folder, you can (but you don?t have to) move the cached files to the new location. If you move these files, do so while the Starbase Server is down. You may want to resize the cache and reset its refresh interval at this time as well.

The Archive Path. The archive folder stores file revisions. By default this folder is the Archive folder and is a child of the folder specified for the vault. If you move this folder, you must also move the archived files to that new location. Do so while the server configuration is shut down.

If you change any of these folder locations, you must restart the server configuration. If you move the entire repository, you usually change all of these folder locations and the startup location.

Old KB# 28380
Comment List