Como Fazer Backup do SQLite para S3 em Tempo Real Sem Perder Dados

Gosta do SQLite pela sua simplicidade? Provisione um VPS novo, lance um serviço pequeno, coloque um arquivo de banco de dados ao lado dele, e tudo funciona com resposta instantânea. Sem containers Docker extras com PostgreSQL, sem gerenciamento de usuários ou configuração de direitos de acesso. Maravilhoso.

Os problemas começam quando o servidor trava inesperadamente ou o provedor "acidentalmente" exclui seu disco. Se você estava fazendo backup uma vez por dia via cron, você perdeu um dia inteiro de usuários e pedidos. Se tentou copiar o arquivo do banco de dados com um simples cp enquanto as gravações estavam acontecendo, acabou com um arquivo corrompido que o SQLite nem consegue abrir.

O criador do conhecido banco de dados chave-valor BoltDB, Ben Johnson, enfrentou exatamente esse dilema e criou o Litestream. É uma pequena ferramenta em Go que resolve o problema de backup do SQLite de uma vez por todas.

O que o Litestream Faz e Por Que Você Precisa Dele

O Litestream é executado como um processo em segundo plano no mesmo servidor que sua aplicação. Seu trabalho é transmitir continuamente alterações do seu banco de dados SQLite local para armazenamento remoto. Pode ser uma nuvem compatível com S3, Yandex Object Storage, MinIO, ou apenas uma pasta em outro disco montado.

Como resultado, você obtém um sistema de recuperação de desastres pronto para uso. Se seu VPS pegar fogo, você sobe uma nova instância, executa um único comando de restauração, e o banco de dados se recupera exatamente até a última transação antes da pane.

O principal recurso da ferramenta é a confiabilidade. Ela interage com o banco de dados estritamente através da API C oficial do SQLite, não lendo cegamente bytes brutos do disco. Isso garante que as fases de escrita não se sobreponham à compressão ou aos pontos de verificação do journal, e que o banco de dados não se transforme em um arquivo corrompido.

Como a Replicação Funciona nos Bastidores

Para entender como funciona, vamos lembrar do modo WAL (Write-Ahead Logging) do SQLite.

Por padrão, o SQLite grava alterações diretamente no arquivo principal .db. No modo WAL, todas as novas transações vão primeiro para um journal separado com a extensão -wal. Periodicamente, essas alterações são descarregadas de volta para o arquivo principal. Essa abordagem acelera as gravações e não bloqueia as leituras.

O Litestream utiliza esse mecanismo:

1. Altera o banco de dados para o modo WAL.
2. Monitora o aparecimento de novas páginas no arquivo WAL.
3. Copia essas alterações e as envia em pequenos segmentos para o S3.
4. Controla o processo de checkpoint para que o SQLite não limpe o WAL prematuramente antes dos dados serem carregados na nuvem.

O atraso no envio de dados para o S3 é de apenas alguns segundos. Se o servidor quebrar, o máximo que você perde são dados dos últimos segundos.

Configuração e Exemplo de Uso

Você pode iniciar a replicação em poucos minutos. Basta baixar o binário ou usar uma imagem Docker pronta.

Primeiro, vamos criar o arquivo de configuração litestream.yml:

dbs:
  - path: /var/lib/my-app/production.db
    replicas:
      - url: s3://my-backup-bucket/production.db

Parâmetros de conexão com o S3, como chaves de acesso e endpoint, geralmente são passados via variáveis de ambiente padrão: AWS_ACCESS_KEY_ID e AWS_SECRET_ACCESS_KEY.

O processo é iniciado com um comando simples:

litestream replicate -config /etc/litestream.yml

Frequentemente, o Litestream é executado no mesmo container Docker que a aplicação principal, usando um orquestrador de processos leve como entrypoint.sh ou supervisord.

Se o servidor travou e você precisa fazer deploy do banco de dados em um novo local, execute o comando de restauração antes de iniciar a aplicação:

litestream restore -o /var/lib/my-app/production.db s3://my-backup-bucket/production.db

O utilitário vai buscar o último dump base do bucket, baixar todos os segmentos WAL faltantes por cima, montar um arquivo de banco de dados completo, e colocá-lo no caminho especificado.

Limitações e Ressalvas

A ferramenta parece muito atraente, mas o Litestream tem um escopo definido e suas próprias limitações.

Primeiro, o utilitário requer que o modo WAL esteja habilitado. Se sua aplicação ou uma biblioteca específica de driver de banco de dados for incompatível com ele, nada vai funcionar.

Segundo, esta é uma ferramenta de recuperação de desastres, não para escalabilidade horizontal de leitura. Você não pode usar o Litestream para subir cinco cópias do serviço em servidores diferentes lendo do mesmo banco de dados replicado simultaneamente. Para cenários distribuídos com múltiplos nós, é melhor olhar para o LiteFS da mesma equipe ou projetos como o rqlite.

Terceiro, se você tem um banco de dados enorme com centenas de gigabytes e escritas constantes, os custos de tráfego e requisições de API do S3 podem ser uma surpresa desagradável. A ferramenta é projetada para cargas de trabalho pequenas a médias.

Quem Vai Encontrar Este Projeto Útil

O Litestream remove a necessidade de configurar bancos de dados pesados onde não há necessidade real deles. É uma excelente escolha para:

• Bots do Telegram e APIs REST em Go, Python ou Node.js com uma única instância de aplicação.
• Projetos em frameworks como PocketBase ou Directus rodando sobre SQLite.
• Serviços pessoais auto-hospedados rodando em VPS barato.
• Microsserviços com cache local ou isolamento de dados de clientes.

Se você estava querendo migrar um projeto pessoal para o SQLite, mas o medo de perder seu disco estava te impedindo, experimente adicionar o Litestream. A configuração leva meia hora, mas você vai dormir tranquilo.