TeamCity 5.0 Help

Migrating to an External Database

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

This section covers steps you need to perform if you evaluated TeamCity with internal database and need to switch to an external database to prepare your TeamCity installation for production use.

Since TeamCity 5.0, maintainDB command line utility is used to migrate data between databases. maintainDB.[cmd|sh] shall/batch script is located in the <TeamCity Home>/bin directory and is used for migrating as well as for Backing Up TeamCity Data and Restoring TeamCity Data from Backup TeamCity data.

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

  • db_switch with no data migration: build configurations settings will be preserved, but not the historical builds data or users.

  • db_full: all the data is preserved except Inspections and Duplicate build results (and any database-stored data provided by the third-party plugins).

Internal note as to why: Target database is initialized by the code (so it corresponds to the version of the TeamCity used). So, both target and source database should be from the same TeamCity database version.

Switching to Another Database

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

  1. Install and Setting up an External Database.

  2. Shut down the TeamCity server.

  3. TeamCity Data Backup 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, Microsoft SQL Server 2005, 2008 and Sybase; the maintainDB tool can move data between any of these databases.

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

  1. Setting up an External Database to be used by TeamCity. At this point you should only create and configure the database and also Setting up an External Database the database driver into TeamCity. Do not modify any TeamCity settings at this time.

  2. Shut the TeamCity server down.

  3. Create new properties file with a custom name (for example, database.<database_type>.properties) for the target database according to its settings from a corresponding template (<TeamCity Data Directory>/config/database.<database_type>.properties.dist), entering actual values. Place this file into a temporary directory to your liking.

  4. Run the maintainDB tool with the migrate command and specify the absolute path to the newly created target database properties file with -T option:

    maintainDB.[cmd|sh] migrate -T <path to database.properties file>

Upon the successful completion of the database migration, a database.properties file will be replaced with the file specified via -T option. The old database.properties file will be automatically re-named in the following format: database.properties.before.<timestamp>.

  1. 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

DB Name

Driver Class Name

Driver jar Name

Driver is Bundled

JDBC URL format

MySQL

com.mysql.jdbc.Driver

mysql-connector-java-5.1.12-bin.jar

no, download page

jdbc:mysql://<host>[:<port>]/<database>

PostgreSQL

org.postgresql.Driver

postgresql-8.2-505.jdbc3.jar

no, download page

jdbc:postgresql://<host>[:<port>]/<database>

Oracle

oracle.jdbc.driver.OracleDriver

ojdbc14.jar orai18n.jar

no, grab files ojdbc14.jar and orai18n.jar from Oracle server installation or download them form download page

jdbc:oracle:thin:@<host>:<port>:<database>

HSQLDB

org.hsqldb.jdbcDriver

hsqldb.jar

yes

jdbc:hsqldb:hsql://<host>[:<port>]/<database>

MS SQL

net.sourceforge.jtds.jdbc.Driver

jtds-1.2.2.jar

no, download page

jdbc:jtds:sqlserver://<host>[:<port>]/<database name>

Sybase

com.sybase.jdbc3.jdbc.SybDriver

jconn3.jar

no, grab it from <Sybase home directory>/jConnect-6_0/classes

jdbc:sybase:Tds:<host>:<port>/<database_name>

Running the maintainDB Tool

You can use the maintainDB.[cmd|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

  • Extended information during migration execution is logged into logs\teamcity-dbmt.log file. Also, logs\teamcity-dbmt-truncation.log contains extended information on possible data truncations during the migration process.

  • If you encounter an "out of memory" error, try increasing the number in the -Xmx512m parameter in the maintainDB 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 get "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 maintainDB.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.

Last modified: 20 April 2023
Setting up an External Database TeamCity Data Backup