Creating Backup via maintainDB command-line tool

TeamCity .tar.gz and .exe distributions provide the maintainDB.bat|sh utility located in the <TeamCity Home>/bin directory. This command-line tool enables you to back up the server data, restore it, and migrate between different databases. You can also back up data using the UI.

Before You Back up

Before backing up data, it is recommended to shut down the TeamCity server to include all builds into the backup. If the backup process is started when the TeamCity server is up, running and queued builds are not included into the backup.

Backup File Location and Format

The default directory for backup files is the <TeamCity Data Directory>\backup.

The default format of the backup file name is TeamCity_Backup_<timestamp>.zip; the <timestamp> suffix is added in the YYYYMMDD_HHMMSS format.

Performing TeamCity Data Backup with maintainDB Utility

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

To create a data backup file, from the command line start maintainDB utility with the backup command:

maintainDB.[cmd|sh] backup

TeamCity data backup has some limitations. By default, if you run maintainDB utility with no optional parameters, only the database, server settings, projects and builds configurations, plugins and supplementary data (settings history, triggers states, plugins data, and so on) will be backed up, omitting build logs and personal changes.

Configuring backup scope

To configure the scope of data to include in the backup file, use the following options:

-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 or --include-supplementary-data — includes supplementary (plugins') data

Specifying different combinations of the above options, you can control the content of the backup file. For example, to create backup with all supported types of data, run

maintainDB backup -C -D -L -P -U

maintainDB Usage Examples for Data Backup

To create a backup file with a custom name, run maintainDB with -F or --backup-file option and specify desired backup file name without extension:

maintainDB.cmd backup -F <backup file custom name>
or
maintainDB.cmd backup --backup-file <backup file custom name>

Executing the command above will create a new ZIP file with the specified name in the default backup directory.

To add a timestamp suffix to a custom filename, add -M or --timestamp-suffix option:

maintainDB.cmd backup -F <backup file custom name> -M
or
maintainDB.cmd backup -F <backup file custom name> --timestamp-suffix

To create a backup file in a custom directory, run maintainDB with the -F option:

maintainDB backup -F <absolute path to the custom backup directory>
or
maintainDB backup --data-dir <absolute path to the custom backup directory>

maintainDB Startup Options

If you customize TeamCity server startup options via TEAMCITY_SERVER_OPTS/TEAMCITY_SERVER_MEM_OPTS environment variables or use custom JDK installation to run the server, you might need to run maintainDB script with related options added into TEAMCITY_MAINTAINDB_OPTS/TEAMCITY_MAINTAINDB_MEM_OPTS environment variables and run the script with all the same environment as the TeamCity server, so that the same JVM is used.

Last modified: 16 October 2024