Migrating to an External Database

By default, TeamCity runs using an internal database that uses the HSQLDB database engine. The internal database suits evaluation purposes since it works out of the box and requires no additional setup. However, we strongly recommend using an external database as a back-end TeamCity database in a production environment.

This section covers:

TeamCity supports the following external databases:

• MySQL,
• Oracle,
• PostgreSQL,
• Microsoft SQL 2005.

Please refer to Setting up an External Database page for the database-specific configuration steps. If you want to start using external database from the first TeamCity start, these are the only steps you need.

If you were using TeamCity with the internal storage engine, there are two ways to switch to an external database:

• Switch with no data migration: build configurations settings will be preserved, but not the historical builds data or users.
• Full Migration: all the data is preserved except Inspections and Duplicate build results (and any database-stored data provided by the third-party plugins).

  Database migration cannot be combined with server upgrade. If you want to upgrade at the same time, you should first upgrade (run the new version of TeamCity) and then migrate to another database.

Switching to Another Database

To switch to another database without saving the build history or user data:

1. Install and set up an external database.
2. Shut down the TeamCity server.
3. Create a backup copy of the <TeamCity data directory> used by the server
4. Clean up the system folder: you must remove messages and artifacts folders from /system folder of your <TeamCity data directory>; you may delete old HSQLDB files: buildserver.* to remove the no longer needed internal storage data.
5. Start the TeamCity server.

Full Migration

TeamCity supports HSQLDB, MySQL, Oracle, PostgreSQL and Microsoft SQL Server 2005; the migration tool can move data between any of these databases.

The target database must be empty before the migration process (it should NOT contain any tables).

To migrate all your existing data to a new external database:

1. Set up an external database to be used by TeamCity. You can refer to Setting up an External Database for information on how to set up a TeamCity-specific. (At this point you should only create and configure the database, do not modify any TeamCity settings at this time).
2. Shut the TeamCity server down.
3. Create a backup copy of the <TeamCity data directory> used by the server
4. If the database driver is not bundled with TeamCity (refer the database properties table below, and place the appropriate driver into the TeamCity WEB-INF/lib directory. The following instructions refer to the driver as <DRIVER_JAR_NAME>.
5. Edit the <TeamCity home>/bin/dbMigration.properties file, entering correct values for the source and target database. Ensure all the properties are supplied and only the necessary lines are uncommented (single-line comments are designated by # character)
6. Run the migration tool (see below)
7. Upon the successful completion of the database migration, a database.properties file will be created. migrateDB script will automatically copy it into config directory of <TeamCity data directory>.
8. Edit <TeamCity data directory>/config/database.properties file according to the settings of the target database as described in the appropriate section of Setting up an External Database page.
9. Additionally a version.dat file will be created. migrateDB script will automatically copy it into system directory of <TeamCity data directory>.
10. Start TeamCity server. This should be the same TeamCity version that was run last time (TeamCity upgrade should be performed as a separate procedure).

Databases Properties Table

Sample dbMigration.properties file residing in the bin directory contains sections for several databases.

Running the Migration Tool

You can use the migrateDB.bat/migrateDB.sh script located in the <TeamCity home>\bin directory. Just run the script and follow the instructions.

Generally, you would need to run the script with single migrate parameter to perform the migration and move the generated configuration files into <TeamCity data directory>.

Troubleshooting

• If you encounter an "out of memory" error, try increasing the number in the -Xmx512m parameter in the migrateDB script. On a 32-bit platform the maximum is about 1300 megabytes.

Alternative approach is to run HSQLDB in standalone mode via

java -Xmx256M -cp ..\webapps\ROOT\WEB-INF\lib\hsqldb.jar org.hsqldb.Server -database.0
<TeamCity data directory>\system\buildserver -dbname.0 buildserver

and then running the Migration tool pointing to the database as the source: jdbc:hsqldb:hsql://localhost/buildserver sa ''

• If you run into "The input line is too long." error while running the tool (e.g. this can happen on Windows 2000), please change the script to use alternative classpath method.
  For migrateDB.bat, remove the lines below "Add all JARs from WEB-INF\lib to classpath" comment and uncomment the lines below "Alternative classpath: Add only necessary JARs" comment.

See Also:

• Concepts: TeamCity Data Directory
• Installation and Upgrade: TeamCity Data Backup | Setting up an External Database