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 restauram no lugar ou não restauram. 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 authe 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