Corrigir erros de migração do banco de dados Kopano após uma atualização da versão do MySQL

Um erro de migração de banco de dados do Kopano imediatamente após uma atualização de versão do MySQL ou MariaDB geralmente significa que o aplicativo e o banco de dados não estão mais em conformidade com algo que antes era implícito: estado do esquema, configurações padrão do servidor, comportamento do SQL, autenticação ou o próprio caminho de atualização. O objetivo não é simplesmente garantir kopano-serveruma inicialização perfeita. O objetivo é alcançar um estado em que o esquema seja consistente, o Kopano inicie sem erros de atualização do banco de dados, os usuários consigam acessar lojas e o fluxo de e-mails sobreviva a uma reinicialização.

Este guia se concentra em evidências. Cada etapa inclui um sinal de sucesso e um ponto em que você deve parar de tentar a mesma solução e mudar de direção. A documentação pública do administrador do Kopano é mais antiga do que as versões atuais do MySQL e do MariaDB, portanto, não presuma que todas as versões modernas de bancos de dados sejam compatíveis com todas as versões históricas do Kopano. Use a versão exata do pacote Kopano, o fornecedor do banco de dados e o erro do servidor como evidências decisivas.

Comece pelo resultado que você precisa.

Antes de alterar a configuração, defina o que significa "corrigido". Uma recuperação bem-sucedida normalmente apresenta todos estes sinais:

• kopano-serverInicia e permanece em execução após a reinicialização do serviço.
• O log do Kopano não reporta mais uma atualização de esquema de banco de dados ou falha na execução de SQL.
• O banco de dados pode ser lido e gravado pela conta Kopano configurada.
• Lojas e usuários existentes são exibidos, em vez de um esquema vazio recém-criado.
• O envio e a entrega de correspondências são retomados normalmente.
• Uma segunda reinicialização produz o mesmo resultado satisfatório.

Se você só conseguir realizar o primeiro item, continue testando. Um início temporário após a alteração sql_mode, por exemplo, não prova que o esquema subjacente esteja correto.

1. Interrompa os gravadores Kopano e faça um backup restaurável do banco de dados.

A documentação de atualização do Kopano recomenda fazer backup do banco de dados e dos arquivos de configuração, além de interromper os serviços que utilizam o banco de dados antes de iniciar a atualização. A documentação menciona especificamente a interrupção kopano-spoolerde outros kopano-servercomponentes, além de componentes opcionais que estejam em execução. Consulte a documentação de atualização do Kopano Core .

sudo systemctl stop kopano-spooler
sudo systemctl stop kopano-server

mysqldump -u root -p --single-transaction kopano > /root/kopano-before-fix.sql
ls -lh /root/kopano-before-fix.sql

Para instalações de grande porte, preserve também /etc/kopano/os arquivos de backup, anote o local de armazenamento dos anexos e siga sua política de backup de banco de dados existente. Se os anexos estiverem armazenados fora do MySQL, um dump do SQL Server por si só não constitui um backup completo do Kopano.

Antes de alterar o esquema ou as configurações do servidor, pare os serviços do Kopano que gravam no banco de dados e verifique se existe um dump recente.

Sinal de sucesso: você tem um backup que pode ser restaurado em uma instância de banco de dados separada e sabe onde os anexos externos estão armazenados. Mude a abordagem se: o próprio despejo falhar. Corrija a corrupção do banco de dados, as permissões, o espaço em disco ou a conectividade antes de tentar uma migração de esquema do Kopano.

2. Registre a versão exata do banco de dados e as alterações nos valores padrão.

Uma grande atualização do MySQL pode alterar as configurações padrão do servidor sem modificar as tabelas existentes. O MySQL 8.0, por exemplo, alterou o conjunto de caracteres padrão do servidor para utf8mb4e a ordenação padrão para utf8mb4_0900_ai_ci. Também alterou outros padrões e removeu ou tornou obsoletos comportamentos antigos. A Oracle documenta essas diferenças em Changes in MySQL 8.0 .

Capture o estado real do servidor em vez de presumir o que a atualização do pacote fez:

mysql -u root -p

SELECT VERSION();
SHOW VARIABLES LIKE 'sql_mode';
SHOW VARIABLES LIKE 'character_set_server';
SHOW VARIABLES LIKE 'collation_server';

