Backups Firebird

gbak e nbackup agendados, para um banco de dados ou para todos os bancos de uma pasta. Para o gbak, você pode ativar uma restauração de teste após cada backup. O banco de dados é atualizado a partir do backup automaticamente, e nenhuma falha no meio do processo o deixa em um estado desconhecido.

  • 6 tipos de job de backup
  • nbackup níveis 0…4
  • zip · gz · zstd com verificação do arquivo
  • S3 sem arquivo intermediário
  • restauração de teste

Duas ferramentas

gbak ou nbackup

O HQbird faz os dois tipos de backup do Firebird, e é possível combiná-los para um mesmo banco de dados. O gbak faz uma cópia lógica: ela é menor que o banco e é verificada por uma restauração. O nbackup copia as páginas do banco: é rápido, e os incrementos ocupam pouco espaço.

gbak (verified backup)nbackup (incremental)
O que copiaDados e metadados. Lixo e versões antigas de registros não entram na cópia.Páginas do arquivo do banco. O nível 0 é completo; os níveis 1…N têm só as páginas alteradas.
TamanhoEm geral bem menor que o banco; comprime bem.O nível 0 tem o tamanho do banco; os incrementos são pequenos.
RestauraçãoCria um novo banco e reconstrói os índices. Para bancos grandes, isso demora.Junta a cadeia de níveis. Rápido.
VerificaçãoRestauração de teste após cada backup, se estiver ativada no job.Verificação da cadeia por GUID. Sem nível 0 — o agente o faz na hora.
Para que serveCópia confiável, migração entre versões e servidores, Backup-Restore-Replace.Pontos de restauração frequentes durante o dia sem carga no servidor.

Se o gbak e o nbackup de um banco precisam começar no mesmo minuto, o gbak é adiado em 15 minutos. Enquanto o banco está ocupado pelo nbackup, o gbak espera (por padrão até 60 minutos) em vez de falhar.

Tipos de job

Jobs individuais e de grupo

Um job individual cuida de um banco de dados e tem suas próprias configurações. É o job para o banco principal da empresa: agendamento próprio, pasta própria, retenção própria.

Um job de grupo cuida de pastas com bancos de dados. Uma única configuração para todos os bancos do grupo. A cada ciclo, o agente escaneia as pastas de novo pelas máscaras, então um banco novo entra no backup sozinho, sem mudar as configurações.

Um bancoTodos os bancos nas pastas
gbak com verificaçãovbackupgrpvbackup
nbackup com níveisnbackupgrpnbackup
Dump do nbackupnbackup_dumpgrpnbackup_dump

O que o job de grupo inclui e o que ignora

O agente percorre as pastas e verifica cada arquivo pelas máscaras de inclusão e exclusão. Opcionalmente, também verifica o tamanho mínimo e o início do arquivo. Arquivos de backup (.fbk, .nbk, .delta, arquivos compactados) nunca entram no backup.

Um banco que tem seu próprio job individual é excluído do grupo automaticamente, mesmo se esse job estiver desativado. Um grupo gbak não inclui bancos de jobs individuais gbak. Um grupo nbackup não inclui bancos de jobs nbackup e de dump.

Bancos de sistema (nomes que começam com security e examples) são sempre ignorados. A prévia do escaneamento mostra o motivo de cada exclusão.

