Read this guide in English

Como baixar um backup do Supabase em arquivo .sql

Versão curta: a maioria dos projetos não consegue baixar os backups que o Supabase faz. Projetos mais novos usam backups físicos, que podem ser restaurados no próprio projeto ou, em planos pagos, em um projeto novo, mas não baixados. Mas gerar um arquivo .sql equivalente por conta própria é um único comando, funciona em qualquer plano (inclusive o Free), e o resultado restaura em um projeto Supabase novo depois que você ativa as extensões que o schema usa e, se houver tabelas ligadas a auth.users, restaura os usuários do Auth antes — em outro Postgres, também o schema auth e as roles do Supabase. Os dois caminhos estão abaixo, mais uma armadilha na CLI oficial que deixa gente com um “backup” sem nenhum dado dentro.

Verifique o painel primeiro — às vezes o botão existe

Painel → Database → Backups. O que você encontra depende do processo de backup do seu projeto. Projetos antigos ainda em backups lógicos conseguem baixar cada backup diário nessa página, e pronto. Projetos no Postgres 15.8.1.079 ou mais novo — o que inclui praticamente todo projeto criado recentemente — usam backups físicos, que não podem ser baixados. Ativar o PITR faz o mesmo e ainda substitui os backups diários por completo. O conselho da documentação oficial para os dois casos: faça um backup lógico manual com a CLI ou com pg_dump. Que é o resto desta página.

A resposta em um comando: pg_dump para .sql

Copie a string de conexão do Session pooler no botão Connect no topo do painel e preencha a senha do banco. Não a Direct connection — ela usa IPv6, a menos que o projeto tenha o add-on pago de IPv4, e morre com erro de rede na maioria das redes domésticas e de CI.

export DB_URL="postgresql://postgres.<project-ref>:<senha>@aws-0-<regiao>.pooler.supabase.com:5432/postgres"

pg_dump "$DB_URL" \
  --format=plain \
  --schema=public \
  --no-owner --no-privileges \
  --file="backup-$(date +%F).sql"

Três flags fazem o trabalho pesado aqui:

• --format=plain escreve SQL legível — instruções CREATE TABLE seguidas de blocos COPY com suas linhas. Dá para abrir, fazer grep, comparar e reproduzir com o psql comum.
• --schema=public captura o schema da sua aplicação. Os schemas gerenciados pelo Supabase — auth (seus usuários), storage (metadados de arquivos) — ficam de fora; despejá-los sem ser superusuário é restrito de qualquer forma. Saiba o que o arquivo não contém antes de precisar dele.
• --no-owner --no-privileges mantém o arquivo portátil: sem eles o dump fixa roles e grants específicos do Supabase, e reproduzi-lo num Postgres local afoga em erros de ownership.

Uma verificação de versão antes de confiar na saída: pg_dump --version precisa ser pelo menos a versão major do seu servidor (projetos Supabase rodam PG 15 ou 17 — select version(); no editor SQL mostra qual). Um cliente mais antigo se recusa a despejar um servidor mais novo.

A armadilha do supabase db dump: só schema, sem linhas

O conselho da documentação oficial para o plano gratuito cita o supabase db dump, então muita gente começa por ele. Ele produz SQL limpo — e a saída padrão não contém dados. Só definições de schema. Se você bate o olho no arquivo, vê seus CREATE TABLE e guarda como backup, você fez backup de um banco vazio. Suas linhas precisam de uma segunda execução com --data-only:

supabase db dump --db-url "$DB_URL" -f schema.sql
supabase db dump --db-url "$DB_URL" --data-only -f data.sql

(O valor de --db-url precisa estar com percent-encoding — uma senha com @ ou # quebra a URL. Dentro de um repositório vinculado com supabase link, passe --linked no lugar.) Restaurar significa reproduzir schema.sql primeiro e depois data.sql. Se você guardar só um comando desta página, guarde o do pg_dump: um arquivo, schema e dados juntos.

.sql ou .dump — escolha pelo que vai fazer com ele

O .sql puro é a escolha certa quando um humano vai olhar o arquivo: exportações avulsas, mover dados entre ambientes, conferir como uma tabela estava na terça passada. (Quer mover um projeto inteiro, e não só obter um arquivo? O guia de exportação (em inglês) cobre exportações só de schema, só de dados e o caminho de clonagem.) Para um backup recorrente, o formato custom (--format=custom, por convenção .dump) é o padrão melhor: é comprimido, consegue restaurar uma única tabela em vez de tudo, e as decisões de ownership vão para a hora da restauração, onde pertencem. O guia de opções de backup usa o formato custom exatamente por isso. Os dois não são rivais — um backup agendado em formato custom mais uma exportação .sql ocasional quando você precisa olhar os dados é uma configuração normal.

Restaurando o arquivo .sql

psql "$TARGET_DB_URL" -f backup-2026-09-07.sql

Aponte para um banco vazio — um projeto Supabase novo ou um Postgres local. E leia a saída, não o código de saída: o psql continua depois de erros e retorna 0 mesmo assim. Uma linha de ruído é esperada se o destino já tem um schema public (schema "public" already exists — inofensivo); erros citando as suas próprias tabelas são reais e significam que a restauração ficou incompleta. Restaurar especificamente dentro do Supabase, com todas as pegadinhas, tem um guia próprio (em inglês).

“Download automático”: agende em vez disso

Se o que trouxe você até aqui foi querer que o download aconteça toda semana sem você, isso é trabalho de agendador. O guia de GitHub Actions (em inglês) monta um workflow semanal gratuito que despeja seu banco em um bucket seu; o serviço hospedado faz o mesmo em horário fixo e depois testa a restauração, porque um arquivo que ninguém nunca restaurou é uma esperança, não um backup — veja como rodar esse teste você mesmo.

Perguntas frequentes