← Voltar ao blog

Firebird 2.5 para 3.0, 4 e 5: o que muda na migração

Migração do Firebird 2.5 para 3.0: o SQL continua válido, mas autenticação, ODS e dialeto mudam. Veja o que testar antes de subir a versão em produção.

S
Sqlify8 de novembro de 2026·7 min de leitura
firebirdmigraçãobanco de dados

A migração do Firebird 2.5 para 3.0 ou superior raramente exige reescrever SQL: procedures, triggers e consultas continuam válidos. O que quebra é a autenticação (SRP), o driver antigo e o plano de execução das queries críticas. O banco sobe com backup e restore; a aplicação é que para de conectar.

Este guia mostra o que muda em cada versão, o que costuma falhar na virada e como planejar a migração com rollback pronto.

A sintaxe do dia a dia muda?

Não. Todo SELECT, JOIN, procedure e trigger escrito para o 2.5 compila no 5.0. As versões novas só acrescentam recursos — e é justamente por isso que a migração é mais operacional do que de código.

Recurso Versão mínima
EXECUTE BLOCK 2.0
LIST(), tabelas MON$, CTE recursiva, UPDATE OR INSERT 2.1
INSERT/UPDATE/DELETE ... RETURNING 2.5
BOOLEAN, colunas IDENTITY, window functions (ROW_NUMBER, RANK) 3.0
DECFLOAT, INT128, tipos com fuso horário 4.0

Se o sistema já usa algo de versão superior à do servidor em produção, o erro aparece na compilação da procedure — não na migração.

O que realmente quebra na virada?

Quatro coisas, em ordem de frequência: autenticação, driver, plano de execução e bibliotecas externas.

Autenticação. A partir do 3.0, o Firebird usa SRP para guardar e validar senha. Senhas passam a diferenciar maiúsculas de minúsculas: Master e master deixam de ser a mesma. O Firebird 4 removeu o plugin Legacy_Auth, então cliente antigo que só sabe falar o protocolo velho não conecta de jeito nenhum.

Driver. Um cliente compilado contra a biblioteca do 2.5 pode não negociar os plugins novos. O sintoma típico é "unavailable database" ou erro de permissão que não existe no usuário. A saída é atualizar o driver (no PHP, pdo_firebird ou interbase da versão correspondente) ou ajustar a negociação no servidor:

# firebird.conf — apenas enquanto o driver não for atualizado
WireCrypt = Enabled
AuthClient = Srp256, Legacy_Auth

Cada plugin habilitado é uma porta aberta. Atualize o driver e volte a configuração restritiva depois.

Plano de execução. O otimizador mudou entre versões. Uma consulta que usava índice no 2.5 pode passar a varrer a tabela no 3.0, e o contrário também acontece. Não é bug: é estatística e custo recalculados.

Bibliotecas externas. UDF compilada em 32 bits não carrega em servidor 64 bits. Se o sistema usa função externa, teste antes de virar.

Como migrar sem derrubar a produção?

O caminho seguro é sempre o mesmo: backup, restore em ambiente separado, validação e só então a virada.

  1. Levante a versão e o charset do banco atual.
  2. Liste drivers e bibliotecas em uso por todas as aplicações que conectam.
  3. Faça backup com o gbak da versão atual.
  4. Restaure com o gbak da versão nova — é o restore que faz o upgrade do ODS.
  5. Teste a aplicação contra a base restaurada, na porta nova.
  6. Compare planos das consultas críticas.
  7. Rode a bateria de telas que mais reclamam de lentidão.
  8. Vire na janela planejada, com o banco antigo intacto para rollback.

Versão e charset em uma consulta:

SELECT
  rdb$get_context('SYSTEM', 'ENGINE_VERSION') AS VERSAO,
  rdb$get_context('SYSTEM', 'DB_NAME')        AS BANCO,
  mon$character_set_name                      AS CHARSET
FROM rdb$database
CROSS JOIN MON$DATABASE;

Backup e restore entre versões:

# backup no servidor antigo
gbak -b -v -user SYSDBA -password **** C:\dados\sistema.fdb C:\backup\sistema-2.5.fbk

# restore no servidor novo (aqui o ODS é atualizado)
gbak -c -v -user SYSDBA -password **** C:\backup\sistema-2.5.fbk C:\dados\sistema-novo.fdb

Backup gerado por versão antiga é lido pela nova. O contrário não existe: servidor 2.5 não abre banco criado pelo 5.0. Guarde o .fbk e o servidor antigo até o aceite final.

Quais consultas costumam piorar?

As que dependem de estatística desatualizada ou de índice composto fora de ordem. Recalcule a estatística dos índices das tabelas grandes logo após o restore:

SET STATISTICS INDEX IDX_LANCAMENTOS_DATA;
SET STATISTICS INDEX IDX_LANCAMENTOS_CLIENTE_DATA;

Depois compare o plano das consultas que aparecem no topo de tempo:

SET PLANONLY ON;

SELECT ID, VALOR
FROM LANCAMENTOS
WHERE IDCLIENTE = 42
  AND DATA >= '2026-10-01'
  AND DATA < '2026-11-01';

SET PLANONLY OFF;

Se o plano mudou para NATURAL, veja se o índice ainda é o adequado para o filtro. Em muitos casos o problema não é a versão: é a ordem das colunas que sempre esteve errada e o otimizador antigo escondia.

E o dia seguinte à virada?

Os incidentes pós-migração se concentram em três pontos:

  • Senha com maiúscula que funcionava antes e agora falha.
  • Job ou integração que usa driver antigo e ninguém lembrou de testar.
  • Rotina noturna que ficou mais lenta por causa de plano novo em tabela grande.

Ter um usuário de aplicação com senha compartilhada em vários sistemas aumenta o risco: cada ponto precisa ser atualizado. Prefira usuário por aplicação, com senha própria.

Passo a passo resumido

  1. Inventarie versão, charset, drivers e UDFs.
  2. Faça backup e restaure na versão nova, em ambiente separado.
  3. Teste conexão, login e as dez telas mais usadas.
  4. Recalcule estatísticas e compare planos.
  5. Corrija índice e query que pioraram.
  6. Documente o rollback e vire na janela.
  7. Monitore a primeira semana com as tabelas MON$.

Checklist de virada

  • Backup testado com restore completo, não só gerado.
  • Todos os drivers atualizados e testados.
  • Senhas conferidas quanto a maiúsculas e minúsculas.
  • UDFs e bibliotecas externas validadas na arquitetura nova.
  • Planos das consultas críticas comparados antes e depois.
  • Estatísticas dos índices recalculadas.
  • Rollback documentado e servidor antigo disponível.
  • Monitoramento ativo na primeira semana.

Perguntas frequentes

Preciso reescrever procedures na migração do 2.5 para o 3.0?

Não. A sintaxe procedural continua compatível. Só reescreva o que usar recurso exclusivo da versão de destino ou o que depender de comportamento antigo do otimizador.

Posso pular do Firebird 2.5 direto para o 5.0?

Sim. O restore com o gbak da versão de destino faz o upgrade do ODS em uma etapa. O que não pode é abrir banco novo em servidor antigo.

O backup do 2.5 restaura no Firebird 5?

Sim, backup antigo é lido por versão mais nova. O inverso não funciona: o servidor 2.5 não entende o formato de banco gerado pelo 5.0.

Conclusão

Migrar Firebird é mais planejamento do que código: backup, restore em ambiente separado, drivers atualizados e planos comparados. Feito nessa ordem, a virada dura uma janela e o rollback fica disponível. Feito no escuro, vira noite em claro descobrindo qual integração usa driver de 2012.

Se o problema aparecer depois da virada, com consulta lenta em tabela grande, o Sqlify ajuda a reescrever a query em Firebird a partir da descrição em português, com filtros e junções explicados. Descreva o que precisa e revise o SQL antes de rodar.

Leia também: