Como Fazer Backup do Banco de Dados de uma Instância Mastodon Auto-Hospedada

Se você administra uma instância Mastodon auto-hospedada, perder o banco de dados significa perder todas as contas de usuário, publicações, seguidores e configurações. O banco de dados é o componente central que armazena todos os dados, exceto arquivos de mídia e emojis personalizados. Sem um backup recente, uma exclusão acidental, falha no servidor ou erro em atualização de software pode destruir sua comunidade. Este artigo explica como criar um dump PostgreSQL consistente do seu banco de dados Mastodon, automatizar o processo e verificar se o arquivo de backup é utilizável.

Por que o Banco de Dados do Mastodon Precisa de uma Estratégia de Backup Dedicada

O Mastodon usa PostgreSQL como seu banco de dados. O banco contém perfis de usuário, status, seguidores, bloqueios, denúncias e configurações de aplicativo. Anexos de mídia e emojis personalizados são armazenados separadamente no sistema de arquivos, mas o banco de dados mantém todas as referências e metadados.

Uma simples cópia do diretório de dados do PostgreSQL não é segura. O PostgreSQL usa logs de write-ahead e pode ter dados não gravados na memória. Executar pg_dump ou pg_dumpall enquanto o banco está ativo produz um snapshot consistente sem travar todo o banco. O formato customizado (-Fc) compacta a saída e permite restaurações paralelas, essencial para instâncias maiores.

A tarefa rake de backup embutida do Mastodon mastodon:backup:create é um wrapper conveniente, mas não cobre todos os cenários. Um pg_dump manual oferece controle total sobre compactação, paralelismo e criptografia. Para instâncias em produção, ambos os métodos devem ser compreendidos.

Passos para Criar um Dump PostgreSQL da Sua Instância Mastodon

Antes de começar, confirme que você tem o seguinte:

• Acesso SSH ao servidor Mastodon com privilégios sudo.
• Ferramentas cliente do PostgreSQL instaladas (pg_dump, psql).
• Espaço em disco suficiente para o arquivo de backup. Uma instância pequena com 100 usuários pode gerar um dump de 50 MB; uma instância grande com 10.000 usuários pode gerar 5 GB ou mais.
• O nome do banco de dados, usuário e senha do Mastodon. Eles estão no arquivo .env.production sob DB_NAME, DB_USER e DB_PASS.

1. Mude para o usuário mastodon
   Execute sudo -i -u mastodon para trabalhar como o usuário que possui o processo Mastodon. Isso evita erros de permissão ao ler o arquivo .env.production.
2. Leia as credenciais do banco de dados
   Abra ~/.env.production e anote os valores de DB_NAME, DB_USER e DB_PASS. O nome padrão do banco é mastodon_production e o usuário padrão é mastodon.
3. Execute pg_dump com o formato customizado
   Execute o comando a seguir, substituindo os placeholders pelos seus valores reais:
   pg_dump -Fc -h localhost -U DB_USER DB_NAME > /home/mastodon/backups/mastodon_$(date +%Y%m%d_%H%M%S).dump
   A flag -Fc seleciona o formato customizado, que é compactado e suporta restauração paralela. A flag -h localhost conecta à instância PostgreSQL local. O nome do arquivo de saída inclui um timestamp para que você possa manter várias versões.
4. Digite a senha do banco de dados
   O pg_dump solicitará a senha. Para evitar prompts interativos em scripts, crie um arquivo .pgpass:
   echo 'localhost:5432:DB_NAME:DB_USER:DB_PASS' > /home/mastodon/.pgpass && chmod 600 /home/mastodon/.pgpass
   Agora o pg_dump lerá a senha automaticamente.
5. Verifique o arquivo de dump
   Execute pg_restore --list /caminho/para/seu.dump | head -20. Isso lista o conteúdo do dump sem restaurá-lo. Se o comando retornar um sumário, o backup é válido. Se retornar um erro, o dump está corrompido e deve ser recriado.
6. Copie o backup para um local remoto
   Use rsync ou scp para transferir o arquivo de dump para um servidor separado ou armazenamento em nuvem. Nunca mantenha a única cópia na mesma máquina da instância Mastodon. Exemplo:
   rsync -avz /home/mastodon/backups/ usuario@servidor-remoto:/backups/mastodon/

Usando a Tarefa Rake do Mastodon para Backup

O Mastodon fornece uma tarefa rake que encapsula o pg_dump e também faz backup dos arquivos de mídia. Execute como o usuário mastodon:

1. Execute a tarefa rake de backup
   RAILS_ENV=production bundle exec rake mastodon:backup:create
   Isso cria um arquivo .dump e um .tar.gz do diretório public/system em ~/backups/.