D:\data\ · máscara *.fdb

  1. sales.fdbno grupo
  2. stock.fdbno grupo
  3. branch_new.fdb
    banco novo: começa pelo nível 0
    no grupo
  4. erp.fdb
    tem job individual próprio
    ignorado
  5. security5.fdb
    banco de sistema
    ignorado
  6. bck_sales_20261107.fbk
    arquivo de backup
    ignorado
  7. orders.fdb.delta
    arquivo delta do nbackup
    ignorado
  • Banco sumiu da pastaEle fica “órfão”. Seus backups são mantidos por uma regra: N dias ou sempre. Ou vão na hora para a pasta _orphaned e são excluídos após 7 dias.
  • Banco renomeadoO novo nome começa uma nova cadeia a partir do nível 0. Os backups antigos são mantidos pela regra para bancos órfãos.
  • Falhas repetidasApós 5 falhas seguidas, o banco fica em pausa por 6 horas e depois é tentado de novo.
  • O erro de um banco não para o grupoO grupo continua a partir do próximo banco. É a opção “Continue with the next databases after an error”; ela vem ativada por padrão para grupos gbak, nbackup, dump e sweep.
  • Resumo do grupo na linha do job“Encontrados N bancos · com sucesso M · com erro X · tempo total”. Nos detalhes, uma tabela dos bancos com erro: nome, caminho e início do texto do erro.
  • Limite de tempoO ciclo não começa novos bancos quando o tempo acaba. Para grupos nbackup, é possível ativar a continuação a partir do próximo banco no ciclo seguinte.
  • ParalelismoQuantos bancos do grupo processar ao mesmo tempo. Há um limite comum de tarefas longas por servidor: por padrão, no máximo duas rodam ao mesmo tempo.
  • Uma operação por bancoJobs individuais e de grupo, gbak e nbackup veem os bloqueios uns dos outros.
  • Árvore de pastas como na origemCaixa de seleção “Repeat the source folder tree”: o backup do banco x/y/EMPLOYEE.FDB vai para <pasta de backups>/x/y/EMPLOYEE.FDB/. Bancos com o mesmo nome em pastas diferentes não atrapalham uns aos outros.
Jobs no HQ Monitor. Seis tipos de backup e o inventário. Os jobs de restauração ficam em um grupo separado: é preciso permiti-los explicitamente, porque eles alteram bancos de dados.

vbackup · grpvbackup

gbak: backup com verificação

Antes de cada etapa, o agente verifica o espaço livre: para o backup, para a restauração de teste, para o arquivo compactado. Se falta espaço para a restauração, ela é pulada com o motivo no_space, e o backup permanece. O gbak grava em um arquivo temporário. O arquivo recebe o nome .fbk só se o tamanho e o log do gbak estiverem corretos. Assim, um backup incompleto com nome normal nunca aparece na pasta.

  1. 1Verificação de espaçopara o backup; de novo antes da restauração e da compressão
  2. 2gbakpara um .gbaktmp temporário; no Firebird 5 — em N núcleos
  3. 3Verificaçãotamanho e log; depois o nome .fbk
  4. 4Restauração de testese ativada; um arquivo separado, não o banco de produção
  5. 5Compressãoarquivo descompactado e conferido por SHA-256
  6. 6✓ Armazenamentocópia para outra pasta; cópias antigas são excluídas
Formulário do job gbak. Agendamento com dica sobre fuso horário, pasta e nome do backup, opções do gbak em uma linha, timeouts e fatores de cálculo de espaço.
  • Nomes clarosbck_sales_20261107_02-00.fbk: o início do nome do banco e a hora. Dois bancos na mesma pasta não gravam nomes iguais.
  • Aviso de sobreposiçãoSe dois jobs gravam arquivos com o mesmo início de nome na mesma pasta, o agente e o editor avisam.
  • Resultado da restauração de testeok, failed, skipped com motivo ou not_run. Aparece no último resultado do job e no inventário. No editor, cada restauração mostra os dois comandos: backup e restauração.
  • Banco de teste antigoUm job novo faz a restauração de teste com -rep: o gbak sobrescreve a cópia da execução anterior. Antes, o agente desconecta os clientes dessa cópia. Se o caminho do banco de teste for igual ao do banco de produção ou ao banco de outro job, a restauração é pulada.
  • Logs e comandos do gbakAs últimas linhas do erro aparecem no console; o log pode ser baixado. Os logs são excluídos junto com o seu backup. O agente guarda o histórico dos comandos executados: até 50 por etapa do job, com senhas ocultas.
  • Chaves que quebram a verificação-Y envia a saída do gbak para um arquivo, mas o agente verifica o backup por essa saída. Por isso -Y é proibido. Um job de streaming também não aceita -SE na linha de restauração. O editor marca essas chaves.
  • TimeoutsSuave: um aviso. Rígido: o gbak é interrompido.
  • Tempo do gbak por etapasO próprio agente adiciona a chave -ST TDRW a cada backup e restauração e pega da saída o tempo do gbak. Um -ST próprio nas opções do job não é necessário: o editor não o aceita.
  • O login é definido pelo agenteAs chaves -user, -password, -fetch_password e -trusted são proibidas nas opções. A restauração de teste roda em nome do dono do banco, se ele estiver registrado no acesso aos bancos. A linha da restauração mostra com qual nome ela rodou.
  • Mensagens clarasEspaço e tempo em unidades comuns: “8.1 GiB free, 11.8 GiB needed”, “timed out after 60 s”.