Anote a versão do banco de dados e as configurações padrão que o Kopano está reconhecendo; esses valores ajudam a explicar falhas que ocorreram somente após a atualização do banco de dados.

Não desative imediatamente os modos SQL estritos. Um erro no modo estrito pode revelar dados legados inválidos ou SQL que precisa ser corrigido. Desativar o modo estrito pode ocultar o sintoma, mas deixar dados que falharão posteriormente. Primeiro, capture a instrução com falha ou o erro de banco de dados exato do log do Kopano.

3. Leia o primeiro erro SQL, não apenas a falha final do serviço.

O Systemd geralmente mostra apenas que kopano-serverfoi encerrado. A linha útil costuma estar mais cedo no journal ou no log do Kopano. Comece com:

journalctl -u kopano-server -n 100 --no-pager

Em seguida, classifique a falha. A tabela a seguir é um mapa prático de triagem, e não uma afirmação de que uma única causa se aplica a todas as instalações.

O changelog do Kopano confirma que algumas versões introduziram alterações de esquema que exigiram kopano-dbadmoperações específicas. Ele também registra defeitos históricos de atualização do banco de dados, incluindo falhas envolvendo definições de tabela MySQL antigas e atualizações para utf8mb4. Use o changelog do Kopano Core para encontrar a ação de manutenção correspondente à sua versão exata do Kopano.

4. Compare o esquema Kopano existente com os novos padrões do servidor.

Verifique o esquema tal como está; as configurações padrão do servidor por si só não informam a idade das tabelas do Kopano.

SHOW CREATE DATABASE kopano;
SHOW TABLE STATUS FROM kopano;

Inspecione a definição existente do banco de dados Kopano e os mecanismos de armazenamento, mantendo o erro de migração original visível para comparação.

Se o banco de dados foi originalmente criado em uma versão mais antiga do MySQL, suas tabelas podem manter conjuntos de caracteres antigos, mesmo que os objetos recém-criados agora usem o conjunto de caracteres utf8mb4 por padrão. O MySQL afirma explicitamente que a atualização da versão 5.7 para a 8.0 não converte automaticamente os objetos de banco de dados existentes para o novo conjunto de caracteres padrão. Essa distinção é importante: uma migração pode falhar quando uma nova coluna ou índice é criado com valores padrão diferentes dos objetos vizinhos.

O próprio Kopano adicionou suporte a utf8mb4 em versões posteriores do Core e documentou uma etapa específica de manutenção do banco de dados kopano-dbadm usmppara atualizar bancos de dados existentes para suporte a Unicode de 4 bytes. Não execute esse comando apenas porque o MySQL agora usa utf8mb4 por padrão; execute-o somente quando a documentação da versão do Kopano instalada ou a saída do servidor assim o exigir.

5. Se o MariaDB foi atualizado, conclua primeiro a atualização do lado do MariaDB.

Se o seu backend for MariaDB em vez de Oracle MySQL, conclua o procedimento de atualização do próprio servidor de banco de dados antes de culpar o Kopano. A documentação do MariaDB descreve o Kopano mariadb-upgradecomo a ferramenta que atualiza as tabelas do sistema e verifica as tabelas após alterações de versão principal. A documentação recomenda fazer backup de todos os bancos de dados primeiro. Consulte a referência oficial do mariadb-upgrade .

Este é um comando específico, não universal. Não o execute mariadb-upgradeem servidores Oracle MySQL. Da mesma forma, não aplique as premissas do MySQL 8.0 a um servidor MariaDB apenas porque ambos aceitam o mysqlprotocolo do cliente.

6. Verifique se a conta do banco de dados Kopano ainda possui os privilégios necessários.

O manual do administrador do Kopano afirma que o servidor precisa de permissões ALTER, incluindo CREATE` CREATE ROUTINE<username> DELETE` DROP, ...INDEXINSERTLOCK TABLESSELECTUPDATE/etc/kopano/server.cfg

Após uma migração de versão do MySQL, um administrador pode recriar usuários, alterar plugins de autenticação, mover o host do banco de dados ou restaurar permissões de forma incompleta. Teste com o mesmo nome de host e conta que o Kopano utiliza. Se a autenticação falhar antes da execução de qualquer SQL de migração, corrija primeiro o problema de conta ou de permissões.

7. Repare apenas a condição comprovada pelo erro.

Neste ponto, você já deve ter uma classe de falha concreta. Aplique a menor alteração que a explique:

