Como identifiquei e corrigi problemas de charset e collation no moodle (passo a passo)

Quem administra ambientes no Moodle (Modular Object-Oriented Dynamic Learning Environment) sabe que o comportamento do banco de dados precisa estar alinhado com as exigências da aplicação.

Se você já migrou uma instalação entre servidores ou atualizou versões antigas, provavelmente já enfrentou acentuação corrompida: palavras exibindo é ou ?, chamadas Ajax quebrando silenciosamente em fóruns e formulários de questionários travando.

O motivo quase sempre é a codificação legada do MySQL: o antigo charset utf8 armazenava no máximo 3 bytes por caractere. O Moodle moderno exige utf8mb4 com a collation utf8mb4_unicode_ci para suportar caracteres multilíngues, símbolos matemáticos e emojis sem corrupção de dados.

Abaixo, compartilho o roteiro de como diagnosticar o problema, auditar as variáveis, criar uma base de testes e executar a migração pelo terminal.

1. O diagnóstico: sintomas e identificação#

Os primeiros sinais de divergência de codificação costumam aparecer de três formas:

• Textos e enunciados salvos com caracteres especiais quebrados.
• Falhas em chamadas assíncronas (Ajax) que recebem retornos JSON malformados do backend.
• Erros e avisos de codificação registrados no error_log do servidor web.

Para inspecionar como as variáveis de charset e ordenação estão configuradas no servidor MySQL/MariaDB:

SHOW VARIABLES WHERE Variable_name LIKE 'character_set_%' OR Variable_name LIKE 'collation%';

Para listar exatamente quais tabelas do Moodle ainda estão fora do padrão utf8mb4_unicode_ci:

SELECT table_name, table_collation 
FROM information_schema.tables 
WHERE table_schema = 'banco_moodle' 
  AND table_collation NOT LIKE 'utf8mb4_unicode_ci';

Se o retorno listar tabelas com latin1_swedish_ci, utf8_general_ci ou utf8mb4_general_ci, a conversão é necessária.

2. A preparação: backup e ambiente de testes#

Antes de alterar qualquer estrutura em produção, a regra de ouro é gerar um dump de segurança:

# Snapshot comprimido do banco atual
mysqldump -u usuario -p --opt --default-character-set=utf8mb4 banco_moodle | gzip > moodle_pre_charset_$(date +%Y%m%d).sql.gz

Para trabalhar com segurança em ambientes críticos, você pode clonar o banco de dados em uma base temporária (banco_moodle_fix), apontar o Moodle no config.php e validar a migração antes de aplicar na base definitiva:

$CFG->dbname = 'banco_moodle_fix';

3. Passo a passo da conversão pelo terminal#

Passo 1: Habilitar prefixos grandes no innodb#

O utf8mb4 consome até 4 bytes por caractere em colunas indexadas. Para evitar que índices antigos estourem o limite padrão de 767 bytes do InnoDB durante a migração:

SET GLOBAL innodb_file_per_table = 1;
SET GLOBAL innodb_large_prefix = 1;

Passo 2: Executar o utilitário nativo de conversão do moodle#

Em vez de converter tabela por tabela manualmente via comandos ALTER TABLE, utilize o script oficial da plataforma, que preserva integridade de campos serializados em PHP:

# Executar a partir da raiz da instalacao do Moodle
php admin/cli/mysql_collation.php --collation=utf8mb4_unicode_ci

Em bases com muito histórico de logs (mdl_logstore_standard_log), o script pode levar alguns minutos reconstruindo os índices.

Passo 3: Atualizar a configuração no config.php#

Abra o config.php na raiz do Moodle e defina a nova collation na chave dboptions:

$CFG->dbtype    = 'mariadb'; // ou 'mysqli'
$CFG->dblibrary = 'native';
$CFG->dbhost    = 'localhost';
$CFG->dbname    = 'banco_moodle';
$CFG->dbuser    = 'usuario_moodle';
$CFG->dbpass    = 'SuaSenhaForte123';
$CFG->prefix    = 'mdl_';
$CFG->dboptions = array(
    'dbpersist'   => 0,
    'dbport'      => '',
    'dbsocket'    => '',
    'dbcollation' => 'utf8mb4_unicode_ci',
);

Passo 4: Normalizar linhas comprimidas (se aplicável)#

Para validar se alguma tabela precisa de ajuste no formato de linha do InnoDB:

php admin/cli/mysql_compressed_rows.php --list
php admin/cli/mysql_compressed_rows.php --fix

Passo 5: Limpar os caches da aplicação#

Após a conversão, limpe os caches em disco e em memória para que o Moodle recarregue todos os templates e strings:

php admin/cli/purge_caches.php

4. Ajustes no my.cnf (servidores dedicados/VPS)#

Se você gerencia o servidor e quer garantir que novas tabelas e conexões já negociem o charset correto na inicialização do MySQL/MariaDB, edite o /etc/mysql/my.cnf (ou /etc/my.cnf):

[client]
default-character-set = utf8mb4

[mysqld]
character_set_server = utf8mb4
collation_server = utf8mb4_unicode_ci
skip-character-set-client-handshake

Após reiniciar o daemon do banco, rode uma verificação e otimização geral:

mysqlcheck -u root -p --auto-repair --optimize --all-databases

Cuidados com a pasta moodledata e permissões#

Durante manutenções no Moodle, outro ponto que frequentemente gera falhas silenciosas é o diretório de dados (moodledata):

1. Fora do public_html: Mantenha a pasta fora do diretório público web para impedir que documentos de alunos e logs sejam acessados diretamente pelo navegador. Em painéis onde o isolamento de pastas é mais restrito, reforce a proteção com regras de negação no .htaccess ou no bloco de configuração do Nginx.
2. Permissões de Escrita: O processo do servidor web (www-data ou o usuário do painel) precisa de permissões de gravação (permissões 750 ou 770), evitando erros de upload e geração de cache.

Veja também

Infraestrutura Desincronização de handshake do MySQL em ambientes multi-tenant: cPanel, CloudLinux e CageFS

Banco de Dados Como Corrigir o Mapeamento de Bancos e Resolver Access Denied no phpMyAdmin via CLI no cPanel

Banco de Dados Como um SELECT COUNT(*) no LiveZilla derrubou o MySQL por max_connections (e como mitiguei)

Este post está licenciado sob CC BY-NC.