Restoring TeamCity Data from Backup
TeamCity administrators are able to restore backed up data using the maintainDB
command line utility.
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.
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").
Performing full restore
To perform full restore a TeamCity server from a backup file:
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.
Select one of the options:
To restore the backup into a new external database, 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.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
Place the required database drivers into the
lib/jdbc
sub directory.Use the
maintainDB
utility located in the< TeamCity Home >/bin
directory.Use the
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>
The -A argument can be omitted if you have the TEAMCITY_DATA_PATH environment variable set.
The -F argument can be an absolute path or a path relative to the
< >/backup
directoryThe -T argument should point to the temporary
database.properties
file created in step 3.
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
.
TeamCity will restore the data directory from the backup file. You can also copy the files that were not included into the backup into the data directory (most importantly, build artifacts, located in <TeamCity Data Directory>/system/artifacts
by default), see details on the directories in the TeamCity Data Directory description.
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:
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.Ensure that the required database drivers are present in the
/lib/jdbc
sub directory.Use the
maintainDB
utility located in the< TeamCity Home >/bin
directory (only available in TeamCity.tar.gz
and.exe
distributions).Use the
restore
command (The -T argument should point to the temporarydatabase.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> -DSee the
maintainDB
utility console output. You may have to copy thedatabase.properties
file manually if requested.
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 --continue
option: