Before a Database upgrade on a high traffic Matomo server, it is highly recommended to:
Disable Matomo Tracking
In the config/config.ini.php, add the following
record_statistics = 0
This will cause all Matomo Tracking API requests (to
piwik.php) to return quickly the response and status code
204, without connecting to the database or doing any processing. Requests for
configs.php for Heatmaps & Session Recordings will still return a status code
Disable the Matomo User Interface and APIs
To disable the User Interface and the APIs, but still track all of your data correctly, you can enable maintenance mode.
When maintenance_mode is on, a maintenance message instead of the standard Matomo reporting interface. Your data is still tracked as expected, but the UI and the Reporting APIs are disabled.
If you run the Matomo Database Upgrade script using the shell/console command, we highly recommend turning Matomo off while the upgrade is in process. Disabling the Matomo User Interface will prevent other users from accessing Matomo while the Database upgrade is in process.
To do so, add the following in the config file:
maintenance_mode = 1
If the line
[General] already exists, add the line
maintenance_mode = 1 below the line
The following XML messages will be returned by the API:
<result><error message="Matomo is in scheduled maintenance. Please come back later. "/></result>
The Reporting API endpoint
index.php will return an HTTP error status code
503 (Service unavailable) while it is in maintenance mode. Unless Matomo is configured behind a load balancer, with
multi_server_environment=1, should return HTTP status code
Re-enable Tracking API and UI
When the Matomo update is finished, do not forget to re-enable Visit Tracking and/or the User Interface.
And if you need to recover any missing data that wasn’t tracked during the maintenance window, learn more in about replay the traffic to Matomo and ingest logs of piwik.php requests