Corrigir o erro "Banco de Dados" na interface web do Nextcloud após uma atualização: Guia prático de recuperação

Uma mensagem de erro na interface web do Nextcloud, como "Exception: Database Error", logo após uma atualização, geralmente significa que o aplicativo web consegue carregar o suficiente para alcançar a camada de banco de dados, mas uma consulta, migração, expectativa de esquema, conexão ou operação específica do aplicativo no banco de dados está falhando. Não comece excluindo tabelas, reinstalando o Nextcloud ou restaurando um diretório de código antigo sobre o novo. A sequência mais segura é identificar a consulta SQL ou migração com falha, concluir o caminho de atualização suportado, reparar apenas o que o Nextcloud sabe como reparar e verificar o serviço e o esquema do banco de dados antes de reabrir o acesso.

Esta referência segue a documentação de administração atual do Nextcloud 35, disponível em outubro de 2026. Os comandos abaixo pressupõem uma instalação comum no estilo Debian/Ubuntu /var/www/nextcloudcom o usuário do servidor web www-data. Ajuste o caminho, o binário do PHP, o comando do contêiner ou o usuário HTTP de acordo com a sua implementação.

Diagnóstico rápido: o que o erro geralmente indica.

1. Preserve o estado atual antes de fazer alterações no banco de dados.

Se você ainda tiver o backup anterior à atualização, mantenha-o intacto. O Nextcloud recomenda explicitamente um backup antes de cada atualização, e o backup integrado do atualizador cobre a base de código, mas não faz backup do banco de dados ou do diretório de dados . Se você não tiver um backup atual do banco de dados, crie um com a ferramenta de backup padrão da sua plataforma de banco de dados antes de tentar alterações ou restaurações manuais em SQL.

Evite fazer um downgrade como solução rápida. O Nextcloud afirma que o downgrade não é suportado e pode corromper dados. Se for necessário reverter para uma versão anterior, o modelo de recuperação recomendado é uma nova instalação da versão anterior seguida da restauração de um backup correspondente, e não a cópia de arquivos antigos do programa sobre um banco de dados que já iniciou a migração. Consulte a documentação do atualizador integrado do Nextcloud .

2. Leia a exceção exata do banco de dados no log do Nextcloud.

Com o registro em arquivo configurado, o log padrão fica nextcloud.logdentro do diretório de dados configurado. O guia de solução de problemas do Nextcloud recomenda verificar esse log e, quando relevante, os logs do servidor web e do PHP. Se a página de erro exibir um ID de solicitação, procure por esse ID para isolar a transação correspondente.

sudo -u www-data tail -n 100 /var/www/nextcloud/data/nextcloud.log

Não reduza o log à frase “Erro de banco de dados”. Capture o código SQLSTATE, a classe da exceção, a tabela ou coluna com falha e o aplicativo ou componente principal mencionado no rastreamento de pilha. Por exemplo, “tabela não existe” é uma falha muito diferente de “muitas conexões” ou “o servidor MySQL foi desligado”. O Nextcloud lista várias falhas comuns no estilo SQLSTATE em sua documentação geral de solução de problemas .

3. Verifique se a atualização foi realmente concluída.

O atualizador integrado substitui o código do Nextcloud primeiro. As migrações de banco de dados e de aplicativos são uma fase separada. No modo de linha de comando, o atualizador pode ser executado occ upgradeautomaticamente; caso contrário, a migração ainda precisa ser concluída posteriormente. Essa distinção explica muitos casos em que o atualizador parecia ter "concluído", mas a interface web normal retornava uma exceção de banco de dados.

cd /var/www/nextcloud
sudo -E -u www-data php occ status

Se precisar proteger a instância durante a resolução de problemas, ative o modo de manutenção. O Nextcloud descreve o modo de manutenção como o modo ideal para atualizações, pois impede novos logins e bloqueia as sessões ativas.

sudo -E -u www-data php occ maintenance:mode --on
sudo -E -u www-data php occ status

