Supabase storage backup: sua cópia do banco não tem nenhum arquivo

Você configurou backups para seu app do Lovable ou do Bolt, ou paga o plano do Supabase que os faz, e a palavra cumpriu seu papel: você parou de se preocupar. Aí vem uma restauração, ou uma mudança para um projeto novo, e o app volta com uma imagem quebrada onde antes ficava cada foto de perfil. Cada tabela e cada linha estão lá. As fotos sumiram, junto com cada fatura, cada exportação e cada anexo que um usuário já enviou.

Aqui está a parte que a palavra backup esconde: um Supabase storage backup é uma tarefa à parte, porque um backup do banco de dados contém uma linha para cada arquivo que seus usuários enviaram e nenhum dos arquivos. A linha está no seu banco. O arquivo está no Storage, um serviço separado, e nenhuma cópia do banco, em nenhum plano, chega lá. Este artigo mostra como fazer essa segunda cópia e em que ordem as duas metades voltam, que é a parte que dá errado mesmo quando você tem as duas.

Ajuda pensar numa biblioteca. O catálogo é uma gaveta de fichas, uma para cada livro, e cada ficha diz em que prateleira o livro está. Os livros estão nas prateleiras. Um backup do banco copia a gaveta.

O Supabase faz backup dos meus arquivos do Storage?

Não, em nenhum plano. A documentação de backups do Supabase diz que os backups não contêm os arquivos guardados pela API do Storage, só os metadados deles no banco, e o point-in-time recovery é um recurso do banco de dados, então a mesma frase cobre ele também.

O que todo backup contém, isso sim, é a lista. O Supabase mantém no seu banco Postgres uma tabela chamada storage.objects, com uma linha por arquivo em cada bucket: em que bucket ele está, o caminho, quem enviou, o tamanho e quando chegou. Essa tabela é copiada junto com todo o resto, e é exatamente por isso que um projeto restaurado parece tão completo. Cada ficha está na gaveta.

Os bytes de cada arquivo estão em outro lugar. Eles vivem no armazenamento de objetos, um serviço separado ao lado do seu banco, e uma ferramenta que copia um banco de dados nunca lê esse lugar. O plano gratuito não faz nenhum backup automático, então ali a pergunta nem se coloca; do Pro para cima, a cópia diária tem suas linhas e nenhum dos seus uploads.

Onde o Supabase guarda seus arquivos

Em dois lugares, e um backup do banco alcança um deles.

Quando um usuário envia um avatar, seu app entrega o arquivo ao Storage. O Storage grava os bytes no armazenamento de objetos sob o nome do bucket e o caminho, e na mesma operação escreve uma linha em storage.objects que o descreve. Seu app então guarda esse caminho numa das próprias tabelas, digamos uma linha de profiles com uma coluna avatar_url, e monta um link a partir dele sempre que a imagem é necessária.

Então uma imagem enviada é três coisas: os bytes no armazenamento de objetos, a linha em storage.objects que o Storage mantém, e o caminho na sua própria tabela. Um backup do banco carrega as duas últimas. Restaure-o e seu app tem cada caminho e o Storage tem cada linha, e o link que os dois montam juntos aponta para um lugar onde não há nada.

É também por isso que a falha é tão silenciosa. Cada linha bate com todas as outras, cada contagem fecha, e cada verificação que lê o banco passa, inclusive a etapa de verificação da maioria das ferramentas de backup, porque os arquivos nunca estiveram dentro daquilo que estava sendo verificado.

Como fica uma restauração com só a metade

Um projeto que passa em toda verificação e mostra uma imagem quebrada em cada lugar onde um arquivo deveria aparecer.

A restauração informa sucesso porque fez o que lhe pediram: as tabelas voltaram e as contagens de linhas batem. Abra o painel e o Storage lista cada bucket e cada arquivo dentro dele, com tamanhos e datas, porque essa listagem é lida da tabela que a restauração recolocou. O próprio guia do Supabase para restaurar um backup do painel num projeto novo descreve exatamente esse estado: os buckets e os metadados dos arquivos aparecem, e os objetos por trás deles não.

