How to upgrade MySQL/MariaDB via WHM?

What is the MySQL/MariaDB Upgrade Interface?

The MySQL/MariaDB Upgrade interface in WHM allows you to change or upgrade the database engine version on your server. After you select a version, WHM automatically keeps your database engine up-to-date with vendor patches. This is the officially supported method for upgrading MySQL or MariaDB on a cPanel server.

Before You Upgrade

• Back up all databases before starting. Major version upgrades can cause compatibility issues with existing data.
• Review the cPanel MySQL/MariaDB upgrade guide for version-specific requirements.
• Ensure you have sufficient disk space for the upgrade process.
• MySQL to MariaDB is a one-way change. If you switch to MariaDB, you cannot revert to MySQL.
• If CloudLinux MySQL Governor is installed, you must remove it before upgrading. See CloudLinux MySQL Governor docs.
• Downgrades are not supported. Do not attempt to downgrade MySQL or MariaDB after upgrading.
• Plan for potential downtime — the database service will restart during the upgrade.

Steps to Upgrade MySQL/MariaDB

1. Log in to WHM as the root user.
2. Navigate to Home » SQL Services » MySQL/MariaDB Upgrade (in some cPanel versions, this may appear under Home » Databases » Upgrade Database Version).
3. On the upgrade page, select the version you wish to upgrade to from the available options. Click Continue.
4. Review the pre-upgrade checks and warnings. WHM will display any potential compatibility issues with your current databases, applications, or PHP configurations.
5. Select the type of upgrade (typically Unattended Upgrade for the standard automated process) and click Continue.
6. The upgrade process will begin. Do not interrupt the process — this may take several minutes to complete depending on the size of your databases.
7. Once finished, review the results screen for any errors or warnings. Click Continue to return to WHM.

Important Notes

• The phpinfo() output may show a different MySQL client library version than the server version. This is normal — it reflects the MySQL client API built into PHP, not the server version.
• After upgrading to MySQL 8.0, ensure your applications and scripts are compatible with the new version, as it includes breaking changes (e.g., removed features, new default authentication plugin).
• WHM will automatically apply minor version patches after the initial upgrade.
• The sha256_password plugin is not supported for MySQL 5.7, MySQL 8, MariaDB 10.2, or MariaDB 10.3.

Troubleshooting

• Upgrade option is missing or greyed out: Ensure no conflicting software (like CloudLinux MySQL Governor) is installed. Check that your cPanel version is up to date.
• Upgrade failed: Check /var/cpanel/logs/cpanel_install_log and /var/log/mysql/error.log for detailed error messages. Restore from backup if needed.
• Databases are not working after upgrade: Run mysql_upgrade from SSH, or check for tables that need repair in WHM » SQL Services » Repair a MySQL Database.
• Applications cannot connect: The upgrade may have changed the default authentication plugin. Check your application database credentials and ensure the user authentication method is compatible.

For official documentation, see the cPanel MySQL/MariaDB Upgrade guide.