nbackup · grpnbackup

nbackup: níveis e pontos de restauração

O nível 0 copia o banco inteiro. O nível 1 copia as páginas alteradas após o último nível 0. O nível 2 copia as alterações após o último nível 1. Para restaurar o banco para o momento desejado, bastam três arquivos.

Exemplo de agendamento: nível 0 uma vez por semana, nível 1 toda noite, nível 2 quatro vezes por dia. São 36 pontos de restauração por semana: 1 + 7 + 28. São mantidas 5 cópias do nível 0, 7 do nível 1 e 24 do nível 2.

Semana do nbackup: nível 0 no domingo, nível 1 toda noite, nível 2 quatro vezes ao dia; a restauração usa um arquivo de cada nível
nível 0 nível 1 nível 2 arquivos para restauração
  • Cadeia sem lacunasSem nível 0 — o agente o faz na hora. Para os outros níveis, é a configuração “Criar de imediato os níveis baixos que faltam”. Sem ela, a execução é pulada enquanto o nível inferior não existir.
  • Verificação por GUIDCada nível é ligado ao seu nível inferior; um arquivo estranho não entra na cadeia.
  • Três modos de agendamentoSimples — por dias e horas. Avançado — cron para cada nível, até o nível 4. Plano — regras com nível, dias e horário.
  • Dump do nbackupCópia completa do arquivo do banco fora da cadeia de níveis, com agendamento próprio.
  • Banco em estado deltaSe o banco ficou bloqueado após um nbackup interrompido, o agente tenta mesclar o delta.

Modo “plano”

Um plano é um conjunto de regras: nível, dias e horário. Os dias podem ser todos os dias, dias da semana ou dias do mês. Se duas regras coincidem no mesmo minuto, roda o nível mais baixo. O plano pode fazer um nível 0 sozinho quando o último nível 0 for mais antigo que um número de dias definido. Ele roda um nível mais baixo antes do prazo quando os incrementos passam de uma fração definida do tamanho do banco. Em um job de grupo, cada banco monta a sua própria cadeia de níveis.

O editor mostra o plano em um calendário de várias semanas à frente: qual nível roda e quando. Um botão converte um agendamento simples ou avançado em plano, e é possível desfazer isso antes de salvar.

  • Retenção por ciclosUm ciclo é um nível 0 com todos os seus incrementos. O agente mantém ou exclui o ciclo inteiro: pelo número de ciclos, por dias ou pelo volume total. O ciclo completo mais recente nunca é excluído. O editor mostra de antemão quanto espaço os backups vão ocupar.
  • Status do planoA última cópia de cada nível, o espaço ocupado e o que a próxima limpeza vai excluir. O agente atualiza o status após cada execução do plano.

Compressão · S3 · armazenamento

Onde os backups ficam

O backup pode ir direto para o S3: o gbak ou o nbackup grava em um stream, e o stream vai para o bucket. Não há arquivo intermediário no disco do servidor, então não é preciso espaço para o backup no servidor.

A compressão zip, gz ou zstd funciona tanto para backups locais quanto para backups em streaming. Para um backup local, o agente descompacta o arquivo pronto e o compara com a origem por tamanho e SHA-256. Só depois disso o arquivo de origem é excluído. Se a verificação falhar, nada é excluído.

  • Retenção por quantidadegbak: quantos arquivos manter. nbackup: quantas cópias de cada nível.
  • Cópias em outros locaisCópia para uma segunda pasta ou um caminho de rede. Envio para S3, FTP ou FTPS — por um job file_sync separado.
  • Script próprio após o backupPara o gbak. Recebe os caminhos do backup, do banco de teste e dos logs do gbak.
  • Criptografia do arquivoUm job gbak pode criptografar o arquivo zip (AES-256) com uma senha das chaves do agente, no disco e no stream para o S3. O arquivo abre no 7-Zip. A restauração encontra a chave certa sozinha.
  • Restauração a partir de arquivo compactadoO formato é detectado pelo conteúdo do arquivo, localmente e no S3.
  • Restauração a partir do S3O job de restauração lê o backup direto do bucket.
  • AntivírusÉ melhor excluir as pastas de backup e de restauração da verificação em tempo real.
  • Você escolhe a compressãoUm job novo é criado sem compressão. Na lista de formatos, o zstd vem primeiro. É possível definir uma extensão de arquivo própria para o arquivo compactado de qualquer formato.
  • Guia do Amazon S3Configuração passo a passo do bucket, das chaves e do job. Disponível em inglês e português.