O jeito como você descobre é corriqueiro. A página da equipe mostra uma fileira de ícones de imagem quebrada onde ficavam os avatares. Um cliente responde ao e-mail da fatura do mês passado dizendo que o link abre um erro. Alguém clica num arquivo no navegador do Storage e o download falha. A ficha diz prateleira quatro, terceiro da esquerda, e a prateleira quatro está vazia.

Nada avisa você antes desse momento, porque todo aviso que você tem está ligado ao banco de dados. Como restaurar um backup do Supabase percorre as cinco formas de uma restauração voltar quebrada, e os arquivos são a linha daquela tabela sem conserto, a menos que você tenha feito uma cópia deles.

Já que a página do Storage está aberta, vale saber o que ela mostra a um estranho. Nossa varredura gratuita lê seu app ao vivo de fora e pede a cada bucket a lista de arquivos usando nada além da chave que já está no código do seu app. Em agosto de 2026 ela recebeu uma lista de 792 dos 27.269 apps que conseguiu verificar, um número da nossa própria pesquisa. Ela lê nomes e nunca baixa um arquivo, leva uns 20 segundos e não precisa de conta: escaneie seu app.

Como faço backup de um bucket do Supabase Storage?

Pelo endpoint compatível com S3, com um único comando que copia um bucket inteiro para uma pasta que você guarda.

O Supabase Storage fala o protocolo S3, o que significa que as ferramentas comuns feitas para o armazenamento da Amazon funcionam com o seu. Este é o único passo deste artigo que acontece numa linha de comando, e vale fazê-lo uma vez à mão, para você saber do que a cópia é feita.

1. No seu painel do Supabase, abra as configurações do Storage e ative o protocolo S3. A mesma página mostra a URL do endpoint e a região do seu projeto; copie os dois de lá, e não daqui.
2. Nessa página, crie um par de chaves de acesso S3. O segredo aparece uma única vez, então guarde-o num gerenciador de senhas antes de fechar a janela.
3. Instale a linha de comando da AWS, dê a ela as duas chaves como um perfil e rode uma sincronização por bucket:

aws s3 sync s3://avatars ./supabase-files/avatars \
  --endpoint-url https://<project-ref>.storage.supabase.co/storage/v1/s3 \
  --region <region>

Rode de novo amanhã e ele copia só o que mudou. O rclone faz o mesmo trabalho se você preferir; num bucket grande, a nota de solução de problemas do Supabase manda passar --s3-list-version 2, senão a listagem pode parar antes da hora.

Duas coisas sobre essa chave. A página de autenticação S3 do Supabase diz que uma chave de acesso S3 tem acesso total a todos os buckets e passa por cima do Row Level Security, então o lugar dela é um servidor ou sua própria máquina, e nunca seu app. E ela consegue escrever além de ler, porque o Supabase não emite nenhuma chave somente leitura para o Storage; quem a tiver consegue apagar arquivos com a mesma facilidade com que os copia. Trate-a como trataria sua chave service_role.

Depois coloque a pasta em algum lugar fora da sua conta do Supabase, pelo mesmo motivo pelo qual uma cópia do banco deveria viver fora dela: um projeto suspenso ou um login perdido leva junto cada cópia guardada dentro daquela conta.

Primeiro os arquivos, ou primeiro as linhas?

Primeiro o banco de dados, depois os arquivos, e os arquivos voltam pelo Storage para que o Storage escreva as linhas.

Todo upload que passa pelo Storage, vindo do seu app, do endpoint S3 ou da CLI do Supabase, faz duas coisas numa operação só: grava os bytes e escreve a linha de storage.objects que os descreve. O livro vai para a prateleira e a ficha é escrita pela mesma mão. Recoloque os arquivos por esse caminho e as linhas chegam com eles, e os dois não conseguem divergir.