4. Conclua as migrações de banco de dados e aplicativos compatíveis com o upgrade do OCC.

Se o código foi atualizado, mas as migrações não foram concluídas, execute o comando de atualização como o usuário HTTP:

cd /var/www/nextcloud
sudo -E -u www-data php occ upgrade

Observe a saída até que o comando reporte sucesso ou pare em uma falha específica. Se falhar, corrija o pré-requisito antes de repetir o comando. Bloqueios comuns incluem um aplicativo incompatível, versão não suportada do PHP/banco de dados, serviço de banco de dados indisponível ou permissões que impedem as atualizações necessárias. Não atualize repetidamente a interface web enquanto a migração estiver falhando.

A documentação de atualização do Nextcloud também alerta para não pular versões principais. Ao migrar entre versões principais, atualize uma versão principal por vez.

5. Execute a rotina de reparo do Nextcloud após a correção do problema de migração.

maintenance:repairExecuta etapas de reparo do Nextcloud e também é executado automaticamente durante as atualizações. Executá-lo manualmente é recomendável após corrigir o problema que interrompeu a atualização.

sudo -E -u www-data php occ maintenance:repair

Isso é mais seguro do que criar instruções SQL, pois as etapas de reparo são fornecidas pelo núcleo e pelos aplicativos do Nextcloud. Não é um substituto mágico para o comando `nextcloud` occ upgradee não corrigirá um servidor de banco de dados inativo ou uma versão de banco de dados sem suporte. O comando está documentado em Comandos de sistema e manutenção do Nextcloud .

6. Verifique o serviço de banco de dados, as configurações de conexão e a versão compatível.

Se o log apontar para problemas de conectividade em vez de esquema, verifique se o serviço de banco de dados está em execução e acessível a partir do ambiente PHP do Nextcloud. Em um host MariaDB típico, uma verificação útil é:

sudo systemctl status mariadb

Em seguida, revise as configurações do banco de dados em config/config.php: tipo de banco de dados, host, nome do banco de dados, usuário e quaisquer configurações de socket ou porta. Um erro de socket Unix pode aparecer como "Arquivo ou diretório inexistente", enquanto um banco de dados remoto pode falhar devido a roteamento, DNS, TLS, regras de firewall, credenciais ou ao próprio servidor.

A compatibilidade de versões é importante após uma grande atualização do Nextcloud. Para o Nextcloud 35, as notas de lançamento oficiais indicam que o MariaDB 10.6 e o ​​MySQL 8.0 não são mais suportados; os requisitos mínimos documentados são MariaDB 10.11 LTS e MySQL 8.4 LTS. Verifique os requisitos para a sua versão principal específica do Nextcloud antes de atualizar o banco de dados por conta própria. Consulte Atualizar para o Nextcloud 35 .

7. Inspecione a deriva do esquema e adicione apenas as estruturas ausentes documentadas.

O Nextcloud 35 adiciona o `nextcloud.compares_schema` db:schema:check, que compara o esquema em produção com o esquema esperado pelo núcleo instalado e pelas migrações de aplicativos. Ele é somente leitura: relata as diferenças sem alterar o banco de dados.

sudo -E -u www-data php occ db:schema:check
sudo -E -u www-data php occ db:schema:check -v

Se a visão geral do administrador ou a saída do comando indicar a ausência de colunas opcionais, índices ou chaves primárias, utilize os comandos de manutenção documentados:

sudo -E -u www-data php occ db:add-missing-columns
sudo -E -u www-data php occ db:add-missing-indices
sudo -E -u www-data php occ db:add-missing-primary-keys

Cada um deles oferece suporte --dry-runquando você deseja visualizar o SQL. Esses comandos não devem ser usados ​​como substitutos para uma migração de núcleo com falha. Se db:schema:checkforem relatados objetos inesperados ou diferenças nas propriedades das colunas, revise as descobertas antes de alterar qualquer coisa; o Nextcloud observa que alguns valores padrão de todo o banco de dados estão fora do modelo de esquema esperado. A referência oficial de comandos é o documento Comandos DAV e de banco de dados do Nextcloud .

