You are viewing the documentation of TeamCity 10.x and 2017.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.


Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


Wiki Markup
{hidden-data} An internal note as to why: The target database is initialized by the code (so it corresponds to the version of TeamCity used). So, both the target and source database must be from the same TeamCity database version.
There are several ways to migrate data into a new 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 for any database-stored data provided by the third-party plugins.
  • Backup and then restore: the same as full migration, but using the two-step approach.


If you want a fast switch to an external database and do not want to preserve existing data like users and builds on the server you can , follow the steps below. See #Full Migration for preserving all the data.
After the switch, the server will start with an empty database, but preserve all the settings stored under TeamCity Data Directory (see details on what is stored where).


  1. Create and configure an external database to be used by TeamCity.
  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 the messages and artifacts folders from the /system folder of your <TeamCity data directory>; you may delete the old HSQLDB files: buildserver.* to remove the no longer needed internal storage data.
  5. Start the TeamCity server.


    If you see the TeamCity Maintenance screen, click the "I’m a server administrator, show me the details" link and enter the Maintenance Authentication Token. Follow the instructions to create a new TeamCity database.