How do I fix a failed database update?

Or « How do I get Matomo to run the database update commands again after a failed update? »

Sometimes the database update that is run after you update to a newer version of Matomo can fail. There are several different reason why such an update would fail, in this FAQ you will find the steps on how to get Matomo to re-run the database update commands and queries to make sure that everything in your Matomo database has been updated correctly.

Step 1 – Fix the issue that caused the failed database update

Simply re-running the database update may not work if there was something specific that caused the update to fail.
In some cases you will need to increase the wait_timeout of your database server to ensure that the queries don’t time out. In other cases, you may need to re-upload all of the Matomo codebase files to ensure that there are no corrupted files causing an issue.

Step 2 – Rollback the version numbers stored in the Matomo database

We can achieve this by running the following queries directly on the Matomo database:

For updating from Matomo 5 and higher

If you were updating from one version of Matomo 5 to a newer version of Matomo 5, you will need to run the following query:

UPDATE matomo_option set option_value = '5.0.0' where option_value like '5.%';

Note: Here we’re rolling the versions back to an older version than what was previously installed. The reason for this is that there may be plugins that only have a 5.0.X version which need to be updated.
If you’re using an RC or Beta version of Matomo 5, you need to instead roll back to an earlier RC or Beta version to re-run any updates. For example the version to set in the database would be similar to 5.0.0-rc1.

For updating from Matomo 4 and higher

If you were updating from one version of Matomo 4 to a newer version of Matomo 4, you will need to run the following query:

UPDATE matomo_option set option_value = '4.0.0' where option_value like '4.%';

Note: Here we’re rolling the versions back to an older version than what was previously installed. The reason for this is that there may be plugins that only have a 4.0.X version which need to be updated.

For updating from Matomo 3

If you were updating from Matomo 3 to Matomo 4, you will need to run the following query (If you were using an older version than Matomo 3.13.6 then use that version number in the query below):

UPDATE matomo_option set option_value = '3.13.6' where option_value like '4.%';

Once this has been done, we can then trigger the database update:

./console core:update