Amazon S3 · armazenamentos compatíveis

Backups no S3

O agente envia os backups para um bucket do Amazon S3 ou de um armazenamento compatível. Isso funciona para jobs de gbak e de nbackup. Não é preciso outro programa.

A configuração tem três partes: preparar o bucket e a chave de acesso, criar o destino s3 nas configurações do agente e ligar o envio no job de backup. Cada job usa um de dois modos.

Cópia de arquivoStream para o S3
Arquivo no disco do servidorSim. O backup é gravado no disco e depois enviado.Não. O backup vai direto para o bucket.
Espaço em disco para o backupNecessário.Não necessário.
DestinoS3, FTP, FTPSsó S3
Remoção de cópias antigas no bucketNão. Use uma regra de ciclo de vida do bucket.Sim, pela regra de retenção do job.
Falha no envioO backup local continua válido.Não há backup: nenhum objeto fica no bucket.
  • Como escolherCópia de arquivo: quando você precisa de uma cópia local e de uma cópia no S3. Stream: quando o disco do servidor é pequeno ou o S3 é o único lugar para os backups.
  • Restauração do S3O job de restauração lê o backup em streaming direto do bucket: o mais novo ou o objeto indicado. O agente confere o tamanho e o SHA-256 de cada objeto.
  • CriptografiaA criptografia no bucket protege o objeto no lado do armazenamento. A criptografia do arquivo compactado no job protege o arquivo com uma senha antes que ele saia do servidor.
  • BucketMantenha o bloqueio de acesso público. Adicione uma regra que remove após um dia os uploads em partes não concluídos.
  • Chave só para backupsCrie um usuário separado e dê a ele apenas as permissões necessárias: gravar, ler e remover objetos, cancelar uploads e listar os uploads não concluídos do bucket. Se o bucket é criptografado com uma chave KMS, também são necessárias permissões nessa chave. Em um servidor Amazon EC2, é possível trabalhar sem chave, pela função (role) do servidor.
  • VerificaçãoExecute o job com o botão Run now, veja o resultado e faça uma restauração de teste antes de confiar no backup.

Erros comuns

ErroCausaO que fazer
AccessDeniedFalta uma permissão, ou o caminho nas permissões é outro.Verificar as permissões do usuário.
SignatureDoesNotMatchChave errada ou espaços no valor dela.Copiar a chave de novo.
PermanentRedirectA região na configuração é diferente da região do bucket.Corrigir a região.
NoSuchBucketNome do bucket errado.Corrigir o nome.
RequestTimeTooSkewedO relógio do servidor está errado.Sincronizar o relógio por NTP.

restore.replace_cycle

Backup-Restore-Replace

O ciclo reconstrói o banco de produção. O agente faz um backup gbak, restaura-o em um novo arquivo e coloca o novo arquivo no lugar do antigo. O novo banco não tem lixo, os índices são novos, e em geral ele é bem menor. O banco de produção é desconectado e renomeado com segurança: primeiro o agente o coloca em shutdown full, todas as conexões são fechadas, e só depois o arquivo recebe um novo nome.

