How do I downgrade from Matomo 4 to Matomo 3?

Matomo 4 comes with many database schema changes requiring additional steps to downgrade to Matomo 3. Please read the instructions fully before proceeding with the steps.

Please note that the downgrade process will change your token_auth. If you are using for example the Matomo HTTP API or the Matomo Tracking API this will affect you. You will need to change the token_auth in all your applications. Also some slight data conversions may occur while downgrading.

• We recommend making a backup of your code and database if any possible. If you still have a backup from before upgrading to Matomo 4, try to use the backups instead of following below steps.
• If you have a high traffic site we recommend enabling the maintenance mode.
• Download the latest version of Matomo 3.
• Extract the zip and replace the files on your server using the following instructions from the manual update process. The idea is that you basically remove all existing files except for config/config.ini.php and then copy over the new files. If you were using any plugins from the Marketplace, you will need to download them again from the Marketplace.
• Execute below queries on your database. You may need to adjust the matomo_ prefix depending on your DB table prefix.

    ALTER TABLE matomo_user ADD COLUMN alias VARCHAR(45) NOT NULL;
    ALTER TABLE matomo_user ADD COLUMN token_auth CHAR(32) NOT NULL;
    UPDATE matomo_user set token_auth = MD5(CONCAT(NOW(), UUID())), `alias` = `login`;
    ALTER TABLE matomo_log_visit ADD COLUMN config_gears TINYINT(1) NOT NULL, ADD COLUMN config_director TINYINT(1) NOT NULL;
    ALTER TABLE `matomo_log_link_visit_action` CHANGE `pageview_position` `interaction_position` MEDIUMINT UNSIGNED DEFAULT NULL;
    ALTER TABLE matomo_log_visit ADD COLUMN visitor_days_since_first INT(11) UNSIGNED NULL;
    ALTER TABLE matomo_log_visit ADD COLUMN visitor_days_since_order INT(11) UNSIGNED NULL;
    ALTER TABLE matomo_log_visit ADD COLUMN visitor_days_since_last INT(11) UNSIGNED NULL;
    ALTER TABLE matomo_log_conversion ADD COLUMN visitor_days_since_first INT(11) UNSIGNED NULL;
    ALTER TABLE matomo_log_conversion ADD COLUMN visitor_days_since_order INT(11) UNSIGNED NULL;
    UPDATE matomo_log_visit SET visitor_days_since_first = ROUND(visitor_seconds_since_first / 86400), visitor_days_since_order = ROUND(visitor_seconds_since_order / 86400), visitor_days_since_last = ROUND(visitor_seconds_since_last / 86400);
    UPDATE matomo_option set option_value = '3.13.6' where option_value like '4.0.0%';

• You can now disable the maintenance mode if you enabled it previously
• Open the Matomo UI
• You might be presented with another MySQL update changing a few more columns which you can execute either using the UI directly or on the command line should your database size be larger.
• You should now be able to use Matomo 3.