A outra direção não tem mecanismo nenhum desse tipo. Copiar linhas de storage.objects de volta com uma ferramenta de banco escreve fichas e não coloca nada na prateleira. Também atrapalha o passo seguinte: por padrão, o Storage recusa um upload para um caminho que já tem linha, com um erro dizendo que o recurso já existe, e o guia de uploads do Supabase diz que isso se resolve ligando a sobrescrita. Então, quando a restauração do banco já trouxe as linhas de volta, que é o que o próprio guia de migração do Supabase manda fazer, a cópia de arquivos que vem depois precisa ter permissão para sobrescrever.

A ordem, então:

1. Restaure o banco de dados, como aquele artigo descreve.
2. Copie os arquivos de volta pelo Storage, com o aws s3 sync rodado ao contrário (primeiro a pasta, depois o bucket) ou com supabase storage cp -r, e com a sobrescrita ligada. Um bucket que não existe mais precisa ser criado antes, com o mesmo nome e a mesma configuração de público.
3. Abra um arquivo, e depois vários outros.

A versão mais limpa disso pula por completo a reprodução de storage.objects na etapa do banco e deixa os uploads escreverem cada linha do zero, de modo que nada precise ser sobrescrito nunca. É assim que a nossa própria restauração faz. Isso exige filtrar a cópia antes de reproduzi-la, o que é um passo para a ferramenta que executa a restauração.

Como conferir que você tem os dois

Abrindo arquivos, porque toda lista que você consegue puxar é lida da tabela.

O navegador de arquivos do painel, uma consulta em storage.objects e a contagem de linhas num relatório de backup descrevem todos a gaveta, e depois de uma restauração só do banco a gaveta está perfeita. O único pedido que toca a prateleira é um pedido pelo arquivo em si.

Então, depois de uma restauração, e depois da primeira cópia que você fizer, abra arquivos. Pegue um punhado de cada bucket, incluindo os mais antigos, e abra-os pelo app do jeito que um usuário faria. Um arquivo que abre voltou. Um arquivo que dá erro nunca esteve lá, diga o que disser a lista.

O que fazer esta semana

Onde o Reeve Care entra

O Care copia os arquivos junto com o banco de dados, na ordem que este artigo descreve, e os recoloca do mesmo jeito.

• Os arquivos que seus usuários enviaram também são copiados, assim que você conecta os buckets do Storage do seu app do Supabase. É uma segunda chave, pedida separadamente, porque a chave que o Supabase emite para o Storage consegue escrever além de ler, e preferimos pedir a juntá-la com a chave do banco, que não consegue.
• A cópia dos arquivos roda depois que a cópia do banco foi relida e verificada, nunca ao lado, de modo que um ponto de restauração nunca reivindica arquivos que não copiou. Uma cópia que ficou sem tempo é marcada como parcial, com as contagens reais.
• Cada ponto de restauração registra qual caminho guardava qual arquivo. Um banco devolvido a terça-feira recebe os arquivos de terça, e um arquivo que ainda está no lugar é deixado em paz.
• A restauração recoloca os arquivos pelo Storage, de modo que cada linha é escrita pelo upload que carrega o arquivo. Nada do que existe hoje é sobrescrito ou apagado, o que significa que apertar o botão em pânico não consegue destruir aquilo que você estava tentando salvar.
• Restaurar é um botão, e ele tira um instantâneo do estado atual antes de começar, de modo que a própria restauração tem um desfazer.

O Care começa em $49 por mês para um app. É um preço de tabela, e a página de preços às vezes fica abaixo do valor daqui e nunca acima.

Como uma cópia é feita, conferida e recolocada, arquivos incluídos, está desenhado passo a passo na página de backups do Supabase.

Antes de fechar esta aba, abra o Storage no seu painel e conte os buckets. Cada um é um conjunto de arquivos que nenhum backup feito pelo Supabase vai conter jamais, e o comando de sincronização acima é tudo o que é preciso para mudar isso. Se um bucket também se mostrou listável, o que um estranho tira dessa lista é a próxima coisa a ler.