Skip to content

Perform a version upgrade

This section provides the procedure to follow for upgrading the SquashTM application outside of Docker. To perform a version upgrade of SquashTM 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 SquashTM;
  2. Extract the SquashTM archive;
  3. Stop the SquashTM instance currently in use;
  4. Keep a copy of the configuration files in the conf folder of the SquashTM instance;
  5. Make a dump of the database (see the section on Backups) for backup purposes.

Database version upgrade

Minor versioning

A minor version change of SquashTM does not require a database version upgrade.

Manual installation (up to version 8.1.1)

If your current SquashTM 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 SquashTM 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 SquashTM 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 (the default, except for the Docker image): This mode requires manual confirmation before each automatic database update. If a database update is needed when starting a new version of SquashTM, a prompt will ask whether a dump exists. To allow SquashTM 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 default for the Docker image): The database update is executed without asking the user for confirmation or verifying if a backup has been made.
    • disabled: Should a database update be necessary when starting a new version of SquashTM, 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 SquashTM with an appropriate parameter value (for example, set the value to only and run SquashTM 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. SquashTM will not start after the update process is completed.

      Installing SquashTM without command prompt

      • In the case of Docker, squash.db.update-mode is set to forced in the image provided by Henix. When upgrading the Docker image to a later version, the database will be automatically updated on the first launch of the new image.
      • In cases where SquashTM is configured as a Windows or Linux (systemd) service, there are two options:
        • forced mode: the database will be automatically updated on the first launch of the new version of SquashTM.
        • interactive mode: after updating SquashTM, you must launch it manually once and validate the database update, after which the service will function normally.

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 SquashTM 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 SquashTM archive. Save the changes.
  3. Retrieve and install the plugins compatible with the SquashTM 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 SquashTM.
  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 SquashTM and plugins, please visit these pages: Install the app and Install plugins.