Migrating to an External Database
Last modified: 20 April 2023Please 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 need to migrate TeamCity data from one database to another. Most typical case is when you evaluated TeamCity with internal database and need to switch to an external database to prepare your TeamCity installation for production use.
There are several ways to migrate data into new 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 for any database-stored data provided by the third-party plugins.
backup_restore: same as migration, but using two-step approach.
note
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 preserving the build history and user data:
Install and Setting up an External Database.
Shut down the TeamCity server.
TeamCity Data Backup of the <TeamCity data directory> used by the server
Clean up the
system
folder: you must removemessages
andartifacts
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.Start the TeamCity server.
Backup and Restore backup_restore
You can TeamCity Data Backup and then Restoring TeamCity Data from Backup using different target database settings. You will probably need to specify restore options to restore only database data.
Full Migration
maintainDB
command line utility is used to migrate data between databases. maintainDB.[cmd|sh]
shell/batch script is located in the <TeamCity Home>/bin
directory and is used for migrating as well as for Creating Backup via maintainDB command-line tool and Restoring TeamCity Data from Backup TeamCity data.
TeamCity supports HSQLDB, MySQL, Oracle, PostgreSQL, Microsoft SQL Server 2005, 2008 and Sybase; the migration is possible between any of these databases.
note
The target database must be empty before the migration process (it should NOT contain any tables).
note
If an error occurs during migration, do not use the new database as it can result in database data corruption various errors that can uncover later. In case of error investigate the reason that is logged into console or in the migration logs (see below), and if solution is found, clean the target database and repeat the migration process
To migrate all your existing data to a new external database:
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.
Shut the TeamCity server down.
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.Run the
maintainDB
tool with themigrate
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>
You may need to setTEAMCITY_APP_DIR
environment variable to path of TeamCity web application directory (default is <TeamCity_home>\webapps\ROOT). Also, if you do not haveTEAMCITY_DATA_PATH
environment set (pointing to TeamCity Data Directory), you will need to specify the directory via-A
parameter of the tool. Upon the successful completion of the database migration, adatabase.properties
file will be replaced with the file specified via-T
option. The olddatabase.properties
file will be automatically re-named in the following format:database.properties.before.<timestamp>
.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 | 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. x . y .jar where 1. x . y - jtds version; TC supports versions 1.2.2 and higher | no, download page | jdbc:jtds:sqlserver://<host>[:<port>]/<database name> |
Sybase | com.sybase.jdbc3.jdbc.SybDriver | jconn3.jar | no, grab it from | jdbc:sybase:Tds:<host>:<port>/<database_name> |
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 themaintainDB
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.