Restoring TeamCity Data from Backup
TeamCity administrators are able to restore backed up data via the TeamCity UI or by manually using the maintainDB
command-line utility.
Before Restoring
You can restore backed up data into the same or a different database; from/to any of the supported databases (for example, 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 the TeamCity version is later than 6.0).
During restoration of a large database you might want to configure database-specific settings to make the bulk data changes faster (like setting SQL Server "Recovery Model" to "Simple"). Consult your DBA for more details.
A TeamCity backup file does not contain build artifacts. To back up the build logs and artifacts, copy the contents of the artifact directory (<TeamCity Data Directory>/system/artifacts
by default) from the old location to the new one 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.
Note that it is important to copy artifacts before the server start as reindexing build metadata is launched automatically on starting the server restored from backup. If some artifacts are missing during indexing, this could lead to failures in the work of some parts of the TeamCity server (for example, a NuGet feed). In case you copied artifacts after the server start (or copying of artifacts was not completed before the server start), you might need to reindex build metadata manually and wait until reindexing is finished.
Performing Restore
TeamCity can automatically restore the backed up data. This process relies on the maintainDB utility, but performs all the necessary operations under the hood. To restore the backed up files on the first start of the TeamCity server:
Open the TeamCity URL (by default,
http://localhost/
forexe
installations andhttp://localhost:8111/
fortar.gz
) in a browser.On the TeamCity First Start page, enter the path to the Data Directory and click Restore from backup.
Enter an absolute path to the backup directory on the TeamCity server or upload a ZIP archive with the backed up data.
Choose the target database. If you use an external database, configure its address and credentials.
Proceed with the restoration.
TeamCity will restore the data and display the maintainDB utility log. If the version of the backed up data format is earlier than the current one, TeamCity will propose to upgrade it.
Alternatively, you can use the maintainDB utility manually. This section 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 via maintainDB:
Install the TeamCity server from a
tar.gz
or.exe
installation package. Do not start the TeamCity server.Create a new empty TeamCity Data Directory.
Choose one of the options:
To restore the backup into a new external database, create and configure an empty database, configure a
database.properties
file with the database settings to be passed to therestore
command later on and either place it into the/config
subdirectory 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.
Place the required database drivers into the
lib/jdbc
subdirectory of the newly created TeamCity Data Directory directory.Use the
maintainDB
utility located in the<TeamCity Home>/bin
directory to run therestore
command:a. To restore the backup into a new external database
if the
database.properties
file 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.properties
file 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>b. 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>c. 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/artifacts
from the old directory. The directory stores build artifacts and those are not included into the backup file.
Notes on the restore
command options:
The
-A
argument can be omitted if you have theTEAMCITY_DATA_PATH
environment variable set.The
-F
argument can be an absolute path or a path relative to the<TeamCity Data Directory>/system/backup
directory.The
-T
argument must point to thedatabase.properties
file created in step 3.If the
-T
argument is not specified and thedatabase.properties
file is present in the newly created<TeamCity Data Directory>/config
and the backup file, the database is restored using the properties file in<TeamCity Data Directory>/config
.By default, if no other option except
-F
is specified, all 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 themaintainDB
utility:-D
,-C
,-U
,-L
, and-P
.
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:
<TeamCity Data Directory>/system/pluginData
(supplementary data) should be restored as well to be consistent with the data stored in the database.<TeamCity Data Directory>/system/caches
should 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:
Create and configure the database, placing the
database.properties
file into theconfig
subdirectory of theTeamCity Data Directory
.Ensure that the required database drivers are present in the
/lib/jdbc
subdirectory.Use the
maintainDB
utility located in the<TeamCity Data Directory>/bin
directory (only available in TeamCity.tar.gz
and.exe
distributions).If the supplementary data is present in the backup, delete the content of the
<TeamCity Data Directory>/system/pluginData
directory (consider backing it up in another location first).Use the
restore
command (The-T
argument must point to thedatabase.properties
file 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> -DSee the
maintainDB
utility console output. You may have to copy thedatabase.properties
file manually if requested.Delete the contents of the
<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 --continue
option: