...
Totara currently enforces a linear upgrade path, meaning each successive plugin upgrade must be to a higher version.
However it is possible to for sites to get into situations where a given upgrade step is run more than once – consider the simple scenario where an upgrade step fails and is restarted before the savepoint is reachedlikely, because of the way that we manage versions across major releases, for the same upgrade step to have two or more different versions. For example, in Totara 18.6 an upgrade step that is part of a bug fix might have the version 2023112801. In Totara 19, that same step would have the version 2025012301. So a site upgrading from Totara 17, through 19, to 20 would execute the step twice.
For this reason, upgrade steps must be written so that they use conditional statements to avoid trying to make the same change twice. As a simple example, consider an upgrade that adds an index to a table:
...
As an upgrade step becomes more complex, however, it is important necessary to abstract the steps to one or more standalone functions in db/upgradelib.php that have unit test coverage proving that they work and handle edge cases appropriately.
...
A manual trigger (CLI script or in-product admin action) may also a possibility, with a check API check to detect that the manual upgrade hasn’t been actioned yet.
If you are concerned about upgrade performance, please raise the issue early your dev lead and/or an architect so we can collaborate on the best solution.