Skip to content

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

  1. Start by downloading the new version of Squash TM;
  2. Extract the Squash TM archive;
  3. Stop the Squash TM instance currently in use;
  4. Keep a copy of the configuration files in the conf folder as well as a copy of the startup file in the bin folder of the Squash TM instance;
  5. 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.

  1. Access the squash.tm.cfg.properties configuration file.

  2. 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 to forced).

    • 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 to only and run Squash TM once to update the database, then reset the value to disabled).

    • 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

  1. Install the extracted Squash TM application in the desired location.
  2. 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.
  3. Retrieve and install the plugins compatible with the Squash TM version in the plugins directory. Remember to delete old versions and obsolete plugins.
  4. Do not forget to place the license file in the license subdirectory within the plugins directory.
  5. If possible, clear the Tomcat caches (in tomcat-home/work, delete the Tomcat folder) and empty the contents of the tmp directory.
  6. Start the new version of Squash TM.
  7. 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.