Upgrade e downgrade do MySQL e MariaDB no cPanel e WHM imprimir

Atualize o MySQL ou o MariaDB pelo WHM com segurança e entenda por que o cPanel não faz downgrade e qual caminho seguir quando é preciso voltar de versão.

• Tempo: 30 a 90 min, conforme o tamanho dos bancos
• Nível: Avançado
• Vale para: cPanel e WHM em AlmaLinux, CloudLinux e Ubuntu 24.04, com MySQL 8.0 e 8.4 ou MariaDB 10.5 a 11.8
• Atualizado: outubro de 2026

O cPanel troca a versão do banco de dados por uma tela própria do WHM, que cuida dos pacotes, da configuração e da conversão das tabelas. Ela só anda para a frente: não existe botão de downgrade. Antes de clicar, vale entender as regras, porque uma atualização errada não tem volta simples.

Versões que o cPanel oferece hoje

Uma instalação nova do cPanel vem com MariaDB 10.11, se ninguém escolher outra versão. Fique de olho no suporte de cada série: o MySQL 8.0 deixou de receber correções da Oracle em abril de 2026, o MariaDB 10.5 em junho de 2025 e a versão comunitária do MariaDB 10.6 em julho de 2026. Quem está em uma delas deve planejar a atualização.

As regras que não mudam

• Não há downgrade. A ferramenta do WHM não volta versão, e a própria documentação do cPanel recomenda fortemente não tentar.
• MariaDB não vira MySQL. O cPanel trata o MariaDB como uma atualização do MySQL; depois de trocar, não dá para voltar.
• MySQL 8 não vira MariaDB. Os dois ficaram incompatíveis a partir do MySQL 8, e a troca não é oferecida.

Resumindo: quem está no MySQL só sobe de MySQL, e quem está no MariaDB só sobe de MariaDB.

Antes de atualizar

1. Faça um backup lógico de todos os bancos e da configuração. É ele que permite voltar atrás se algo der errado.

   mkdir -p /root/pre-upgrade && cp -a /etc/my.cnf /root/pre-upgrade/
   mysqldump --all-databases --single-transaction --routines --events --triggers \
     | gzip > /root/pre-upgrade/todos-os-bancos.sql.gz

   Se você usa JetBackup ou snapshot do servidor, confirme que existe uma cópia recente e testada.
2. Confira o espaço livre com df -h /var/lib/mysql /root. A atualização e o backup precisam de folga.
3. Teste a compatibilidade dos sistemas. Versões antigas de WordPress, WHMCS, lojas e sistemas próprios podem ter problema com consultas ou métodos de login que mudaram. Na dúvida, consulte o fornecedor de cada sistema.
4. Revise o /etc/my.cnf. Opções que existiam na versão antiga e foram removidas impedem o banco novo de iniciar. Exemplos: query_cache_size e query_cache_type no MySQL 8, e NO_AUTO_CREATE_USER no sql_mode do MySQL 8.
5. Escolha um horário de pouco movimento e avise os clientes. Os sites ficam sem banco durante parte do processo.

Como atualizar o MySQL ou MariaDB pelo WHM

1. Abra a ferramenta. No WHM, vá em SQL Services » MySQL/MariaDB Upgrade.
2. Selecione a versão desejada e clique em Continue. Se a versão que você quer não aparece, ela não é suportada no seu sistema operacional (veja a tabela acima) ou é mais antiga que a atual.
3. Leia os avisos. O WHM valida o /etc/my.cnf e lista os pontos de atenção da versão nova. Marque as caixas de confirmação depois de ler.
4. Escolha o tipo de atualização. Unattended Upgrade faz tudo sozinho; Interactive Upgrade para a cada etapa e pede confirmação. Para a primeira vez, o modo interativo ajuda a entender onde parou se algo falhar.
5. Acompanhe até o fim. No final aparece a mensagem de sucesso ou o erro. O registro completo fica em /var/cpanel/logs/, em um arquivo ou pasta com mysql_upgrade e a data no nome.
6. Confira o resultado. Rode mysql -V, abra alguns sites que usam banco e acompanhe o log de erros do MySQL nas primeiras horas.

Preciso voltar para a versão anterior: e agora?

Os arquivos de dados são convertidos para o formato da versão nova, e a versão antiga não consegue mais lê-los. Por isso não existe downgrade "no lugar". Os caminhos possíveis:

1. Restaurar o servidor do backup ou snapshot feito antes da atualização. É o mais rápido, mas tudo o que foi gravado depois se perde, a menos que você exporte esses dados antes.
2. Levar os bancos para outro servidor com a versão desejada: exporte com mysqldump e importe lá, ou transfira as contas inteiras para outro servidor cPanel que já esteja na versão certa.
3. Usar um servidor de banco separado. Em SQL Services » Manage MySQL Profiles, o WHM pode passar a criar os bancos em outro servidor MySQL, com a versão que você escolher. Atenção: a ferramenta não move os dados existentes, o servidor remoto precisa de um /root/.my.cnf com o acesso de root e a documentação desaconselha ligar vários servidores cPanel ao mesmo banco remoto.

Problemas comuns

A atualização falhou e o MySQL não inicia

Leia o registro em /var/cpanel/logs/ e o log de erros do banco (mysql -NBe "SELECT @@log_error" mostra onde fica). A causa mais comum é uma opção do /etc/my.cnf que não existe na versão nova: comente a linha, inicie o serviço e rode a ferramenta de novo.

Plugin 'mysql_native_password' is not loaded

Aparece depois de subir para o MySQL 8.4, que desliga esse método de login antigo. Como paliativo, adicione mysql_native_password=ON na seção [mysqld] e reinicie. A solução definitiva é trocar a senha das contas afetadas para o método atual, caching_sha2_password, e atualizar sistemas que ainda dependem do método antigo.

Unknown collation: 'utf8mb4_0900_ai_ci'

Acontece ao importar um backup do MySQL 8 em uma versão que não conhece essa collation, como um MariaDB antigo. Troque a collation no arquivo antes de importar, por exemplo: sed -i 's/utf8mb4_0900_ai_ci/utf8mb4_unicode_ci/g' backup.sql.

Sites com erro de consulta depois de atualizar

Versões novas são mais rígidas com SQL mal escrito. Veja a mensagem exata no log do site. Se for sql_mode, siga o guia de strict mode abaixo, ajustando só o necessário.