Upgrade MariaDB or MySQL on cPanel/WHM without breaking it

Upgrading the database engine on a cPanel box is the one routine maintenance task that has no undo button. Once WHM finishes the upgrade, the on-disk data format is rewritten and you cannot downgrade — not to the previous MariaDB version, and not back to MySQL if you switched. This guide covers the supported version paths, the CloudLinux MySQL Governor route (where the WHM tool is disabled), and the pre-flight checks that keep a 10-minute upgrade from turning into a restore-from-backup afternoon.

This is for sysadmins running production shared or reseller hosting. If you're on a stock cPanel box without CloudLinux, use the WHM tool. If you run CloudLinux, skip to the Governor section — the WHM upgrade tool is greyed out on purpose.

What versions cPanel supports in 2026

cPanel & WHM ships support for a moving target. As of mid-2026 the supported engines are:

• MariaDB 10.6 — old stable, fine to stay on, but plan ahead.
• MariaDB 10.11 — current LTS, the safe default for most fleets.
• MariaDB 11.4 — newer LTS, supported but test your application stack first.
• MySQL 8.0 — supported; MySQL 5.7 is end-of-life and unsupported.

MariaDB 10.3, 10.4, and 10.5 are gone. If WHM shows your server on one of those, you're on borrowed time — security patches stopped upstream, and a CentOS/AlmaLinux upgrade will fight you over it. See migrating CentOS 7 to AlmaLinux on cPanel if your OS is also overdue.

Pre-flight checks

Run these before touching the upgrade tool. Skipping them is how upgrades go wrong.

# Current version
mysql --version

# Free space on the MySQL datadir partition — you need headroom for the rewrite
df -h /var/lib/mysql

# Full logical dump of every database (your real safety net)
mysqldump --all-databases --routines --triggers --single-transaction \
  > /root/all-databases-pre-upgrade.sql

# Check table health first — upgrades amplify existing corruption
mysqlcheck --all-databases --check

Upgrading via WHM (no CloudLinux)

1. WHM Home → SQL Services → MySQL/MariaDB Upgrade. (Or just type upgrade in the WHM search box.)
2. Select the target version. WHM tells you if the jump is allowed.
3. Choose Interactive Upgrade. It walks each step, runs the engine upgrade, rebuilds Apache and PHP, and updates dependent components. The unattended mode exists but you want eyes on a production upgrade.
4. Acknowledge the irreversibility prompt and let it run.

When the engine swap finishes, cPanel runs mariadb-upgrade (formerly mysql_upgrade) automatically to bring the system tables in line with the new version. Expect a short MySQL restart — seconds to a couple of minutes depending on table count — during which sites throwing database queries will error.

Step through major versions — don't leap

You cannot skip major versions. The data format changes incrementally, and the upgrade routine expects the previous format. To get from 10.6 to 11.4, go 10.6 → 10.11 → 11.4, running the full upgrade and verifying between each hop. Trying to jump straight risks a half-migrated system-table state that's painful to unwind.

Upgrading on CloudLinux with MySQL Governor

If MySQL Governor is installed, MySQL/MariaDB is managed by CloudLinux, not cPanel — so the WHM upgrade tool is disabled. Use the Governor CLI instead:

# Set the target version
/usr/share/lve/dbgovernor/mysqlgovernor.py --mysql-version=mariadb1011

# Run the install/upgrade
/usr/share/lve/dbgovernor/mysqlgovernor.py --install

Version codes follow the pattern mariadb106, mariadb1011, mariadb114, and mysql80. The same stepwise rule applies: upgrade one major version at a time, not in a single leap.

Verify the upgrade

# Confirm the running version
mysqladmin version | grep -i "server version"

# Re-run the table check — anything that broke shows up here
mysqlcheck --all-databases --check

# Watch the error log during first traffic
tail -f /var/lib/mysql/$(hostname).err

Load a few real sites — especially anything on WooCommerce or a heavy plugin stack — and watch for 1146 (missing table) or 1932 (table doesn't exist in engine) errors, which point to an incomplete mariadb-upgrade run. Re-running mariadb-upgrade --force usually clears them.

What breaks, and how to spot it

• PHP could not connect to MySQL after upgrade — usually a socket path change. Confirm /etc/my.cnf points at the live socket and restart the engine.
• WordPress "Error establishing a database connection" site-wide — the engine didn't restart. systemctl status mariadb.
• Disk full mid-upgrade — the rewrite ran out of space. This is the worst case; restore from the dump you (hopefully) took.
• Governor in unlimited mode — see the callout above.

Next steps

• MySQL Governor modes explained
• Backup strategy for cPanel hosts in 2026
• Migrate CentOS 7 to AlmaLinux on cPanel

Need a CloudLinux license to run MySQL Governor, or sizing help for a fleet upgrade? Talk to us.