WHM’s MySQL/MariaDB Upgrade tool does most of the mechanical work of a version change, and that is exactly why it goes wrong: it is easy to click through without the preparation that makes the outcome recoverable. cPanel does not support downgrades, so once the new packages are installed the only way back is a backup restored onto the old version. This guide wraps the WHM workflow in the steps we take on every production upgrade, whether the hop is 10.6 to 10.11 or 11.4 to 11.8.
Applies to cPanel & WHM; MariaDB 10.6 to 10.11 and 11.4 to 11.8
Table of Contents
Short answer: Check my.cnf for variables the target version removed, take a verified mariadb-dump --all-databases and set SET GLOBAL innodb_fast_shutdown = 0 so the redo log is empty at shutdown, then run the upgrade from WHM → SQL Services → MySQL/MariaDB Upgrade or whmapi1 start_background_mysql_upgrade version=11.8. Afterwards confirm the version, rerun mariadb-upgrade and check every table with mariadb-check --all-databases --check-upgrade, keeping the dump because cPanel offers no downgrade.
Pre-flight
Confirm the current version, the target the panel offers, and the disk headroom. The upgrade creates a copy of the data directory during the process on some paths, and mariadb-upgrade rebuilds tables, so you want at least the size of /var/lib/mysql free on that filesystem:
whmapi1 current_mysql_version
whmapi1 installable_mysql_versions
du -sh /var/lib/mysql
df -h /var/lib/mysqlThen check my.cnf for variables the target version no longer accepts. cPanel’s tool warns about some but not all of them, and a single unknown variable stops the service from starting after the packages are swapped:
grep -vE '^\s*(#|$)' /etc/my.cnf /etc/my.cnf.d/*.cnf 2>/dev/nullCompare each line against the removed-variable list for your target in the unknown variable guide. Comment out anything suspicious now; you can restore it afterwards if the new version still accepts it.
Take the backup that you will actually be able to use
A logical dump is portable across versions and is what you restore if you need to go back:
mariadb-dump --all-databases --single-transaction --routines --events --triggers --flush-privileges | gzip > /backup/mariadb-pre-upgrade-$(date +%F).sql.gz
ls -la /backup/mariadb-pre-upgrade-*.sql.gz--single-transaction keeps InnoDB tables consistent without locking; MyISAM tables (still common in old customer schemas) are not covered by it, so on a server with many MyISAM tables run the dump during a quiet period. If the server uses a snapshot-capable filesystem or a virtualisation platform with snapshots, take one as well, but do not treat a snapshot as the only backup; a snapshot of a running database is only consistent if the database was quiesced.
Verify the dump is complete by checking its tail:
zcat /backup/mariadb-pre-upgrade-*.sql.gz | tail -3The last lines should be the dump-completed marker, not a truncated INSERT. Our backup verify script does this check across a directory of dumps.
Slow shutdown
InnoDB’s default shutdown leaves work for the next start: dirty pages are flushed but the redo log and undo logs are not fully purged. A new major version that has to replay an old version’s redo log is a well-known source of failed starts. Set the slow shutdown before stopping, so the data files are fully consistent and the log is empty:
mariadb -e "SET GLOBAL innodb_fast_shutdown = 0;"
mariadb -e "SET GLOBAL innodb_max_dirty_pages_pct = 0;"
sleep 60
mariadb -e "SHOW GLOBAL STATUS LIKE 'Innodb_buffer_pool_pages_dirty';"Wait until the dirty page count is close to zero. On a server with a large buffer pool and heavy writes that can take several minutes; it is time well spent. The WHM tool stops the service itself, and it inherits the setting because it is a global variable on the running instance.
Run the WHM upgrade
In WHM go to SQL Services, then MySQL/MariaDB Upgrade. Select the target version, acknowledge the warnings (they are worth reading; the tool checks for known-incompatible cPanel versions and for third-party repositories that might interfere), and choose the unattended upgrade. It logs to /var/cpanel/logs/mysql_upgrade.log. You can also drive it from the shell:
whmapi1 start_background_mysql_upgrade version=11.8
tail -f /var/cpanel/logs/mysql_upgrade.logThe tool removes the old packages, installs the new ones from cPanel’s repository, starts the service, runs mariadb-upgrade and rebuilds the PHP MySQL extensions and other dependents through EasyApache. Expect the database to be unavailable for the package swap, typically two to five minutes, plus however long mariadb-upgrade takes across your tables.
If the service does not start
Read the error log before doing anything else:
tail -50 /var/lib/mysql/$(hostname).errThe two usual culprits are an unknown variable (fix my.cnf and start again) and an InnoDB redo log format the new version rejects (which the slow shutdown prevents; if it happens anyway, the log file may need to be moved aside, and at that point you are choosing between the vendor’s recovery procedure and restoring the dump). Our MariaDB will not start guide works through both.
Common pitfall
Skipping mariadb-upgrade because the WHM tool “did it”. It usually does, but if the tool was interrupted, or if the service was restarted by monitoring in the middle, the system tables may still be at the old version. Running it again is harmless:
mariadb-upgrade --verbose 2>&1 | tail -20It reports “already upgraded” if there is nothing to do.
Verify
mariadb -e "SELECT VERSION();"
mariadb -e "SHOW GLOBAL VARIABLES LIKE 'innodb_fast_shutdown';"
mariadb-check --all-databases --check-upgrade | grep -v OK
/scripts/restartsrv_mysql --status
whmapi1 current_mysql_versionThe version should match the target, innodb_fast_shutdown should have returned to its default of 1, and mariadb-check should print nothing beyond the header. Load a few customer sites, log in to phpMyAdmin from a cPanel account, and confirm PHP applications connect (a rebuild of ea-php*-php-mysqlnd is normally automatic, but check php -m | grep -i mysql for each installed version). Keep the dump for at least a week and record the new version in your inventory before moving to the next server.
Upgrade MariaDB WHM at a glance
Official documentation: MariaDB documentation, cPanel & WHM documentation, Linux man pages.
Related guides: MySQL 8.0 is end-of-life: moving cPanel servers to MySQL 8.4 or MariaDB · How to upgrade MySQL 8.0 to MariaDB 11.8 in WHM without losing databases · MariaDB 12.3 LTS: what changed and what breaks (reserved words, removed variables, Galera packages).
Frequently asked questions
How long does a MariaDB upgrade through WHM take?
The package swap takes two to five minutes of database downtime, plus the time mariadb-upgrade needs across your tables, which is usually a few minutes but can be longer on servers with tens of thousands of tables. The slow shutdown beforehand adds a few minutes on a busy server.
Can I skip a MariaDB version, for example 10.6 straight to 11.8?
WHM offers the hop and MariaDB supports upgrades across more than one major version, but each jump removes more configuration variables and reserves more words. Moving one LTS at a time, 10.6 to 10.11 and then to 11.8, keeps each change small and gives an intermediate state to fall back to.
Does the WHM MariaDB upgrade delete customer databases?
No. The upgrade replaces the server packages and starts the new version on the existing data directory, then rebuilds system tables with mariadb-upgrade. Customer data is untouched, which is also why a verified logical dump is still essential: it is the only rollback if the data directory ends up in a state the old version cannot read.
Maintenance record
This guide changes servers, data or security settings, so we re-check it against current versions on a fixed schedule. Take a backup or snapshot before you start.
- Maintained by
- srvScripts editorial team
- Supported versions
- cPanel & WHM; MariaDB 10.6 to 10.11 and 11.4 to 11.8
- Last full review
- Next review