Corrigir o aviso do Nextcloud "Banco de dados com alguns índices ausentes"

Ao abrir a Visão Geral da Administração do Nextcloud, você vê a mensagem: “O banco de dados está com alguns índices ausentes”. Esse aviso pode aparecer após uma atualização, pois o Nextcloud pode adicionar novos índices a tabelas existentes ao longo do tempo, e nem sempre os cria automaticamente em bancos de dados grandes. A ausência de índices pode tornar algumas consultas ao banco de dados mais lentas. A solução recomendada é o comando integrado occ db:add-missing-indices.

Antes de alterar o esquema, confirme se está executando o comando para a instalação correta do Nextcloud, faça um backup do banco de dados e use o usuário do sistema operacional do servidor web. Em versões que suportam essa funcionalidade, visualize o SQL proposto com ` --dry-run. Em seguida, execute o reparo e verifique novamente a Visão Geral da Administração.

O que significa o aviso

Um índice de banco de dados é uma estrutura que ajuda o banco de dados a encontrar linhas sem precisar percorrer a tabela inteira. O Nextcloud e seus aplicativos definem índices para as tabelas e campos que utilizam. Quando uma versão mais recente do Nextcloud ou de um aplicativo introduz um índice que uma instalação existente ainda não possui, a página de administração pode exibir uma mensagem de erro indicando a incompatibilidade. Trata-se de um aviso de manutenção de esquema; por si só, não significa que o banco de dados esteja corrompido ou que arquivos de usuário estejam faltando.

O manual de administração do Nextcloud afirma que índices podem ser adicionados ao longo do tempo, inclusive para melhorar o desempenho, e orienta os administradores a executar o comando occ db:add-missing-indices. Adicionar um índice pode levar tempo, especialmente em tabelas grandes, e o comportamento de carga ou bloqueio do banco de dados pode variar de acordo com o mecanismo do banco de dados e a carga de trabalho. Planeje a alteração para um período de menor movimento, caso sua instância esteja ocupada.

Antes de executar o reparo

• Confirme o caminho e a versão da instalação. Execute os comandos a partir do diretório que contém o occscript da instalação desejada ou forneça o caminho completo.
• Faça backup do banco de dados. Utilize seu procedimento normal de backup para MariaDB/MySQL, PostgreSQL ou SQLite. Verifique se o backup foi concluído e se você sabe como restaurá-lo.
• Localize o usuário HTTP. Utilize a conta que executa o servidor web do Nextcloud. Exemplos comuns incluem www-datasistemas Debian ou Ubuntu, apacheFedora ou CentOS, httpArch e wwwrunopenSUSE. Sua implementação pode ser diferente.
• Verifique as opções de comando. Consulte o manual de administração da versão estável do Nextcloud 35 para obter mais informações --dry-run. Se a sua versão instalada não reconhecer a opção, consulte a occ db:add-missing-indices --helpsaída da sua versão e ignore a pré-visualização, em vez de presumir que a opção existe.

O guia oficial de backup lista o banco de dados, a configuração, o diretório de dados e outros componentes de instalação que devem ser mantidos para um backup completo. Para esta operação de esquema, faça, no mínimo, um backup de teste do banco de dados usando o procedimento apropriado para o seu banco de dados.

Passo 1: Abra um terminal na instalação do Nextcloud

Para uma instalação tradicional do Linux, conecte-se ao servidor via SSH e acesse o diretório do Nextcloud. Um caminho comum no Ubuntu é `/usr/local/nextcloud` /var/www/nextcloud, mas utilize o caminho especificado no seu servidor.

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

Confirme se a saída do comando `status` identifica a instância instalada esperada. Se você usar um binário PHP diferente para o servidor web em relação ao padrão do shell php, use a mesma versão compatível do PHP para o comando `php artisan` occ. Executar o comando occcomo o usuário HTTP ajuda a preservar a propriedade e as permissões de arquivo esperadas.

Etapa 2: Visualize as alterações do índice

Se a versão instalada do seu sistema suportar, execute primeiro o teste de simulação:

sudo -E -u www-data php occ db:add-missing-indices --dry-run

A simulação exibe uma prévia das instruções SQL sem aplicá-las. Leia a saída e confirme se ela se refere aos índices ausentes que você pretende corrigir. Se a saída identificar uma tabela ou índice que você não reconhece, anote o nome exato e verifique se o aplicativo correspondente está instalado e atualizado. Não cole o SQL visualizado no console do banco de dados como um atalho.

Etapa 3: Adicione os índices ausentes

Quando a pré-visualização estiver disponível e o backup estiver pronto, execute o comando de reparo documentado:

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

O comando verifica as tabelas do banco de dados e cria índices que estão definidos no esquema, mas que estão ausentes na instalação atual. Deixe-o terminar. Em um banco de dados grande, isso pode demorar um pouco. Evite interrompê-lo enquanto o esquema estiver sendo alterado. A documentação do Nextcloud afirma que este comando pode ser executado enquanto a instância permanece online; o modo de manutenção não é listado como um pré-requisito para este reparo específico. Siga seu próprio processo de controle de alterações se for necessária uma janela de manutenção.

Docker e outros tipos de instalação

Em uma implantação em contêiner, execute o comando occdentro do contêiner do aplicativo Nextcloud, não no contêiner do banco de dados. Os nomes de contêineres e serviços variam, portanto, verifique sua implantação e substitua o nome correto. Para um contêiner Docker chamado `<nome_do_contêiner>` nextcloud, o padrão é:

docker exec --user www-data nextcloud php occ db:add-missing-indices

Para o Docker Compose, o padrão correspondente é `<nome_do_contêiner>` docker compose exec -u www-data <nextcloud-service> php occ db:add-missing-indices. Algumas implantações empacotadas usam um comando dedicado ou um usuário de contêiner diferente; use as instruções específicas para esse pacote. Não copie o nome de um contêiner da configuração de outra pessoa sem verificá-lo.

Se o comando falhar ou o aviso persistir

• Permissão negada: Verifique o usuário HTTP e o caminho de instalação. Não resolva este problema executando o comando como root, a menos que a documentação da sua implantação exija especificamente um wrapper com privilégios elevados; o processo PHP geralmente deve ser executado como o usuário do servidor web.
• Erro de conexão com o banco de dados ou erro de PHP: verifique o log do Nextcloud, a integridade do serviço de banco de dados, a versão do PHP configurada e a saída do comando. Resolva o problema de conexão ou de execução subjacente antes de executar novamente o comando de esquema.
• Erro de chave duplicada ou índice único: Pare e guarde o texto completo do erro. Ele pode indicar linhas conflitantes que impedem a criação de um índice único. Identifique o aplicativo e a tabela afetados, confirme as versões do aplicativo e do Nextcloud e consulte o responsável pela manutenção do aplicativo ou um administrador familiarizado com o banco de dados. Não exclua linhas nem remova índices sem um diagnóstico específico dos dados e um backup.
• Mensagem "Comando não encontrado" ou opção não suportada: Confirme se você está na instalação correta do Nextcloud e verifique php occ listcomo php occ help db:add-missing-indicesusuário HTTP. Versões mais antigas podem não exibir todas as opções mais recentes.
• O aviso ainda aparece: Atualize a Visão Geral da Administração após a conclusão bem-sucedida do comando. Leia atentamente os nomes exatos do índice e da tabela exibidos no aviso. Pode haver mais de um índice ausente, um índice recém-introduzido por uma atualização do aplicativo, uma operação de banco de dados com falha ou uma incompatibilidade de esquema que este comando não resolveu.

Não confunda índices ausentes com colunas ou chaves primárias ausentes. O Nextcloud documenta comandos separados para essas alterações de esquema, como `nextcloud.repair` db:add-missing-columnse `nextcloud.repair` db:add-missing-primary-keys. Execute um reparo diferente somente quando o aviso do administrador ou a documentação específica da versão assim o exigir.

Verifique o resultado

1. Aguarde até que db:add-missing-indicesas saídas e os relatórios sejam concluídos, como por exemplo:Done.
2. Recarregue a Visão Geral da Administração e confirme se o aviso específico de índice ausente desapareceu.
3. Caso o problema persista, compare os nomes exatos da tabela e do índice com a saída do comando, em vez de executá-lo novamente sem uma comparação precisa.
4. Verifique o log do Nextcloud e a integridade do banco de dados em busca de novos erros e, em seguida, confirme se o acesso normal aos arquivos e os aplicativos que usam as tabelas afetadas ainda funcionam.
5. Mantenha o backup até que a instância esteja operando normalmente e sua política de retenção permita sua remoção.

Para a sintaxe atual dos comandos, consulte a referência de comandos de banco de dados e índice do Nextcloud . Para requisitos de usuário e PHP, consulte Usando o comando occ e o guia de backup do Nextcloud . Estas páginas estáveis ​​identificam o manual atual como Nextcloud Server 35, conforme verificado em 6 de outubro de 2026; caminhos, opções e instruções de empacotamento podem ser diferentes em outras versões ou tipos de implantação.