Last modified: November 29, 2022

Overview

This interface allows the root user or root-enabled resellers to manage MySQL® or MariaDB® version upgrades (for example, when you upgrade from MySQL 5.7 to 8.0). After you select your servers MySQL or MariaDB version, WHM automatically keeps your database engine up-to-date. This means, for example, that whenever the vendor releases a new patch for your servers version of MySQL or MariaDB, WHM automatically applies the patch to your installation.

Before installation

Back up your servers databases before you upgrade its database version or change to MariaDB.

Installation limitations

When upgrading or installing MySQL or MariaDB, the following limitations apply:

• The system considers MariaDB to be an upgrade from MySQL. If you change the database engine to MariaDB, you cannot change back to MySQL.
• We do not support the use of MySQLs sha256_password plugin for MySQL 5.7, MySQL 8, MariaDB 10.2, or MariaDB 10.3.
• This feature does not support downgrades of database engine versions. We strongly recommend that you do not attempt to downgrade MySQL or MariaDB.

CloudLinuxs MySQL Governor

If CloudLinuxs MySQL Governor exists on your server, MySQL upgrades will not work via this interface. If you wish to remove MySQL Governor, read CloudLinuxs MySQL Governor documentation and research how this affects you.

The phpinfo file

The phpinfo file may display a different version of MySQL than the version that you select.

• The API version that you see in the phpinfo file is the built-in MySQL API that PHP includes.
• If the buildapache application uses the MySQL libraries and headers on the server itself, and you change the MySQL version, Apache cannot function correctly. Because cPanel & WHM updates MySQL RPMs whenever Red Hat releases updates, this could automatically break thousands of servers within a few hours. For this reason, cPanel, L.L.C. always builds Apache and PHP with the -builtin option.

Amazon Relational Database Service

You can use MySQL version 5.7 or 8.0 on Amazon Relational Database Service (RDS) servers. We do not support MariaDB on Amazon RDS servers.

Available versions

The following versions of MySQL are available:

• MySQL 5.7
• MySQL 8.0
  • If your server currently runs MySQL 5.6 or earlier and you wish to upgrade it to MySQL 8.0, you must first upgrade the server to MySQL 5.7.
  • MySQL 8.0 is the only database service and version that cPanel & WHM version 100 supports for Ubuntu® 20.04.

The following versions of MariaDB are available:

• MariaDB 10.2
• MariaDB 10.3
• MariaDB 10.5
• MariaDB 10.6

Upgrade or reinstall MySQL or MariaDB

To upgrade or reinstall your servers version of MySQL or MariaDB, perform the following steps:

1. Select the version of MySQL or MariaDB that you wish to upgrade or reinstall.
2. Click Continue. A new interface will appear with warning messages, and the system will validate the /etc/my.cnf file.
   Note:

   If you are upgrading your database server from MySQL version 5.7 to 8, the Upgrade Checker via MySQLShell (optional) section will appear. This section contains the MySQL Upgrade Checker Utility tool. For more information on the MySQL Upgrade Checker Utility tool, read the MySQL Upgrade Checker Utility section of this document.

3. Select the checkbox next to each warning to acknowledge that you are aware of the potential consequences of the upgrade.
4. Click Continue.
5. Select the type of upgrade that you wish to perform:
   • Unattended Upgrade  This option automatically upgrades MySQL or MariaDB.
   • Interactive Upgrade  This option steps you through the MySQL or MariaDB upgrade process.
6. Click Continue. The upgrade process interface will appear.
   • Select or deselect the Autoscroll output checkbox to change whether the output display scrolls as the upgrade runs.
   • If you selected the Interactive Upgrade type on the previous screen, the interface will prompt you to continue through each step as the upgrade progresses. The interface may also provide instructions for additional tasks that you may need to complete before continuing through the upgrade.
7. When the upgrade finishes, the interface will display a message. The message will say whether the upgrade succeeded or errors exist that you will need to address to complete the upgrade.

The MySQL Upgrade Checker Utility

The MySQL Upgrade Checker Utility tool checks whether a MySQL database upgrade will work on the current MySQL version.

To run the MySQL Upgrade Checker Utility tool, perform the following steps:

1. Click Install and Run Checker. A progress window will appear, and it will display the results of the upgrade check.
2. Resolve any upgrade check issues.
3. Click Re-Run Checker to run the MySQL Upgrade Checker utility again.
4. Continue your MySQL upgrade if there are no new issues.

MySQL upgrade log

The system stores the MySQL and MariaDB log files in the /var/cpanel/logs directory. The log files use the mysql_upgrade_log.YYYYMMDD-hhmmss naming convention with the following designators:

• YYYY  Four-digit year.

• MM  Two-digit month.

• DD  Two-digit day.

• hh  Two-digit hour.

• mm  Two-digit minute.

• ss  Two-digit second.