Restoring a TestRail backup

This article explains how to restore a TestRail backup in case you need to recover from a hardware failure, if you want to move a TestRail installation to a new server or to migrate a TestRail Cloud account to a local instance. In all these cases you should have a logical (SQL) database backup as well as copies of all attachments and reports, if any.

If you are just moving your TestRail installation and don't have a backup yet, please read the guide on how to backup TestRail. If you want to migrate a TestRail Cloud account to a local instance, please create and download a backup in TestRail under Administration > Subscription.

1. Installing TestRail

To restore a TestRail backup you first need to install TestRail on the new server. Installing TestRail on the new server ensures that the server meets all requirements and that all file permissions and database connections are set correctly. You can read the installation instructions of TestRail in our Administration manual.

Please install the exact same version or a newer version of TestRail than the version you used to create the backup. Using the exact same version is recommended. You can download older TestRail versions from our customer portal, or you can contact us.

If you have customized any defect plugins, authentication scripts or other parts of TestRail, you will also need to copy the modified scripts (usually stored in the custom directory of the installation/backup) to the new system.

2. Restoring the database

After successfully installing TestRail, you need to restore your database. To do this you can simply use the tools provided by your database. Please see below for a brief explanation of restoring a database backup with MySQL and SQL Server.

MySQL

MySQL comes with a simple command line tool to execute SQL commands. As a logical MySQL backup simply contains SQL commands to restore a database, you can execute your logical backup file against a database. To do this you would use the mysql command line tool like this:

mysql -u <username> -p --default-character-set=utf8 <database> < backup.sql

Please replace <username> with the MySQL login, and <database> with your database name. Please note that all existing data in that database will be replaced with the backup, so make sure it's a new, empty database from the above mentioned installation. Double check that this is the right database and machine before executing the command.

SQL Server

You can either execute the backup SQL file via the SQL Management Studio against your database (just make sure that the correct database is selected in the dropdown in the upper left corner before executing the script in Management Studio).

Or you can execute the script via the sqlcmd command line tool like this:

sqlcmd -x -f 65001 -S localhost -U <username> -d <database> -i backup.sql

Please replace <username> with the login name, and <database> with your database name. Please note that all existing data in that database will be replaced with the backup, so make sure it's a new, empty database from the above mentioned installation. Double check that this is the right database and machine before executing the command.

3. Restoring the attachments & reports

You also need to copy all attachments and reports to the attachment and report directories you specified during the TestRail installation. Please also make sure that the permissions of the files allow the web server to read them. Please note that reports and the report directory are only available with TestRail 3.0 and later.

4. Updating settings

After importing the database and restoring the attachments and reports, you might need to enter your license key and change a few settings under Administration > Site Settings when you first log in to TestRail, namely:

  • Attachment Directory
  • Installation URL
  • Email Server
  • Email From Address
  • License Key
  • Report Directory