8. Isole as falhas de aplicativos de terceiros antes de reabrir a interface web.

Se o rastreamento de pilha mencionar um aplicativo não fornecido com o Nextcloud, a migração dele pode ser incompatível com a nova versão do servidor. O guia de solução de problemas do Nextcloud recomenda desativar aplicativos de terceiros/não fornecidos com o Nextcloud durante atualizações e solução de problemas. Use os comandos disponíveis na sua versão instalada para desativar o aplicativo suspeito específico pela linha de comando, execute o comando novamente occ upgradee só reative o aplicativo após confirmar a compatibilidade com a nova versão.

Este ramo é especialmente importante quando as tabelas principais parecem íntegras, mas a exceção menciona um namespace de fornecedor ou uma tabela pertencente a um aplicativo. Remover manualmente as tabelas desse aplicativo é arriscado, pois você pode destruir dados que o aplicativo ainda espera.

9. Saia do modo de manutenção e verifique mais do que apenas a página de login.

Após occ upgradea conclusão, as verificações de reparo/esquema não apresentarem mais problemas de bloqueio e o serviço de banco de dados estiver estável, desative o modo de manutenção:

sudo -E -u www-data php occ maintenance:mode --off

Em seguida, verifique a instância em camadas: carregue a página de login, faça login, abra o app Arquivos, navegue por algumas pastas, teste o upload/download de um arquivo, verifique as configurações de Administração em busca de avisos e revise as nextcloud.logentradas mais recentes. Confirme também se as tarefas cron/em segundo plano estão sendo executadas normalmente. Uma página inicial recuperada por si só não comprova que as migrações de aplicativos, as operações com arquivos e as tarefas em segundo plano estejam funcionando corretamente.

Lista de verificação de recuperação

• Guarde o backup anterior à atualização e evite um downgrade não suportado.
• Leia a exceção completa do banco de dados em nextcloud.log, incluindo SQLSTATE e o componente nomeado no rastreamento.
• Verifique occ statuse coloque a instância em modo de manutenção durante o reparo.
• Execute o comando occ upgradepara concluir as migrações de aplicativos e do núcleo do jogo compatíveis.
• Corrija o primeiro obstáculo concreto em vez de editar tabelas do banco de dados às cegas.
• Execute a execução maintenance:repairapós a correção da falha subjacente.
• Verifique a integridade do serviço de banco de dados, as configurações de conexão e a compatibilidade da versão.
• Utilize db:schema:checkno Nextcloud 35 e os db:add-missing-*comandos documentados quando apropriado.
• Desative o aplicativo de terceiros que está apresentando falhas se o rastreamento apontar claramente para ele e, em seguida, tente atualizar novamente.
• Desative o modo de manutenção somente após as verificações da CLI serem aprovadas e, em seguida, teste arquivos, transferências, avisos administrativos, registros e tarefas em segundo plano.

Quando restaurar em vez de reparar

Restaure a partir de um backup confiável e internamente consistente quando o próprio banco de dados estiver danificado, migrações alteraram parcialmente os dados de uma forma que você não pode reverter com segurança ou tabelas/dados necessários foram excluídos fora do Nextcloud. O banco de dados, a configuração, o diretório de dados e a versão do código devem pertencer a um ponto de recuperação compatível. Se você possui suporte pago do Nextcloud ou uma implantação crítica para os negócios, interrompa qualquer operação SQL destrutiva e entre em contato com o suporte, fornecendo o log completo, as versões exatas do Nextcloud de origem e destino, o tipo/versão do banco de dados, a versão do PHP e a saída do occcomando relevante.

O princípio fundamental é simples: um erro de banco de dados após uma atualização não é motivo para tentar adivinhar o SQL. Deixe que o log identifique a falha, conclua occ upgradeas migrações planejadas, use as ferramentas de reparo e esquema do Nextcloud e valide a plataforma de banco de dados antes de reabrir a instância.