Outsource Attachments
Squash TM allows you to store attachments outside of the database, directly in a files system. By default, attachments are stored within the database, since it is simpler. Indeed, it is very convenient for storing standard data volumes.
In a new Squash TM install, you simply have to input this storage mode in the settings. In an already existing Squash TM, you first have to extract the existing attachments before changing the settings.
Focus
The change of storage from database to files system has consequences on data saving. Thus, the administrator must make these necessary changes:
- Organize an attachments-saving system that is synchronous with the database system
- Free up enough space to store the attachments and monitor the evolution of the space available
- Give reading and writing privileges to the user starting the Squash TM process on the folder that is going to receive the attachements
Configure Settings
Warning
If there are already existing attachments in the database, you must first extract them BEFORE changing Squash TM settings.
~SQUASH is Squash TM's deployment folder.
- Stop Squash TM and edit the file squash.tm.cfg.properties in the directory ~SQUASH/conf
-
Add the following property to activate the external storage of attachments:
squashtm.feature.file.repository = true
-
Add the following property to define the storage location of the attachments:
squash.path.file.repository=<Chemin choisi pour le stockage des fichiers>.
By default, if this property is absent, Squash TM will store the attachments in the repository ~SQUASH/attachments. However, this step is necessary once you extract attachments from the database.
-
Make all the necessary system changes, especially if your chosen path is not the default path. (This is especially the case when you give permissions to a user, who must be able to write and change the process in both Squash TM and the OS).
- Restart Squash TM
- Add a new attachment from Squash TM and verify that it is stored in your chosen location. Verify that you can properly download and delete the attachment.
Focus
Once the attachments are stored in a files system, you cannot go back to a database storage unless you are willing to lose all the attachments you have stored on that external repository.
Extract Existing Attachments
To go from a database storage to a files system storage already in Squash TM, you must migrate the database attachments to the file format expected by Squash TM.
You can use this tool provided to you by Henix to help you migrate, available on the website https://www.squashtest.com/. The artefact to use is named squash-tm-extract-attachment-tool-1.0.0.RELEASE.
Preconditions
Warning
You must save the database BEFORE starting the migration to be able to restore in case there is a problem.
Linux Procedure
To extract the existing attachments from a Squash TM database to a Linux files system:
~SQUASH is Squash TM's deployment folder.
-
Stop Squash TM
-
Extract the tool squash-tm-extract-attachment-tool-1.0.0.RELEASE to Squash TM's root repository ~SQUASH.
-
Open the file extract-attachments.sh in a text editor
-
Search for the following lines:
DB_TYPE=h2 DB_URL=jdbc:h2:../data/squash-tm DB_USERNAME=sa DB_PASSWORD=sa
Change them with the required values to access Squash TM's database. They must be identical to the ones in Squash TM's startup script (~SQUASH/bin/startup.sh).
-
Search for the following line:
REPO_PATH=./attachments
Edit the property to indicate the path in which the attachments will be extracted. If this property value is not modified, the attachments will directly be extracted in (~SQUASH/attachments), which also is the default path in which Squash TM will get them after the migration.
-
Execute the file extract-attachments.sh. The migration automatically starts. Here are its 3 phases:
- Extracting attachments
- Verifying the extracted files
- Deleting the attachments in the database
-
Once the migration is over, configure the file squash.tm.cfg.properties as written in Configuration
Windows Procedure
To extract existing attachments from a Squash TM database to a files system in Windows:
~SQUASH is Squash TM's deployment folder.
-
Stop Squash TM
-
Extract the tool squash-tm-extract-attachment-tool-1.0.0.RELEASE to Squash TM's root repository ~SQUASH.
-
Open the file extract-attachments.bat in a text editor
-
Search for the following lines:
set DB_TYPE=h2 set DB_URL=jdbc:h2:./data/squash-tm set DB_USERNAME=sa set DB_PASSWORD=sa
Change them with the required values to access Squash TM's database. They must be identical to the ones in Squash TM's startup script (~SQUASH/bin/startup.bat).
-
Search for the following line:
set REPO_PATH=./attachments
Edit the property to indicate the path in which the attachments will be extracted. If this property value is not modified, the attachments will directly be extracted in (~SQUASH/attachments), which also is the default path in which Squash TM will get them after the migration.
-
Execute the file extract-attachments.bat. The migration automatically starts. Here are its 3 phases:
- Extracting attachments
- Verifying the extracted files
- Deleting the attachments in the database
-
Once the migration is over, configure the file squash.tm.cfg.properties as written in Configuration.
Post migration
According to the RDBMS, it might be necessary to perform a maintenance operation on the database using SQL queries to free the disk space taken by the attachments, even if the migrator has deleted them.
For a PostgreSQL database, use the programs vacuumlo or vaccumdb to permanently delete large objects.
For MySQL or MariaDB, use optimize table from the "Table Inspector" tool to permanently delete large objects.
Please read the RDBMS documentation to learn more.