How to upgrade MySQL/MariaDB via WHM?

WHM provides a built-in interface to upgrade your server's MySQL or MariaDB database engine to a newer version. After you select a version, WHM automatically keeps the engine up-to-date with vendor patches. This guide covers the upgrade process and important prerequisites.

Before You Begin

• Back up all databases — Upgrading the database engine is a significant operation. Create a full backup using WHM's Backup interface or via command line (mysqldump --all-databases > /root/all-databases.sql).
• Check for CloudLinux MySQL Governor — If your server uses CloudLinux and MySQL Governor is installed, upgrades via this interface will not work. You must remove MySQL Governor first. See CloudLinux MySQL Governor docs.
• Review compatibility — Ensure your applications are compatible with the target database version. Check for deprecated features, especially when upgrading to MySQL 8.0.

Available Versions

• MySQL: 8.0
• MariaDB: 10.5, 10.6, 10.11

Starting after MariaDB 10.6, cPanel only supports long-term release versions of MariaDB.

Critical Limitations

• You cannot downgrade database engine versions. Downgrading can cause data corruption.
• Switching from MySQL to MariaDB is considered an upgrade, but you cannot switch from MySQL 8 to MariaDB 10.x due to incompatibilities.
• If you switch from MySQL to MariaDB, you cannot switch back to MySQL.

Step 1: Log in to WHM

Open your browser and navigate to https://your-server-ip:2087. Enter your root credentials to access the WHM dashboard.

Step 2: Open the MySQL/MariaDB Upgrade Interface

Go to Home » SQL Services » MySQL/MariaDB Upgrade.

Step 3: Select the Target Version

Choose the MySQL or MariaDB version you want to upgrade to from the list, then click Continue.

Step 4: Acknowledge Warnings

WHM will display warning messages and validate your /etc/my.cnf configuration file. Read each warning carefully, then select the checkbox next to each one to acknowledge you understand the risks. Click Continue.

Step 5: Select the Upgrade Type

Choose the upgrade method:

• Unattended Upgrade — WHM handles the entire upgrade automatically. This is the recommended option for most servers.
• Interactive Upgrade — The system pauses at certain points so you can review and confirm each stage of the process. Use this if you want more control.

Click Continue to begin the upgrade.

Step 6: Monitor the Upgrade

The upgrade process may take several minutes to complete, depending on your database size and server resources. Do not navigate away or close the browser tab. WHM will display the progress and notify you when the upgrade is complete.

Step 7: Post-Upgrade Steps

After the upgrade finishes:

• Verify the new version by running mysql -V via SSH.
• Test your websites and applications to ensure they connect to databases properly.
• Rebuild Apache/PHP if needed by running /scripts/easyapache or using WHM » Software » EasyApache 4.
• The phpinfo() output may display a different MySQL version — this shows PHP's built-in MySQL API version, not the server's database version. This is normal.

Troubleshooting

• Upgrade fails or hangs: Check WHM's /usr/local/cpanel/logs/error_log for details. Ensure you have sufficient disk space (df -h) and that no processes are locking database tables.
• "Cannot upgrade with MySQL Governor installed": Remove CloudLinux MySQL Governor before upgrading. Refer to CloudLinux documentation for removal steps.
• Applications can't connect after upgrade: Check for authentication plugin changes (MySQL 8 uses caching_sha2_password by default). You may need to alter users or update default_authentication_plugin in /etc/my.cnf.

For official documentation, see cPanel & WHM — MySQL/MariaDB Upgrade.