Verificação de restauração de backup

Um backup que termina sem erros não é o mesmo que um backup que consegue realmente restaurar. A única prova real é restaurá-lo. O Databasus faz isso por você, de forma agendada:

pega o backup mais recente
executa a restauração num container de base de dados descartável
compara a base de dados restaurada com a origem
destrói o container
reporta o resultado

O que é um agente de verificação?

O agente de verificação é um pequeno binário em Go que roda numa máquina sob o seu controle. Serve qualquer máquina com CPU, RAM e disco livres. O agente se conecta ao Databasus, coleta trabalhos de verificação de uma fila, executa-os localmente e retorna os resultados.

O que você precisa

Um servidor com acesso HTTPS de saída para a URL do seu Databasus.
Docker disponível nesse servidor. Para cada trabalho, o agente cria containers de base de dados efêmeros da mesma versão principal.
Capacidade de disco para cada trabalho de verificação que cubra o tamanho do arquivo de backup, o tamanho bruto da base de dados e uma margem de segurança adicional.
Pelo menos 1 núcleo de CPU e 512 MB de RAM disponíveis por trabalho simultâneo.

Por que checksums não bastam?

Checksums e códigos de saída pegam alguns modos de falha, mas deixam escapar outros por completo:

Checksums detectam corrupção de bits no arquivo, mas não dizem nada sobre se o dump em si está completo ou é semanticamente válido.
O código de saída do dump diz que o comando de dump rodou. Não detecta uma role sem permissões de leitura em certos objetos, uma extensão ausente na origem ou uma incompatibilidade de tablespaces. Qualquer um desses casos pode fazer com que objetos sejam silenciosamente ignorados ou removidos.
A verificação de restauração passa realmente o arquivo pela ferramenta de restauração nativa da base de dados e conta as linhas por tabela. É a única verificação que pega tudo o que foi descrito acima. Se um backup não restaurar, você descobre antes de precisar dele, e não durante um desastre.

Configuração

Criar um agente na interface

Abra Settings → Verification agents e clique em Create verification agent. Escolha um nome descritivo como staging-verifier ou eu-west-host-1. A janela seguinte mostra o token e o ID do agente.

O token é mostrado exatamente uma vez: copie-o antes de fechar a janela. Se você o perder mais tarde, use a ação Rotate token na linha do agente para emitir um novo; o token antigo deixa de funcionar no heartbeat seguinte do agente. A janela que se segue mostra os comandos de instalação para a arquitetura do seu servidor, os mesmos comandos descritos abaixo.

Iniciar o agente no seu servidor

Acesse por SSH a máquina que vai executar as verificações. Primeiro, baixe o binário do agente. Substitua https://your-databasus-host pela URL do seu Databasus e troque amd64 por arm64 se o servidor for ARM:

curl -L -o verification-agent "https://your-databasus-host/api/v1/system/verification-agent?arch=amd64" \
  && chmod +x verification-agent

Depois inicie o agente. O ID do agente e o token vêm da janela do passo anterior:

./verification-agent start \
  --databasus-host=https://your-databasus-host \
  --agent-id=<AGENT_ID> \
  --token=<TOKEN> \
  --max-cpu=2 \
  --max-ram-mb=2048 \
  --max-disk-gb=20 \
  --max-concurrent-jobs=1

O start transforma o agente em daemon e grava as flags em databasus-verification.json no diretório de trabalho, por isso reinícios posteriores podem usar ./verification-agent start sem flag nenhuma. Os logs ficam em databasus-verification.log, ao lado do binário.

O host do Databasus precisa ser https://. HTTP simples só é permitido se você adicionar --allow-insecure-http, e se destina a testes locais. Nunca exponha um agente de produção por HTTP sem criptografia.

As quatro flags --max-* são orçamentos, não alocações por trabalho. O agente as reporta ao Databasus em cada heartbeat, e o Databasus as divide pelos trabalhos simultâneos que permitir. Com --max-cpu=2 --max-ram-mb=2048 --max-concurrent-jobs=1 o único trabalho recebe os 2 CPUs e os 2 GB de RAM. Com --max-concurrent-jobs=2, cada trabalho recebe 1 CPU e 1 GB. O mínimo é 1 CPU e 512 MB por trabalho: se o orçamento não for suficiente para esse mínimo, o agente anuncia menos concorrência. O orçamento de disco é o mais fácil de errar: cada trabalho precisa de espaço para o tamanho do arquivo de backup, o tamanho bruto da base de dados e uma margem de segurança de até 5 GB adicional, por isso defina --max-disk-gb confortavelmente acima disso para a sua maior base de dados.

Gerenciar o agente

O mesmo binário oferece quatro subcomandos:

./verification-agent status — mostra se o daemon está rodando e em que trabalhos está trabalhando.
./verification-agent stop — para o daemon. As verificações em curso são reportadas ao Databasus como falhadas e voltam para a fila.
./verification-agent start — reinicia o daemon. As flags são lembradas da primeira inicialização; passe --token=<NEW> depois de uma rotação para atualizar o token salvo.
./verification-agent run — executa em primeiro plano em vez de como daemon. Use este modo ao envolver o agente numa unidade systemd ou num container Docker: esses supervisores esperam que o processo não faça fork.

A página Settings mostra três ações em cada linha de agente: ver novamente os comandos de instalação (sem revelar o token), rotacionar o token e apagar o agente. Apagar é seguro: as verificações atribuídas a esse agente voltam para a fila e são assumidas por outro agente, se houver algum disponível.

Agendamentos e notificações

A verificação de restauração é configurada por base de dados. Abra as configurações de verificação da base de dados, ative Scheduled verification e escolha um intervalo.

Opções de intervalo

After backup — a garantia mais forte: cada backup bem-sucedido é verificado assim que termina.
Hourly, daily, weekly, monthly — escolha uma frequência e uma hora do dia.
Cron — uma expressão cron em UTC para tudo o que as opções predefinidas não cobrem. Exemplos: 0 4 * * 0 (todos os domingos às 4:00 UTC) e 0 */6 * * * (a cada seis horas).

Como a fila trata o "After backup"

Uma verificação costuma ser mais lenta do que o backup que a originou, por isso, se os backups chegarem mais rápido do que as verificações terminam, a fila cresceria sem parar. O Databasus evita isso cancelando qualquer verificação pendente da mesma base de dados sempre que chega um backup novo: só o backup mais recente espera na fila. O compromisso é intencional: é melhor pular a verificação de um backup desatualizado do que passar horas verificando algo a partir do qual você nunca restauraria.

Execuções manuais

Você também pode disparar uma verificação pontual a partir da aba Restore verifications da base de dados, sem mudar o agendamento. É útil para conferir um backup específico ou testar um agente novo de ponta a ponta antes de confiar a ele a carga agendada.

Notificações

Sucesso e falha podem ser enviados por qualquer notificador já conectado à base de dados. As duas caixas de seleção, Verification success e Verification failed, são independentes. A maioria das equipes ativa só a de falha, para evitar fadiga de notificações. Consulte a documentação de notificadores para conectar Slack, Microsoft Teams, Discord, email e outros.

Ler os resultados

Cada tentativa de verificação aparece como uma linha na aba Restore verifications da base de dados. O status é um de Pending, Running, Successful, Failed ou Canceled. Ao clicar numa linha abre-se um painel com a cronologia completa, o código de saída da restauração, o tamanho da base de dados restaurada, as contagens de esquemas e tabelas e a contagem de linhas por tabela. As execuções falhadas mostram a mensagem de erro no topo do painel.