TeamCity administrators are able to restore backed up data using the maintainDB command line utility.

Note that restoration of the backup created with TeamCity versions earlier than 6.0 can only be performed with the same TeamCity version as the one which created the backup.
Backups created with TeamCity 6.0+ can be restored using the same or more recent TeamCity versions.

If you are creating a copy of the server, make sure to go through copied server checklist after restoration.

On this page:

You can restore backed up data into the same or a different database; from/to any of the supported databases, e.g. you can restore data from a HSQL database to a PostgreSQL database, as well as restore a backup of PostgreSQL database to a new PostgreSQL database.

During database restoration you might want to configure database-specific settings to make the bulk data changes faster (like setting SQL Server "Recovery Model" to "Simple").

(info) This document describes some of the maintainDB options. For a complete list of all available options, run maintainDB from the command line with no parameters.

TeamCity backup file does not contain build artifacts, so for the full restore you need to restore from a backup file (at least settings and database) and copy the build logs and artifacts (located in <TeamCity Data Directory>/system/artifacts by default) form old into the new data directory manually. See also details on the directories in the TeamCity Data Directory description.

Performing full restore

To perform restore from a backup file:

  1. Install the TeamCity server from a tar.gz or .exe installation package. Do not start the TeamCity server.
  2. Create a new empty TeamCity Data Directory.
  3. Select one of the options:
    1. To restore the backup into a new external database, create and configure an empty database, configure a temporary database.properties file with the database settings to be passed to the "restore" command later on.
    2. To restore the backup into the internal database, save the code below to the database.properties file  (this is a temporary file for the purposes of restore) and place the file into any directory other than TeamCity Data Directory:

      # Database: HSQLDB (HyperSonic) version 2.x 
      connectionUrl=jdbc:hsqldb:file:$TEAMCITY_SYSTEM_PATH/buildserver
      
  4. Place the required database drivers into the lib/jdbc sub directory of the newly created Data directory.
  5. Use the maintainDB utility located in the <TeamCity Home>/bin directory to run "restore" command:

    maintainDB.[cmd|sh] restore -A <absolute path to the newly created TeamCity Data Directory> -F <path to the TeamCity backup file> -T <absolute path to the database.properties file of the target database>
  6. If the process completes successfully, copy over <TeamCity Data Directory>/system/artifacts from the old directory

 

Restore command options:

 

By default, if no other option except -F is specified, all of the backed up scopes will be restored from the backup file. To restore only specific scopes from the backup file, use the corresponding options of the maintainDB utility: -D, -C, -U, -L, and -P.

To get the reference for the available options of maintainDB, run the utility without any command or option.

Restoring database only

Before restoring a TeamCity database to an existing server, make sure the TeamCity server is not running.

To restore a TeamCity database only from a backup file to an existing server:

  1. Create and configure the database, placing the database.properties file (this is a temporary file for the purposes of restore) into any directory other than the TeamCity Data Directory.
  2. Ensure that the required database drivers are present in the TeamCity Data Directory/lib/jdbc sub directory.
  3. Use the maintainDB utility located in the <TeamCity Home>/bin directory (only available in TeamCity .tar.gz and .exe distributions).
  4. Use the restore command (The -T argument should point to the temporary database.properties file created in step 1):

    maintainDB.[cmd|sh] restore -A <absolute path to the newly created TeamCity Data Directory> -F <path to the TeamCity backup file> -T <absolute path to the database.properties file of the target database> -D
  5. See the maintainDB utility console output. You may have to copy the database.properties file manually if requested.

Resuming restore after interruption

The restore may be interrupted due to the following reasons:

The interruption occurs when one of tables or indexes failed to be restored, which is indicated in the maintainDB utility console output.
Before resuming the restore, manually delete the incorrectly restored object from the database.

To resume the backup restore after an interruption:
Run the maintainDB utility with the restore command with the required options and the additonal --continue option:

maintainDB.[cmd|sh] restore <all previously used restore options> --continue

{show-if:mode=edit}
* \-C or \--include-config --- includes build configurations settings
* \-D or \--include-database --- includes database
* \-L or \--include-build-logs --- includes build logs
* \-P or \--include-personal-changes --- includes personal changes
 * \-U  --- include supplementary files
{show-if}


See also:

Administrator's Guide: Creating Backup via maintainDB command-line tool