Como atualizar o Koha sem perder dados: versões, riscos e checklist

Como funciona o ciclo de versões do Koha

O Koha publica duas versões de funcionalidades por ano, em maio e em novembro, por volta do dia 22, segundo o calendário oficial da comunidade. A numeração segue o ano e o mês: 25.05 é a de maio de 2025, e 25.11, a de novembro de 2025. Entre elas saem versões de manutenção mensais (25.11.03, por exemplo), que trazem apenas correções de erros e de segurança.

A comunidade mantém vários ramos ao mesmo tempo e os nomeia pela antiguidade relativa: stable é o mais recente, oldstable, o anterior, e oldoldstable, o que está duas versões atrás. Além disso, desde a 22.11 existe um ramo LTS a cada dois anos, sempre em novembro, com manutenção estendida de cerca de três anos e meio, pensado para instituições que precisam de estabilidade prolongada.

Esta é a situação dos ramos no início de novembro de 2026:

A próxima versão de funcionalidades, a 26.11, está prevista pelo calendário da comunidade para novembro de 2026. Como regra prática, a comunidade mantém de duas a três versões principais ao mesmo tempo, com vida útil média de cerca de dezoito meses por ramo, exceto as LTS. Uma instância que está três ou quatro anos sem atualização já está fora de manutenção.

Que risco traz ficar em uma versão antiga

• Sem correções de segurança. Cada versão de manutenção costuma corrigir vulnerabilidades reais, como injeção de SQL, cross-site scripting e execução de código em templates. Fora dos ramos mantidos, essas correções não chegam, e o OPAC é um serviço público exposto à internet.
• Dependências do sistema operacional vencidas. O Koha roda sobre Debian ou Ubuntu, com Perl e MariaDB; se o sistema operacional também ficou sem suporte, o problema deixa de ser só do Koha.
• Funções que nunca chegam. Módulos inteiros e melhorias de acessibilidade do OPAC e da API REST só existem nas versões recentes.
• O salto fica mais caro com o tempo. Atualizar a cada seis ou doze meses é rotina; fazê-lo depois de quatro anos é um projeto, com testes, retrabalho de personalizações e novo treinamento.
• Menos gente que pode ajudar. As listas da comunidade e os fornecedores trabalham sobre as versões vigentes; em uma versão descontinuada, as respostas são escassas.

O que muda entre versões principais

Alguns marcos explicam por que o salto é tão sentido quando se acumulam vários anos. A lista não é exaustiva (cada versão principal traz centenas de correções e dezenas de melhorias), mas ajuda a antecipar o que vai mudar na tela e na operação.

De todas elas, a que mais gera trabalho em uma atualização é a passagem para o Bootstrap 5. Se o seu OPAC tem CSS próprio escrito para versões anteriores, há classes de alinhamento e de espaçamento que mudaram de nome e deixarão de ser aplicadas. Não é grave, mas é trabalho real, que precisa estar no orçamento.

A rota correta para atualizar o Koha de várias versões atrás

O Koha não salta direto de uma versão muito antiga para a atual sem passar pelas intermediárias: cada versão principal acrescentou suas próprias atualizações de esquema, e todas precisam ser aplicadas em ordem. A rota comprovada é esta:

1. Clonar a produção para um servidor de testes: banco de dados completo, arquivos de configuração, templates e CSS personalizados.
2. Registrar o ponto de partida: versão exata do Koha, do sistema operacional, do MariaDB ou MySQL, motor de busca em uso e lista de plugins instalados.
3. Atualizar o sistema operacional, se ele também ficou sem suporte. É comum um Koha de quatro anos rodar sobre um Debian que já não recebe patches.
4. Subir ramo por ramo, deixando o Koha aplicar as atualizações de esquema em cada degrau e verificando que a instância inicia antes de seguir.
5. Reconstruir os índices de busca ao chegar à versão de destino.
6. Revisar as personalizações: CSS do OPAC, templates modificados, plugins, avisos e relatórios SQL salvos.
7. Testar com a equipe da biblioteca os fluxos reais: catalogar, emprestar, devolver, reservar, renovar, gerar o relatório de fim de mês.
8. Agendar a janela de produção fora do horário de aulas, com backup imediatamente anterior e plano de retorno.

Atualização do esquema do banco de dados

