Perform a version upgrade
This section provides the procedure to follow for upgrading the Squash TM application outside of Docker. To perform a version upgrade of Squash TM using the Docker image, refer to this page. Every version upgrade is carried out in two phases: updating the database and installing the new version of the application.
Focus
It is strongly recommended to test the version upgrade in a production-like environment before performing it in production.
Prerequisites
- Start by downloading the new version of Squash TM;
- Extract the Squash TM archive;
- Stop the Squash TM instance currently in use;
- Keep a copy of the configuration files in the
conf
folder as well as a copy of thestartup
file in thebin
folder of the Squash TM instance; - Make a dump of the database (see the section on Backups) for backup purposes.
Database version upgrade
Manual installation (up to version 8.1.1)
If your current Squash TM version is lower than 8.1.1 (for example, 5.x or 7.x), you must update the database to version 8.1.0.
To do this, execute the version upgrade scripts (<database>-upgrade-to-<version>.sql
) found in the database-scripts
directory of the new Squash TM version. Note that the upgrade scripts must be executed based on the type of database and in version order. You must always start with the script corresponding to the version number immediately above the version of Squash TM currently in use.
For example, to upgrade Squash TM 6.0.0 to Squash TM 8.1.1, on a PostgreSQL database, here is the list of scripts to execute:
postgresql-upgrade-to-7.0.0.sql
;postgresql-upgrade-to-7.1.0.sql
;postgresql-upgrade-to-7.2.0.sql
;postgresql-upgrade-to-7.3.0.sql
;postgresql-upgrade-to-8.0.0.sql
;postgresql-upgrade-to-8.1.0.sql
.
Warning
Upgrade scripts must be run in version order. If the scripts have been run out of sequence, the upgrade process must be restarted from the backup dump.
Automatic update (starting at version 9.0.0)
Squash TM 9.0 introduces an automatic database installation and update system.
-
Access the
squash.tm.cfg.properties
configuration file. -
Modify the
squash.db.update-mode
parameter according to the desired mode:interactive
(default): This mode requires manual confirmation before each automatic database update. If a database update is needed when starting a new version of Squash TM, a prompt will ask whether a dump exists. To allow Squash TM to either continue or stop (depending on the user's choice), manual input is required to respond to the prompt displayed in the command window.-
forced
: The database update is executed without asking the user without asking the user for confirmation or verifying if a backup has been made.Squash TM used in Docker or as a Windows service
For installations of Squash TM without a command prompt, for example in Docker or as a Windows or Linux service (
systemd
),forced
mode should be used. (In the Docker image supplied by Henix, this parameter is already set toforced
). -
disabled
: Should a database update be necessary when starting a new version of Squash TM, no action is taken to update the database. The application will then attempt to continue its startup but will likely fail due to an incompatibility issue between the application version and the database version. It is the user's responsibility to update the database by restarting Squash TM with an appropriate parameter value (for example, set the value toonly
and run Squash TM once to update the database, then reset the value todisabled
). only
: This mode, exclusively dedicated to database updates, automatically updates it. There is no manual confirmation. Squash TM will not start after the update process is completed.
Database update error analysis
Should any errors occur during the database update process, you can review the logs in the squash-tm.log
file. Initialization details, including execution status, are also logged in the DATABASECHANGELOG
table.
Focus
For PostgreSQL databases, actions such as backups, restores, and script executions must be performed with the squash-tm
user, not the postgres
user.
Ensure that the user squash-tm
has the ownership rights (DATABASE OWNER
) on the database. Reassign these rights if necessary.
Application version upgrade
- Install the extracted Squash TM application in the desired location.
- Manually transfer the environment-specific information (from the files saved during the prerequisites phase) to the startup and configuration files of the new Squash TM archive. Save the changes.
- Retrieve and install the plugins compatible with the Squash TM version in the
plugins
directory. Remember to delete old versions and obsolete plugins. - Do not forget to place the license file in the
license
subdirectory within theplugins
directory. - If possible, clear the Tomcat caches (in
tomcat-home/work
, delete theTomcat
folder) and empty the contents of thetmp
directory. - Start the new version of Squash TM.
- Ask users to clear their browser caches after the version upgrade to avoid display issues.
Learn more
For more details on how to install Squash TM and plugins, please visit these pages: Install the app and Install plugins.