Por padrão, o ciclo roda no sábado às 02:00; o agendamento pode ser alterado. Run now inicia o ciclo na hora, mas antes pede para digitar o nome do arquivo do banco. O banco pode ser indicado por caminho ou por alias do databases.conf.

    Clientes

    conectam sales.fdb

    Arquivos no disco

    Do shutdown até a substituição, os clientes recebem “database not found” ou “database shutdown”. Agende o ciclo para um horário em que o banco possa ficar indisponível pelo tempo do backup mais a restauração. No modo pipe, o backup e a restauração rodam ao mesmo tempo, e nenhum arquivo de backup é gravado.

    O ciclo não começa se

    • “Permitir substituição” (allow_replace) não estiver ativado no job;
    • o banco estiver em shutdown, criptografado ou for uma réplica;
    • o banco for um security DB, próprio ou de outros bancos;
    • houver arquivos de um ciclo não concluído ao lado;
    • faltar espaço em disco.

    O espaço é calculado com antecedência: o arquivo de backup e a cópia restaurada ficam no disco ao mesmo tempo, cada um com cerca do tamanho do banco. O original é renomeado, não copiado, então não ocupa espaço. Se falta espaço, o ciclo para antes do shutdown: o banco não é tocado, e os clientes continuam trabalhando.

    O que fica no disco

    Originais. Ao lado do banco ficam os últimos originais em shutdown full, de 1 a 10, por padrão 1. Os excedentes são excluídos no início do próximo ciclo, então o banco no estado anterior ao último ciclo sempre existe.

    O arquivo de backup é excluído após a substituição. Se a restauração falhou, o arquivo é mantido como .restore-failed.fbk para análise.

    Para voltar ao original: pare o banco de produção, renomeie os arquivos e execute gfix -online para o original.

    Quando o ciclo é interrompido

    O agente pode ser parado, o servidor pode reiniciar, a energia pode cair. Em uma parada normal do serviço antes da substituição, o agente deixa o gbak terminar e faz o rollback do ciclo. Para o caso de falha, antes de cada etapa o agente grava o que está fazendo em um arquivo de intenção. Na inicialização e depois a cada minuto, o agente lê esses arquivos e leva o ciclo a um estado conhecido.

    Antes da renomeação

    O banco volta para online

    O agente coloca o banco em online e restaura o atraso de fechamento.

    Antes da substituição

    Rollback

    A cópia intermediária e o backup incompleto são excluídos, o original recebe o nome anterior e volta para online.

    Após a substituição

    Conclusão

    O novo banco fica em produção, o original é mantido em shutdown. O script “após” não rodou: execute-o você mesmo se ele for importante.

    Se os arquivos no disco não correspondem a nenhum estado conhecido, o agente não altera nada, e o resultado do job começa com “operator needed”. O arquivo de intenção lista os nomes de todos os arquivos do ciclo. Coloque o banco certo no caminho dele, e o agente termina a recuperação sozinho.

    Scripts próprios antes e depois

    O script “antes do backup” roda antes do shutdown. Se ele terminar com erro, o ciclo para e o banco não é tocado. O script “após a restauração” roda após a substituição. Exemplo: copiar o arquivo de backup para um arquivo morto antes que o agente o exclua.

    VariávelAntes do backupApós a restauração
    FBAGENT_HOOK_PHASEprepost
    FBAGENT_JOB_IDid do job
    FBAGENT_DB_NAMEnome no job: alias ou caminho
    FBAGENT_DB_PATHarquivo do banco: original, onlinemesmo caminho: banco novo, online
    FBAGENT_ORIG_PATHvaziocaminho do original
    FBAGENT_FBK_PATHfuturo arquivo de backup; vazio no modo pipearquivo de backup, excluído após o script; vazio no modo pipe

    Inventário · relatório de saúde

    Controle: qual banco não tem backup

    O inventário mostra todos os arquivos de backup no servidor, inclusive os feitos por outros programas. O agente o atualiza após cada backup e por completo a cada 2 horas. Ao lado fica a tabela de restaurações: de teste e de produção, dos últimos 14 dias.

    Cada backup tem a coluna Verified: a restauração de teste passou, falhou ou não foi executada. Ao lado ficam o tamanho do banco restaurado e o tempo do gbak. Na tabela de restaurações aparecem o tamanho do banco e a duração.

    O relatório de saúde do servidor marca um banco sem backups registrados e diz por quê: o job falhou, ainda está rodando, foi adiado ou não há arquivo nas pastas. Um botão ao lado do achado abre na hora o formulário de um novo job.

    Inventário. A restauração de teste de cada cópia falha, e isso fica visível na hora. Arquivos sem job próprio são marcados como ORPHANED.
    Achados no relatório. “Sem backups para o banco”: adicione um job nbackup ou gbak com um botão.

    ← Voltar à visão geral do HQbird 2027