É a parte que mais gera ansiedade e, paradoxalmente, a mais automatizada. Ao iniciar pela primeira vez na versão nova, o Koha detecta a versão registrada no banco de dados e executa as atualizações pendentes em sequência. Em catálogos grandes, isso pode levar de minutos a mais de uma hora, porque algumas dessas atualizações reescrevem tabelas inteiras.

Três precauções inegociáveis: fazer um dump completo do banco de dados imediatamente antes de começar, verificar que há espaço livre em disco suficiente para o crescimento temporário das tabelas e não interromper o processo no meio do caminho. Se algo falhar, restaura-se o dump e começa-se de novo; por isso, o ensaio prévio em um clone é a diferença entre um incidente controlado e uma emergência.

O que quebra: plugins, templates e CSS

O núcleo do Koha migra bem. O que exige revisão é tudo o que foi construído em cima dele:

• Plugins: cada um declara com quais versões do Koha é compatível. Um plugin sem manutenção pode ficar pelo caminho, e é preciso decidir se ele será substituído, adaptado ou descartado.
• Templates modificados diretamente: se alguém editou os arquivos de template do OPAC no servidor, essas mudanças se perdem na atualização. O correto é reimplementá-las com as preferências de personalização que o próprio Koha oferece.
• CSS do OPAC: o ponto crítico do salto para o Bootstrap 5. É preciso revisar classes de alinhamento, espaçamento e flutuação.
• Relatórios SQL salvos: consultam tabelas diretamente. Se uma versão mudou a estrutura de uma tabela, o relatório deixa de funcionar ou, pior, devolve números errados sem avisar. É preciso revalidá-los um a um.
• Integrações: autenticação com LDAP ou SAML, autoempréstimo por SIP2, coleta OAI-PMH e qualquer consumo da API REST devem ser testados explicitamente.
• Avisos e modelos de e-mail: as mensagens de vencimento e de reserva disponível podem exigir ajustes se as variáveis disponíveis tiverem mudado.

Quanto tempo leva e como treinar a equipe depois

A janela em produção costuma ser de poucas horas, mas o projeto completo inclui clonar o ambiente, ensaiar o salto, revisar personalizações e testar com a equipe. Para uma instância várias versões atrás, o realista é contar de duas a quatro semanas de trabalho antes da janela de virada.

Se a instância vem de antes do redesenho da interface da equipe, os bibliotecários vão encontrar um sistema diferente na segunda-feira de manhã. A lógica de catalogação e circulação é a mesma, mas mudam a navegação, os menus e o lugar de várias ações. Nos projetos de atualização da BiblioLabTech, isso se resolve com uma ou duas sessões curtas por área (catalogação, circulação, aquisições), apoiadas em um guia interno com capturas de tela do sistema já atualizado, e não do manual genérico. Convém ainda reservar as duas primeiras semanas com suporte reforçado: a maioria dos chamados nesse período não são falhas, e sim perguntas do tipo “onde foi parar esta opção?”.

Antes de atualizar o Koha: checklist

• Dump completo do banco de dados, verificado e restaurado pelo menos uma vez no ambiente de testes.
• Cópia dos arquivos de configuração, dos templates e do CSS personalizado.
• Inventário de plugins com sua versão e a compatibilidade declarada.
• Lista dos relatórios SQL salvos que precisam ser revalidados.
• Versão de destino decidida: estável recente ou LTS, conforme a tolerância da instituição a mudanças.
• Janela de manutenção combinada com a biblioteca, fora do calendário de provas e de matrículas.
• Plano de retorno por escrito: em que condições se aborta e quanto tempo leva restaurar.
• Responsável por avisar os usuários de que o OPAC ficará fora do ar durante a janela.

Se a sua instância está há anos sem atualização e, além disso, roda em um servidor que ninguém mantém, a atualização é o momento natural para repensar a infraestrutura: veja hospedagem Koha: nuvem gerenciada ou servidor próprio. Se o catálogo também arrasta duplicados e registros sem exemplar, convém combinar a atualização com uma depuração, como descrito no guia de migração para o Koha; e, para manter a instância em dia depois do salto, veja o que inclui o suporte Koha.

Se preferir que a BiblioLabTech faça a atualização, o serviço de Koha cobre o ensaio em um clone, a revisão de personalizações e integrações, a janela de produção combinada e o treinamento posterior. Todo projeto de Koha da BiblioLabTech inclui também o BiblioScan AI, de catalogação assistida por IA, sem custo adicional.