Backup diário do PostgreSQL para o Google Drive

[edvaldoszy]

Contexto

A API HCF roda em um container gerenciado pelo CapRover, enquanto o PostgreSQL está instalado na máquina host. Precisamos de backups automatizados diários armazenados fora do servidor, no Google Drive.

Já existe um padrão semelhante no repositório da API: script/database-sync/ — um container Debian com cron e postgresql-client-18, implantado como app separado no CapRover. O serviço de backup deve seguir a mesma abordagem.

---

Objetivo

Criar um novo serviço standalone em script/database-backup/ que:

1. Conecte-se ao PostgreSQL na máquina host
2. Execute backups agendados via cron
3. Envie o backup para uma pasta específica no Google Drive
4. Aplique uma política de retenção para evitar crescimento indefinido no Drive

---

Arquitetura proposta

• Container: Debian slim + postgresql-client-18 + rclone + cron
• Deploy: App separado no CapRover (como o database-sync)
• Estado: Container stateless; os backups ficam apenas no Google Drive (arquivos locais em /tmp são temporários)

Fluxo: cron → backup.sh → pg_dump (SQL plain) → gzip → upload via rclone → Google Drive → lógica de retenção → exclusão de backups antigos

---

Formato do backup

Decisão	Escolha
Formato do dump	SQL plain (pg_dump -Fp)
Compressão	gzip (.sql.gz) — preferível ao zip para dumps SQL
Padrão do nome	{DATABASE_NAME}_{unix_timestamp}.sql.gz
Exemplo	herbario_prod_1748469600.sql.gz

Timestamps Unix ordenam corretamente pelo nome e deixam explícito o horário do backup.

Exemplo de restore:

gunzip -c herbario_prod_<unix_ts>.sql.gz | psql -h <host> -U <user> -d <database>

---

Política de retenção

Após cada upload bem-sucedido, limpar arquivos antigos na pasta do Drive:

Nível	Regra	Quantidade
Diário	Manter os 5 backups mais recentes	5
Semanal	Entre os restantes, manter 1 por semana ISO nas 4 semanas distintas mais recentes	até 4
Excluir	Todo o restante	—

Máximo de arquivos no Drive: 9

Notas de implementação:

• Listar arquivos *.sql.gz da pasta do Drive via rclone
• Ordenar pelo timestamp Unix extraído do nome do arquivo
• Para agrupamento semanal, converter o timestamp de volta para data e usar semana ISO (%G-W%V)
• Excluir arquivos não mantidos com rclone deletefile

---

Arquivos a criar

Todos em script/database-backup/:

Arquivo	Propósito
Dockerfile	Imagem Debian slim com pg client, rclone, cron, gzip
entrypoint.sh	Gerar config do rclone a partir de env vars, registrar cron, iniciar cron
backup.sh	Dump → compressão → upload → retenção → limpeza
docker-compose.yml	Testes locais / config de referência
.env.example	Variáveis de ambiente documentadas
captain-definition.json	Config de deploy no CapRover

Seguir as convenções de script/database-sync/ (padrão do entrypoint, repasse de env vars ao cron via /etc/environment, logs em /proc/1/fd/1).

---

Variáveis de ambiente

Variável	Descrição	Exemplo
DATABASE_HOST	Endereço do PostgreSQL na host (acessível pela rede do CapRover)	10.0.10.80
DATABASE_PORT	Porta do PostgreSQL	5432
DATABASE_USER	Usuário do banco	postgres
DATABASE_PASSWORD	Senha do banco	(segredo)
DATABASE_NAME	Nome do banco	herbario_prod
GDRIVE_TOKEN	JSON do token OAuth2 do rclone	(segredo)
GDRIVE_FOLDER_ID	ID da pasta de destino no Google Drive	(da URL do Drive)
RETENTION_DAILY	Quantidade de backups diários a manter	5
RETENTION_WEEKLY	Quantidade de backups semanais a manter	4
CRON_SCHEDULE	Expressão cron	0 2 * * *
TZ	Fuso horário	America/Sao_Paulo

---

Critérios de aceite

• Novo serviço em script/database-backup/ seguindo o padrão do container database-sync
• Backup gera arquivos {database}_{unix_timestamp}.sql.gz
• Backups são enviados com sucesso para a pasta configurada no Google Drive
• Retenção mantém 5 diários + até 4 semanais; arquivos mais antigos são excluídos
• Cron executa no horário configurado sem intervenção manual
• .env.example documenta todas as variáveis necessárias
• Procedimento de restore documentado (descompressão + psql)
• Serviço implantado como app separado no CapRover

---

Checklist de testes

• Build local da imagem: docker compose build em script/database-backup/
• Executar backup manualmente dentro do container e confirmar dump + upload
• Confirmar que o arquivo aparece no Google Drive com o nome correto
• Executar retenção com vários arquivos fake/antigos e verificar que apenas os esperados permanecem
• Verificar que o cron foi registrado e que os logs aparecem nos logs do app no CapRover
• Testar restore em um banco não produtivo

---

Fora do escopo

• Backup de arquivos/mídia enviados (STORAGE_PATH) — apenas banco de dados
• Alertas em caso de falha no backup (pode ser uma issue de follow-up)
• Criptografia adicional dos backups além dos controles de acesso do Google Drive

---

Referências

• Padrão existente: script/database-sync/ (repositório hcf-api)