Running legacy MySQL versions on cPanel: from package errors to MySQL governor and Docker

Anyone managing cPanel/WHM environments has encountered this request: the server runs modern MariaDB for all customer accounts, but a legacy application strictly requires MySQL 5.6 to execute deprecated queries without errors.

The immediate question is: can cPanel run multiple SQL database engines simultaneously out of the box?

The short answer is not natively through the standard panel interface. However, there are proven architectural methods to achieve this without risking server stability.

Here is the breakdown of the package installation errors, cPanel's single-daemon limitations, and two practical solutions.

1. cPanel architecture and single-daemon limitations#

cPanel is engineered to manage a single active SQL server daemon (MariaDB or MySQL). The panel's service monitoring and maintenance routines (/scripts/restartsrv_mysql and nightly upcp tasks) strictly monitor the default UNIX socket (/var/lib/mysql/mysql.sock) on port 3306.

Attempting to install MySQL packages on top of an active MariaDB setup via the system package manager (yum/dnf) causes dependency conflicts and breaks panel automation during the next update cycle.

2. The MySQL governor attempt and the terminal error#

When investigating MySQL Governor (a tool designed to switch database versions on cPanel systems), running the standard installation command:

yum install governor-mysql

Returned a package lookup failure:

Last metadata expiration check: 0:04:41 ago on Fri 27 Mar 2026 11:53:29 AM -03.
No match for argument: governor-mysql
Error: Unable to find a match: governor-mysql

Why does this happen?#

1. Operating System Requirement: MySQL Governor is exclusive to CloudLinux OS repositories. If your server runs vanilla AlmaLinux, Rocky Linux, or CentOS without an active CloudLinux license and conversion, the package manager cannot find the repositories.
2. Package Name: On CloudLinux systems, the official package is named cl-mysql-governor.

3. Two real-world solutions#

Option a: standardizing the entire server with CloudLinux MySQL governor#

If the server runs CloudLinux with an active license, MySQL Governor is the supported method to switch database versions while keeping cPanel fully aware of the change.

Note: MySQL Governor changes the database version for the entire server (it does not run MariaDB 10.x and MySQL 5.6 concurrently for different accounts in the native service).

Execution steps:#

1. Install the Governor package:

yum install cl-mysql-governor

1. Set the target version to MySQL 5.6:

/usr/share/lve/setup/cl-mysql-utils.py --set-version=mysql56

1. Install and convert the database:

/usr/share/lve/setup/cl-mysql-utils.py --install

Critical considerations:#

• Mandatory Backups (Format Downgrade): Downgrading from modern MariaDB to legacy MySQL 5.6 breaks raw data directory compatibility in /var/lib/mysql. You must take a full mysqldump of all databases before proceeding and restore them after the downgrade.
• EasyApache 4: You may need to recompile PHP database client modules (mysqli, pdo_mysql) to match the new client libraries.

Option b: per-application isolation with Docker (the hybrid approach)#

If your goal is to keep modern MariaDB running on port 3306 for all standard accounts while providing MySQL 5.6 exclusively for a single legacy app, Docker provides complete isolation.

1. Launch a MySQL 5.6 container on alternative port 3307:#

docker run --name mysql56-legacy \
  -e MYSQL_ROOT_PASSWORD=your_secure_password_here \
  -p 3307:3306 \
  -v /var/lib/docker-mysql56:/var/lib/mysql \
  -d mysql:5.6

2. Configure the application via TCP/IP:#

In the legacy PHP application's database configuration (config.php or PDO connection), specify 127.0.0.1 and port 3307 to force a TCP network connection instead of the default UNIX socket:

<?php
$host = '127.0.0.1'; // IP forces TCP connection instead of /tmp/mysql.sock
$port = '3307';
$db   = 'legacy_db';
$user = 'legacy_user';
$pass = 'secure_password';
$charset = 'utf8mb4';

$dsn = "mysql:host=$host;port=$port;dbname=$db;charset=$charset";
$options = [
    PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
    PDO::ATTR_EMULATE_PREPARES   => false,
];

try {
    $pdo = new PDO($dsn, $user, $pass, $options);
} catch (\PDOException $e) {
    throw new \PDOException($e->getMessage(), (int)$e->getCode());
}

Choosing the right approach#

• If you need the entire server standardized on a supported legacy version, use CloudLinux with cl-mysql-governor.
• If you only need to support a single legacy application without degrading or altering the rest of your cPanel environment, running Docker on port 3307 provides clean isolation without risking cPanel update conflicts.

See also

Infrastructure MySQL handshake desynchronization in multi-tenant environments: cPanel, CloudLinux, and CageFS

Email Complete Guide to Exim Spool: Frozen Queues, Kernel Locks, and CloudLinux Troubleshooting

Servers How to fix er_password_no_match and MySQL error loops in cPanel

This post is licensed under CC BY-NC.