...
The upgrade subsystem in Totara is largely unchanged from Moodle, please review https://moodledev.io/docs/5.0/guides/upgrade for basics of how it works.
Plugin upgrade steps must be reviewed by a dev lead or architect due to previous upgrades which resulted in data loss or which performed poorly, causing the upgrade to overrun the time window allotted to it.
| Tip |
|---|
A customer’s data is the most important and valuable part of their system. |
...
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.
...
The patterns for this are not well-established; we have used adhoc tasks to defer performance intensive upgrades in the past but this has do be done carefully and in small batches to prevent overloading the site on the next cron run. Manual triggers would be preferred
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 runbeen 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.