TestRail Server Cassandra Data Migration to MS SQL Server for Windows

Updated August 07, 2025 20:01

Starting with TestRail Server 9.4, attachment storage will transition from Cassandra to Microsoft SQL Server or MySQL. The 9.4 update includes a supported migration script that allows you to copy your existing attachments from Cassandra to MS SQL Server or MySQL. Your original Cassandra data will remain intact.

Note: If you're already using TestRail 8.1, you won't need to follow the steps below. However, you will need to manually edit config.php to remove any Cassandra-related details. Additionally, please verify that TestRail is operating in SQL-only mode by checking the settings table:

primary_attachment_db should be set to "sql"
attachments_to_both_dbs should be set to "0"

You may run the migration at your own pace. However, starting with the following release (TestRail 9.5), completion of the migration will be required to upgrade. Customers who have not completed the migration will be unable to install TestRail 9.5 and all future updates until the migration is complete.

If you prefer not to migrate, you may continue using your current version. Please note that TestRail Server support covers the past two years of active releases, so remaining current ensures continued access to support and security updates.

If you would like to proceed, here are step-by-step instructions:

Open your shell (e.g., Terminal, PowerShell) and navigate to the deprecation_script folder.
Run the following command to verify that Composer is installed and running properly:
```
composer -V
```
If Composer isn’t running, please refer to the project’s documentation for instructions on how to install it.
Install the necessary dependencies with the following command:
```
composer update
```
Verify the connection to the MS SQL Server database:
```
sqlcmd -S  -U username -P password
```
Verify the connection to Cassandra database:
```
sqlcmd -S cqlsh  9042 -u  -p 
```

(Optional) Do a dry-run to verify that the Migration Script is working:

php TestRailSqlToCassandraMigration.php -d2 -r -m"driver=sqlsrv;host=;port=;database=;user=;password=" -s"host=;port=9042;keyspace=;user=;password=" -v2 -b --attachments=""

Make sure to fill config.ini file, use sqlsrv database version and enter credentials to connect to database (make sure that if your password(s) include special characters, place them inside double quotes)
```
`driver = sqlsrv`
```
If all the previous steps completed successfully, run the Deprecation Script with with the following command:
```
php TestRailCassandraDeprecation.php 
```
Alternatively, you can also add the --force-deprecation flag to force the deprecation process to run even in the event that errors are encountered when migrating the attachments:
```
php TestRailCassandraDeprecation.php --force-deprecation
```