How To Upgrade MySQL In WHM: A Step-by-Step Server Administration Guide

Upgrading your database engine in WebHost Manager (WHM) optimizes query execution, patches critical security vulnerabilities, and ensures full compatibility with modern PHP applications. This technical guide outlines the precise procedures for backing up database assets, executing the upgrade using the WHM MySQL/MariaDB Upgrade interface, and resolving configuration or schema incompatibilities. Following this methodical workflow minimizes production downtime while safeguarding critical database tables against data corruption.

Pre-Upgrade Risk Mitigation and Environment Audit

Upgrading a core database system is a one-way operation in cPanel and WHM. The migration process alters the underlying physical files, modifies system table schemas, and updates system libraries. Because WHM does not provide an automated downgrade mechanism, a failed upgrade can result in extended server downtime and corrupted data structures if executed without preparation.

Before initiating the upgrade, you must audit your entire hosting environment. Legacy web applications running on outdated Content Management Systems (CMS) or custom frameworks may utilize legacy SQL syntax or old PHP database extensions that are incompatible with modern database versions, such as MySQL 8.0 or MariaDB 10.11. For instance, the complete removal of the Query Cache in MySQL 8.0 and changes to default SQL modes can cause older database queries to fail. You must also check your PHP configurations and make sure that active PHP versions on the server have modern database extensions enabled.

• Essential System Tools: Root SSH access with key-based authentication, a terminal emulator, and an off-server storage repository (such as Amazon S3, an rsync-compatible backup server, or a local network-attached storage drive) to hold raw database exports.
• Mandatory Technical Standards: An understanding of the differences between MySQL and MariaDB, familiarity with the system configuration file located at /etc/my.cnf, and knowledge of how to manipulate active service daemons via systemd.
• Performance and Space Requirements: Free disk space equivalent to at least 200 percent of the current size of your database directory (typically located at /var/lib/mysql). This prevents write-failures during temporary table creation during the upgrade.
• Estimated Duration Benchmark: 30 to 90 minutes. This timeframe depends directly on the physical size of the databases, disk read/write speeds, and whether any system repository issues arise during compilation.

Executing the Database Upgrade Workflow in WebHost Manager

Follow these steps in sequence to perform the upgrade. Do not skip validation steps, as they ensure your server remains stable and responsive.

Step 1: Execute a Complete Physical and Logical Database Backup

Before clicking any buttons in the WHM interface, you must generate logical and physical backups of all databases.

First, log in to your server via SSH as the root user. Run a full logical dump of all databases, routines, triggers, and events by executing the following command:

mysqldump --all-databases --routines --triggers --single-transaction --quick | gzip > /home/all_databases_backup_before_upgrade.sql.gz

This command streams all database contents into a single compressed SQL file stored in the /home directory. The --single-transaction flag prevents table locks on InnoDB tables, keeping sites readable during the export, while the --quick flag streams rows directly to the disk to avoid high RAM consumption.

Next, perform a physical backup. Stop the active database service to ensure write operations cease:

systemctl stop mysql

With the database offline, duplicate the entire raw data directory using the copy command:

cp -arg /var/lib/mysql /var/lib/mysql_backup_physical

Once the physical copy is complete, restart the database service to restore site functionality while you prepare the next steps:

systemctl start mysql

Step 2: Verify Server Storage and Resource Allocation

An upgrade requires significant system memory and temporary disk write space. Verify that your server partition has sufficient storage by executing:

df -h

Review the output and ensure the partition hosting /var/lib/mysql and the partition hosting /tmp have ample space. If /tmp is mounted on a small virtual partition (e.g., 2GB or less), clear out old session files or temporarily adjust your environment to use a larger directory for temporary files during the upgrade. Ensure the system has sufficient unallocated RAM to handle compilation tasks and database indexing operations.

Step 3: Access the WHM Upgrade Interface

Log in to your WebHost Manager administrative console as the root user. Navigate to the search box in the top-left corner of the interface and type MySQL. From the filtered menu items, select MySQL/MariaDB Upgrade under the Software section.

The main pane will display your current active database software and version (such as MySQL 5.7 or MariaDB 10.3), along with a warning advising you of the risks associated with database migrations.

Step 4: Select the Target Database Version

On the upgrade screen, WHM will display a list of database engines and versions available for installation. Select the radio button corresponding to your target version (for example, MySQL 8.0 or MariaDB 10.6).

Be aware that database upgrades must be executed sequentially. If your server is currently running MySQL 5.6, you cannot upgrade directly to MySQL 8.0. You must first upgrade from MySQL 5.6 to MySQL 5.7, complete that process, and then repeat the workflow to upgrade from MySQL 5.7 to MySQL 8.0. Once you have selected your target version, click the Next button at the bottom of the screen.

Step 5: Address Software Compatibility Warnings

WHM will perform an automated pre-upgrade check and display a list of warnings, deprecation notices, and environmental blocks.

Warning: Read these warnings thoroughly. If the interface flags collation mismatches, deprecated configuration parameters in /etc/my.cnf, or outdated authentication schemes (such as legacy password hashes), do not proceed. Address these issues inside your database or configuration files before resuming the upgrade wizard.

If you are upgrading to MySQL 8.0, WHM will warn you about the change in the default authentication plugin to caching_sha2_password. If your hosted applications use older database connection libraries that only support the legacy mysql_native_password format, you will need to adjust your configuration post-upgrade. If you accept the risks, tick the confirmation checkboxes and click Continue.

Step 6: Choose the Upgrade Type and Run the Process

You will be prompted to select your upgrade implementation method:

• Interactive Upgrade: This option displays step-by-step progress, allowing you to view compiling messages, repository checks, and configuration outputs in real time. This is highly recommended for production servers.
• Unattended Upgrade: This option runs the upgrade process in the background. While convenient, it makes debugging more difficult if the process halts due to an unexpected package conflict.

Select Interactive Upgrade and click Deliver the Upgrade. WHM will initiate the upgrade process. The system will fetch the appropriate RPM packages from cPanel's mirrors, uninstall the legacy database binaries, configure the repository files, install the new version of your selected engine, and attempt to launch the service. This process can take between 5 and 20 minutes depending on server performance.

Step 7: Complete Post-Upgrade Rebuilds and Service Checks

After the upgrade interface displays a success message, you must verify that your web stack's software components are properly linked.

Navigate to the EasyApache 4 interface under the Software menu in WHM. Click Customize on your currently active profile, proceed to PHP Extensions, and ensure that the appropriate database extension (such as php-mysqlnd or php-mysqli) is fully active and compiled for all active PHP versions. If any adjustments are made, click through to Review and click Provision to rebuild your PHP binaries.

Next, return to your terminal. Check the status of the database service using:

systemctl status mysql

Ensure the service is marked as active and running. Finally, check the system upgrade log to confirm that system tables were successfully upgraded:

journalctl -u mysql -n 100

Database Engine Specifications and Version Lifecycles

This comparison table details key technical properties, default settings, and performance characteristics for standard database versions supported by modern WHM installations:

Resolving Common MySQL Upgrade Failures in WHM

During the upgrade process, environmental conflicts or configuration errors can cause the installation to fail or prevent the database service from restarting. Use the following troubleshooting strategies to resolve these issues.

Scenario 1: The Database Service Fails to Start Post-Upgrade Due to "Invalid Option" Errors

• Root Cause: The system configuration file located at /etc/my.cnf contains legacy directives (such as query_cache_size, innodb_file_format, or innodb_large_prefix) that have been completely removed in the newer version of the database software. When the systemd daemon attempts to launch the new database binary, it encounters these unrecognized variables and aborts execution.
• Actionable Fix: Open the configuration file in your terminal using an editor: nano /etc/my.cnf. Locate the lines containing the deprecated parameters and comment them out by placing a hash symbol (#) at the beginning of each line, or delete them entirely. Save the file and restart the service manually with: systemctl start mysql.

Scenario 2: Package Dependency or Broken GPG Key Errors Halt the Installer

• Root Cause: The OS package manager (yum or dnf) encounters expired or missing GPG signing keys for third-party MySQL or MariaDB repositories, or finds conflicting software packages installed outside of the standard cPanel environment.

• Actionable Fix: Force the package manager to clear its cache and import the latest repository keys. Execute the following commands in order:

  yum clean all

  rpm --rebuilddb

  If the upgrade failed due to a missing MariaDB key, manually import the official MariaDB key using the rpm import command, then return to the WHM interface and rerun the upgrade tool.

Scenario 3: Websites Display "Error Connecting to Database" Post-Upgrade

• Root Cause: Upgrading to MySQL 8.0 changes the default authentication protocol to caching_sha2_password. Legacy PHP web applications running on older engines are unable to resolve this handshake, resulting in connection refusals.

• Actionable Fix: Force the database server to fall back to the older authentication method by editing /etc/my.cnf. Add the following line under the [mysqld] block:

  default_authentication_plugin=mysql_native_password

  Save the file and restart the database service. For affected database users, log into the MySQL monitor as root and execute this SQL query to convert their authentication plugin manually:

  ALTER USER 'username'@'localhost' IDENTIFIED WITH mysql_native_password BY 'their_password'; FLUSH PRIVILEGES;

Frequently Asked Questions

Can I downgrade MySQL or MariaDB to an older version through WHM?

No, cPanel and WHM do not support downgrading database engines once an upgrade has successfully completed. The only way to revert to an older version is to completely uninstall the database server software, manually reinstall the desired older version via the command line, and restore all databases from your pre-upgrade SQL backups.

How do I switch from MySQL to MariaDB inside WebHost Manager?

You can switch from MySQL to MariaDB using the same MySQL/MariaDB Upgrade interface in WHM. Once you select a MariaDB version and complete the migration, you cannot return to a MySQL engine, as the database structural directories are modified to match MariaDB specifications.

Why is the upgrade button greyed out or missing in WHM?

This issue occurs if your server has a pending operating system upgrade, a locked package manager process, or if you are running an outdated version of cPanel/WHM that does not support the target database engine. Ensure your server is fully updated by running /usr/local/cpanel/scripts/upcp via SSH before attempting the upgrade.

How does the removal of the Query Cache in MySQL 8.0 affect my websites?

The Query Cache was deprecated because it caused performance bottlenecks on highly concurrent systems. When moving to MySQL 8.0, your sites may experience slight performance drops if they rely heavily on redundant, unoptimized database reads. You can mitigate this by adjusting your application code to use an external object caching system, such as Redis or Memcached.

What should I do if the upgrade fails halfway through and corrupts my system tables?

If the upgrade halts midway and leaves your database in a non-functional state, stop the service immediately and move the corrupted data directory to a safe location. Restore your physical directory backup by moving /var/lib/mysql_backup_physical back to /var/lib/mysql, fix ownership permissions with chown -R mysql:mysql /var/lib/mysql, and start the service to return your databases to their pre-upgrade state.

Secure Your Server Architecture with Expert Systems Administration

Maintaining optimized database engines is a fundamental component of high-performance web hosting. If you prefer to have certified systems administrators manage your database upgrades, server optimization, and proactive monitoring, contact our technical support team today.