2. Localize a saída
   Os arquivos são armazenados em /home/mastodon/backups/ com timestamps. O dump do banco é nomeado mastodon_production.dump e o arquivo de mídia é mastodon_production.tar.gz.
3. Remova backups antigos
   A tarefa rake não exclui backups antigos. Crie um script separado para remover arquivos com mais de 7 ou 30 dias.

Automatizando Backups de Banco de Dados com systemd

Backups manuais não são confiáveis. Use timers do systemd para executar pg_dump diariamente. Este exemplo assume que você já criou o arquivo .pgpass.

1. Crie o script de backup
   Escreva um script em /usr/local/bin/mastodon-backup-db.sh com o seguinte conteúdo:
   #!/bin/bash
BACKUP_DIR=/home/mastodon/backups
DB_NAME=mastodon_production
DB_USER=mastodon
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
pg_dump -Fc -h localhost -U $DB_USER $DB_NAME > $BACKUP_DIR/mastodon_$TIMESTAMP.dump
# Remove backups mais antigos que 30 dias
find $BACKUP_DIR -name 'dump' -mtime +30 -delete
2. Torne o script executável
   sudo chmod +x /usr/local/bin/mastodon-backup-db.sh
3. Crie uma unidade de serviço systemd
   Crie /etc/systemd/system/mastodon-backup-db.service com:
   [Unit]
Description=Backup do banco de dados Mastodon

   [Service]
Type=oneshot
User=mastodon
ExecStart=/usr/local/bin/mastodon-backup-db.sh

4. Crie uma unidade de timer systemd
   Crie /etc/systemd/system/mastodon-backup-db.timer com:
   [Unit]
   Description=Timer diário de backup do banco Mastodon

   [Timer]
   OnCalendar=daily
   Persistent=true

   [Install]
WantedBy=timers.target

5. Ative e inicie o timer
   sudo systemctl daemon-reload
sudo systemctl enable mastodon-backup-db.timer
sudo systemctl start mastodon-backup-db.timer
   Para testar o backup imediatamente, execute sudo systemctl start mastodon-backup-db.service.

Erros Comuns de Backup e Como Evitá-los

O comando pg_dump trava ou expira em instâncias grandes

Instâncias grandes com muita atividade de escrita podem fazer o pg_dump esperar por um snapshot consistente. Adicione a flag --no-blobs para excluir objetos grandes, ou use a flag -j para dump paralelo. Exemplo: pg_dump -Fc -j 4 -h localhost -U mastodon mastodon_production > backup.dump usa quatro trabalhos paralelos.

Arquivo de backup cresce demais devido a dados não utilizados

O Mastodon não executa vacuum automaticamente em dados antigos. Execute VACUUM ANALYZE periodicamente para recuperar espaço. Agende um vacuum semanal via timer systemd: psql -h localhost -U mastodon -d mastodon_production -c 'VACUUM ANALYZE;'. Isso reduz o tamanho do backup e melhora a performance de consultas.

Backup falha porque o usuário PostgreSQL não tem permissões

O usuário do banco de dados do Mastodon geralmente tem propriedade total. Se você criou um usuário de backup separado, conceda as permissões necessárias: GRANT ALL PRIVILEGES ON DATABASE mastodon_production TO backup_user; e GRANT pg_read_all_data TO backup_user; no PostgreSQL 15 e posteriores.

Formato Customizado do pg_dump vs Formato SQL Simples

Item	Formato Customizado (-Fc)	Formato SQL Simples (-Fp)
Compactação	Compactação embutida reduz o tamanho do arquivo em 60-80%	Sem compactação; saída em texto simples
Restauração paralela	Suporta pg_restore -j N para recuperação mais rápida	Restauração single-thread apenas
Restauração seletiva	Pode restaurar tabelas ou esquemas individuais	Deve restaurar o dump inteiro
Legibilidade	Arquivo binário; não legível por humanos	SQL simples; pode ser editado com editor de texto
Compatibilidade	Requer a mesma versão ou mais recente do PostgreSQL para restaurar	Funciona na maioria das versões do PostgreSQL

Para backups do Mastodon, o formato customizado é fortemente recomendado. A compactação economiza espaço em disco e o recurso de restauração paralela reduz o tempo de inatividade durante a recuperação. Use SQL simples apenas se precisar editar o dump antes de restaurar.

Após configurar backups automatizados, verifique o processo restaurando o dump em um banco de dados de teste em uma máquina separada. Execute pg_restore -d test_mastodon -j 4 /caminho/para/backup.dump e confirme que o banco de teste contém as tabelas esperadas. Este passo confirma que seu backup não só foi criado, mas também é restaurável. Para segurança adicional, criptografe o dump com GPG antes de transferi-lo para fora do local: gpg --encrypt --recipient seu-email backup.dump.