Upgrading MySQL/MariaDB in WHM Without Breaking cPanel Sites

If you manage a cPanel/WHM server, you don't upgrade MySQL or MariaDB the way you would on a plain VPS. WHM has its own upgrade tool that touches every cPanel account's databases at once, and if you click through it without a plan, you can take down every WordPress and WooCommerce site on the box in one go. Here's how to do it without a Saturday-night rollback.

Symptom: What Goes Wrong After a WHM Database Upgrade

The upgrade itself almost always "succeeds" — WHM shows a green checkmark and MySQL comes back online. The damage shows up after, spread across different accounts:

• One client's WordPress site throws Error establishing a database connection while three others on the same server are fine.
• phpMyAdmin in cPanel loads but throws a version-mismatch warning or can't authenticate at all.
• Softaculous shows installed apps as "broken" because it can't reach the DB version it expects.
• A reseller's client calls in with Access denied for user even though nobody touched the password — because the account's DB user was still mapped to the old mysql_native_password auth plugin.
• /scripts/mysqlconnectioncheck or WHM's own service status starts flapping between up and down.

Cause: Why a Shared cPanel Server Behaves Differently

On a single-app VPS, a database upgrade is one application's problem. On a WHM server, every cPanel account's site depends on the same mysqld process, and WHM adds its own layer on top:

• cPanel's own my.cnf management. WHM writes and manages /etc/my.cnf through its own tuning presets (MySQL Governor on some setups). A major version upgrade can reset directives you'd customized, or refuse to start if a directive from the old version is no longer valid.
• DBOwner mapping breaks silently. cPanel maps each database and DB user to a cPanel account owner. If the upgrade path involves manually recreating users instead of using WHM's tool, that mapping can be lost — the DB still works from the command line, but WHM's account-level backups and the MySQL Databases page in cPanel stop showing it correctly.
• phpMyAdmin ships with cPanel, not with MySQL. A new major MySQL/MariaDB version can outpace the phpMyAdmin build bundled with your current cPanel version, especially if you haven't run /scripts/upcp recently. Update the DB first and phpMyAdmin second and you get exactly the mismatch above.
• Mixed auth plugins across hundreds of DB users. Older cPanel accounts often still have DB users created years ago under mysql_native_password. MySQL 8.x defaults new connections to caching_sha2_password. This doesn't break existing users automatically, but any script or app using an old MySQL client library can suddenly fail to authenticate against accounts it never had trouble with before.
• Skipping the required upgrade path. WHM's tool (WHM » Software » MySQL/MariaDB Upgrade) enforces one version jump at a time for a reason — going from MariaDB 10.3 straight to 10.11 isn't a supported path, and forcing it via manual repo swaps is what actually causes crashed tables, not the upgrade tool itself.

Fix: The Safe Sequence in WHM

1. Back up before touching anything

Take a full server snapshot if your VPS provider supports it — on Getwebup VPS/dedicated plans this is one click and gives you an instant rollback point. Then take an account-level backup too, since a snapshot restore means restoring the whole server, not just the databases:

/scripts/pkgacct username /backup/pre-upgrade/
# or, for all accounts:
/scripts/pkgacct --allaccts /backup/pre-upgrade/

Also dump every database independently as a second safety net:

mysqldump --all-databases --single-transaction --routines --triggers -u root -p > /root/pre-upgrade-all-dbs.sql

2. Check what you're actually running and where you're going

mysql --version
cat /var/cpanel/mysql-version
/usr/local/cpanel/scripts/mysqlgovernor.pl --status   # if CloudLinux/MySQL Governor is used

In WHM, go to Software » MySQL/MariaDB Upgrade and note the currently installed version and the next available step. Do not skip a major version — go 10.6 to 10.11, not 10.3 straight to 10.11, even if the tool lets you pick a later target.

3. Update cPanel itself first

Make sure cPanel/WHM and its bundled phpMyAdmin build are current before you touch the database engine:

/scripts/upcp --force

This avoids the phpMyAdmin-version-mismatch symptom entirely, because phpMyAdmin gets updated to a build that already understands the target MySQL/MariaDB version.

4. Run the upgrade through WHM, not manually

Use WHM » Software » MySQL/MariaDB Upgrade rather than swapping yum/apt repos and running dnf upgrade by hand. WHM's tool runs mysql_upgrade (or MariaDB's equivalent) automatically after the binary swap, which is what fixes system-table schema differences and prevents crashed-table errors on next boot. It also re-checks DBOwner mappings, which a manual repo-based upgrade won't touch.

5. Test on one account before trusting the whole server

Pick one non-critical cPanel account (or a staging clone) and confirm:

• WordPress admin loads and can save a post.
• phpMyAdmin in that account's cPanel logs in and browses tables.
• Any custom app using an older DB library (check PHP version and mysqli/PDO driver) can still connect — if not, that account's DB user may need re-authenticating with ALTER USER 'dbuser'@'localhost' IDENTIFIED WITH mysql_native_password BY 'existing_password'; as a temporary bridge while the app gets updated.

6. Roll through remaining accounts, then re-verify server-wide

mysqlcheck --all-databases -u root -p --auto-repair
systemctl status mysql
tail -f /var/log/mysqld.log

Watch the error log for a few minutes after the last account is confirmed — auth failures and deprecated-syntax warnings tend to show up as real traffic hits pages that weren't part of your manual test.

Prevention: Keep the Next Upgrade Boring

• Schedule WHM/cPanel updates (/scripts/upcp) on a regular cadence so you're never more than one cPanel version behind when a DB upgrade becomes necessary.
• Audit DB users for legacy mysql_native_password auth periodically, and migrate app credentials to caching_sha2_password ahead of time rather than during an upgrade window.
• Keep ONLY_FULL_GROUP_BY and strict SQL mode in mind when reviewing client apps for compatibility — flag old, unmaintained plugins or custom scripts before they become the thing breaking at 2am.
• Never jump more than one major version in a single WHM upgrade pass, even if the interface allows it.
• Document your pre-upgrade backup location and retention — a snapshot you can't find fast isn't a safety net.

If you're on a Getwebup managed VPS or reseller plan, our support team can run this upgrade path for you during a maintenance window, with the snapshot and account backups handled before a single package gets touched.