Restoring TeamCity Data from Backup
TeamCity administrators are able to restore backed up data using the
maintainDB command-line utility.
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 a PostgreSQL database to a new PostgreSQL database). A newer version of TeamCity can be used to restore the backup created with any previous TeamCity version (provided that TeamCity version is not before TeamCity 6.0).
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").
A TeamCity backup file does not contain build artifacts, so to get the server with all the same important data 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) from an old to the new data directory manually. The general compatibility rule of the data under
system/artifacts is that files created by older TeamCity versions can be read by newer versions, but not necessarily vice versa. When external artifacts storage is enabled, the artifacts directory of the TeamCity Data directory contains metadata about artifacts mappings, so make sure they are restored.
See also details on the directories in the TeamCity Data Directory description.
This document describes only some of the
maintainDB options. For the complete list of all available options, run
maintainDB from the command line with no parameters. See also maintainDB startup options.
To perform restore from a backup file:
Install the TeamCity server from a
.exeinstallation package. Do not start the TeamCity server.
Create a new empty TeamCity Data Directory.
Select one of the options:
To restore the backup into a new external database, create and configure an empty database, configure a
database.propertiesfile with the database settings to be passed to the
restorecommand later on and either place it into the
/configsubdirectory of the newly created TeamCity Data Directory or anywhere on your file system outside the TeamCity Data Directory.
To restore the data into the same database the backup was created from, proceed to the next step.
maintainDButility located in the
< TeamCity Home >/bindirectory to run the
To restore the backup into a new external database- if the
database.propertiesfile is in the TeamCity Data Directory:maintainDB.[cmd|sh] restore -A <absolute path to the newly created TeamCity Data Directory> -F <path to the TeamCity backup file> -T <config/database.properties>
- If the
database.propertiesfile is outside the TeamCity Data Directory: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 on the file system outside data dir>
To restore the data into the same database the backup was created from:maintainDB.[cmd|sh] restore -A <absolute path to the newly created TeamCity Data Directory> -F <path to the TeamCity backup file>
To restore the backup into the internal database:maintainDB.[cmd|sh] restore -A <absolute path to the newly created TeamCity Data Directory> -I -F <path to the TeamCity backup file>
If the process completes successfully, to complete the restoration you need to copy over
<TeamCity Data Directory>/system/artifactsfrom the old directory. The directory stores build artifacts and those are not included into the backup file.
Notes on the
restore command options:
-Aargument can be omitted if you have the TEAMCITY_DATA_PATH environment variable set.
-Fargument can be an absolute path or a path relative to the
<TeamCity Data Directory>/backupdirectory.
-Targument must point to the
database.propertiesfile created in step 3.
-Targument is not specified and the
database.propertiesfile is present in the newly created
TeamCity Data Directory/configand the backup file, the database is restored using the properties file in
TeamCity Data Directory/config.
By default, if no other option except
-Fis 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
Restoring database only
When restoring the database but preserving the more recent TeamCity Data directory, it is important to make sure the data is consistent, so:
<TeamCity Data Directory>/system/pluginData("supplimentary data") should be restored as well to be consistent with the database-stored data;
<TeamCity Data Directory>/system/cachesshould be cleared before the server start.
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:
Ensure that the required database drivers are present in the
maintainDButility located in the
< TeamCity Home >/bindirectory (only available in TeamCity
If "supplementary data" is present in the backup, delete the content of <TeamCity Data Directory>/system/pluginData directory (consider backing it up into another file system location first).
-Targument must point to the
database.propertiesfile created in step 1):maintainDB.[cmd|sh] restore -A <absolute path to TeamCity Data Directory> -F <path to the TeamCity backup file> -T <path to the database.properties file of the target database> -D -U
maintainDButility console output. You may have to copy the
database.propertiesfile manually if requested.
Delete the content of <TeamCity Data Directory>/system/caches directory.
Resuming restore after interruption
The restore may be interrupted due to the following reasons:
Lack of space on the file system or in the database
Insufficient permissions to the file system or the database.
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