• Atualização parcial do esquema Kopano: siga as instruções ou o guia de atualização do Kopano específico kopano-dbadmda versão instalada. Nunca exclua um marcador de versão nem adicione colunas manualmente apenas para que a próxima instrução seja executada.
• Incompatibilidade de conjunto de caracteres ou de ordenação: identifique primeiro a tabela e a coluna afetadas. Planeje as conversões em uma cópia restaurada antes de afetar a produção, pois as alterações de conjunto de caracteres podem alterar os tamanhos dos índices e o comportamento de comparação.
• Erro de incompatibilidade nas tabelas do sistema MariaDB: conclua o procedimento de atualização do MariaDB documentado e tente executar o Kopano novamente.
• Permissões ou autenticação: corrija a conta do banco de dados Kopano e verifique o login do host Kopano.
• Combinação de versões não suportada: interrompa os testes de configuração. Restaure o ambiente de banco de dados anterior à atualização ou migre para uma combinação Kopano/banco de dados compatível com seu fornecedor ou fonte de pacotes.

O último caso é importante. O manual do administrador do Kopano Core, disponível publicamente, é de uma geração de produto mais antiga, enquanto as versões atuais do MySQL e do MariaDB continuam a sofrer alterações. Se você não encontrar uma declaração de suporte para a sua combinação específica de software e software, a falta de documentação não deve ser interpretada como incompatibilidade.

8. Inicie o Kopano e valide mais do que apenas o estado do processo.

sudo systemctl start kopano-server
sudo systemctl start kopano-spooler

systemctl --no-pager --full status kopano-server
journalctl -u kopano-server -n 50 --no-pager

Um estado de serviço saudável é necessário, mas não suficiente; revise o log de inicialização e, em seguida, valide os armazenamentos de usuários e o fluxo de e-mails.

Após o serviço estar ativo, teste o comportamento real do aplicativo. Abra pelo menos uma caixa de correio existente, verifique se as pastas e mensagens antigas estão presentes, envie uma mensagem entre duas contas locais, envie uma mensagem de saída e confirme se a entrega de mensagens de entrada funciona. Se você usa IMAP, ActiveSync, arquivamento, componentes de vários servidores ou armazenamento externo de anexos, teste também essas opções.

Quando você deve mudar de abordagem?

Pare de repetir as alterações de esquema quando qualquer uma destas condições ocorrer:

• O erro SQL muda após cada modificação manual, sugerindo um esquema parcialmente migrado.
• O banco de dados restaurado, anterior à atualização, funciona na versão antiga do banco de dados, mas falha consistentemente na nova versão.
• Não é possível garantir que sua versão do Kopano seja compatível com a versão principal do MySQL ou MariaDB instalada.
• As verificações de tabelas relatam corrupção em vez de uma incompatibilidade de esquema normal.
• Uma conversão de conjunto de caracteres exigiria a alteração de muitas tabelas grandes sem um mecanismo de reversão testado.

Nesses casos, o caminho mais seguro costuma ser recriar o ambiente de banco de dados anterior, restaurar o backup íntegro e planejar uma atualização em etapas em um clone. A Oracle observa que o downgrade do MySQL 8.0 para o 5.7 não é suportado no local; a alternativa suportada é restaurar um backup feito antes da atualização. Consulte as notas de versão do MySQL 8.0 .

Lista de verificação final

• O backup do banco de dados e o backup da configuração do Kopano são preservados.
• A versão exata do MySQL ou MariaDB é registrada.
• O primeiro erro real de SQL foi identificado e explicado.
• Nenhuma solução alternativa abrangente para o modo SQL ou conjunto de caracteres foi aplicada sem evidências.
• A manutenção do esquema Kopano necessária corresponde à versão do Kopano instalada.
• kopano-serversobrevive a uma segunda reinicialização.
• As caixas de correio, pastas e mensagens existentes estão intactas.
• Os testes de entrega de entrada, saída e local foram bem-sucedidos.
• Os componentes opcionais utilizados pelo seu ambiente foram testados.

Um problema de migração de banco de dados é resolvido quando o esquema, o servidor de banco de dados e a versão do Kopano voltam a ser compatíveis — e não quando a mensagem de erro simplesmente desaparece. Preserve as evidências que levaram à correção, pois elas também serão necessárias para a próxima atualização do banco de dados ou do Kopano.