Complete Supabase backup and migration tool. https://www.smoonb.com/#price
npm install smoonbpg_dumpall + SQL separados, idêntico ao Dashboard)
supabase migration fetch)
bash
npm install smoonb
`
Usar com npx:
`bash
npx smoonb --help
`
Não instalar globalmente (será bloqueado):
`bash
npm install -g smoonb
`
$3
Para atualizar o smoonb para a versão mais recente disponível, execute no projeto atual:
`bash
npm install smoonb@latest
`
⚠️ IMPORTANTE: O smoonb deve ser instalado localmente no projeto. Não é permitido usar sem instalar (ex.: npx smoonb@latest).
💡 Por que apenas local?
- 🔒 Segurança: Evita conflitos de versão
- 📦 Isolamento: Cada projeto usa sua versão
- 🔄 Atualizações: Controle granular por projeto
- 🛡️ Estabilidade: Evita quebras em outros projetos
📋 Pré-requisitos
$3
Instale pelo Docker Desktop (Windows/macOS) ou Docker Engine (Linux). Depois verifique se está rodando:
`bash
docker --version
docker ps
`
⚠️ IMPORTANTE: O Docker é necessário para:
- Backup da database via pg_dumpall (compatível com Dashboard do Supabase)
- Compressão de arquivos .backup.gz
- Restauração de backups .backup e .backup.gz
$3
`bash
npm install -g supabase
`
Recomendamos Supabase CLI v2.72 ou mais recente para novos recursos e correções. Para atualizar: Atualizando o Supabase CLI.
$3
É necessário obter um token de acesso pessoal do Supabase para usar a Management API:
1. Acesse: https://supabase.com/dashboard/account/tokens
2. Clique em "Generate new token"
3. Copie o token (formato: sbp_...)
4. Adicione ao .env.local como SUPABASE_ACCESS_TOKEN
$3
O smoonb exige uma licença válida para executar backup e restore:
1. Obtenha sua licença no app desktop em https://www.smoonb.com
2. Defina no ambiente ou no .env.local: SMOONB_LICENSE_KEY=[sua-chave-de-licença]
3. A licença é validada no início de cada execução (step 00); não há cache. Se a validação falhar (rede/servidor), o CLI aborta. A licença não aparece no wizard de mapeamento de variáveis (já foi validada antes).
⚙️ Configuração
$3
O smoonb agora usa .env.local para configuração, seguindo o padrão da indústria. Isso torna o processo mais simples e integrado ao seu fluxo de trabalho.
#### 1. Criar ou editar .env.local na raiz do projeto
`bash
touch .env.local
`
#### 2. Adicionar as variáveis de ambiente necessárias
`env
SMOONB_LICENSE_KEY=[sua-chave-de-licença]
NEXT_PUBLIC_SUPABASE_URL=[sua-supabase-url]
NEXT_PUBLIC_SUPABASE_ANON_KEY=[sua-anon-key]
SUPABASE_SERVICE_ROLE_KEY=[sua-service-role]
SUPABASE_DB_URL=postgresql://postgres:[sua-database-password]@db.[seu-project-id].supabase.co:5432/postgres
SUPABASE_PROJECT_ID=[seu-project-id]
SUPABASE_ACCESS_TOKEN=[seu-access-token]
SUPABASE_POSTGRES_MAJOR=17
SMOONB_TELEMETRY_ENABLED=true
SMOONB_OUTPUT_DIR=./backups
`
Obrigatórias: SMOONB_LICENSE_KEY (app desktop em smoonb.com), SUPABASE_POSTGRES_MAJOR (ex.: 17; veja no Dashboard → Project Settings → Infrastructure → Service Versions). Opcionais: SMOONB_TELEMETRY_ENABLED, SMOONB_OUTPUT_DIR (padrão ./backups).
#### 3. Mapeamento Interativo
Ao executar backup ou restore pela primeira vez, o smoonb irá:
1. Ler seu .env.local atual
2. Identificar as chaves que você já tem
3. Perguntar interativamente quais chaves correspondem às esperadas (se os nomes forem diferentes)
4. Adicionar chaves faltantes se necessário
5. Criar backup automático do .env.local antes de qualquer alteração
6. Salvar mapeamento para futuras execuções
Exemplo de mapeamento:
`
🔧 Mapeando variável: NEXT_PUBLIC_SUPABASE_URL
Valor atual: https://abc123.supabase.co
Este é o valor correto do projeto alvo? (S/n): S
`
🌐 Internacionalização (i18n)
O smoonb suporta múltiplos idiomas automaticamente. Atualmente, os idiomas suportados são:
- Inglês (en) - Idioma padrão
- Português do Brasil (pt-BR) - Suporte completo
$3
O idioma é detectado automaticamente na seguinte ordem de precedência:
1. Variável de ambiente SMOONB_LANG (no .env.local ou no ambiente)
2. Locale do sistema (LANG, LC_ALL, LC_MESSAGES). Exemplo: LANG=pt_BR.UTF-8 → pt-BR
3. Fallback para inglês (en) se nenhum dos anteriores for detectado
$3
- en ou en-US → Inglês
- pt-BR, pt_BR ou pt → Português do Brasil
$3
- Saídas "máquina" (ex.: --json se implementado) não são traduzidas; campos e chaves permanecem em inglês
- Se uma chave de tradução estiver ausente em um idioma, o sistema faz fallback automático para inglês
- O idioma é detectado uma vez no início da execução e aplicado a todas as mensagens do CLI
🎯 Uso
$3
`bash
npx smoonb backup
`
Fluxo interativo do backup:
1. Termo de uso - Exibe e solicita aceitação dos termos
2. Validação de licença - Valida SMOONB_LICENSE_KEY (env ou prompt); sem cache; aborta se a validação falhar
3. Validação Docker - Verifica se o Docker está rodando
4. Consentimento - Pede permissão para ler/escrever .env.local
5. Mapeamento de variáveis - Mapeia suas variáveis de ambiente (primeira vez; a licença não entra no wizard—já validada)
6. Backup do .env.local - Cria backup automático antes de alterações
7. Seleção de componentes - Pergunta quais componentes incluir:
- ⚡ Edge Functions (explicação sobre reset de link e download)
- 📦 Storage (explicação sobre backup completo: download de arquivos + ZIP no padrão do Dashboard)
- 🔐 Auth Settings (explicação sobre configurações)
- 🔄 Realtime Settings (explicação sobre captura interativa de 7 parâmetros)
- 🗑️ Opções de limpeza (functions, .temp, migrations após backup)
8. Resumo de configurações - Mostra tudo que será feito
9. Confirmação final - Confirma antes de iniciar
10. Execução das etapas:
- 📊 1/10 - Backup Database via pg_dumpall (Docker)
- 📊 2/10 - Backup Database SQL separado (schema, dados, roles)
- 🔧 3/10 - Backup Database Extensions and Settings
- 🔐 4/10 - Backup Auth Settings (se selecionado)
- 🔄 5/10 - Backup Realtime Settings (se selecionado) - 7 parâmetros capturados interativamente
- 📦 6/10 - Backup Storage (se selecionado) - Download completo de arquivos + ZIP no padrão do Dashboard
- 👥 7/10 - Backup Custom Roles
- ⚡ 8/10 - Backup Edge Functions (se selecionado)
- 📁 9/10 - Backup Supabase .temp (se selecionado)
- 📋 10/10 - Backup Migrations (se selecionado)
Resultado: Uma pasta backups/backup-YYYY-MM-DD-HH-MM-SS/ contendo, por exemplo:
`
backups/backup-2025-10-31-09-37-54/
├── backup-manifest.json
├── db_cluster-31-10-2025@09-38-57.backup.gz
├── schema.sql
├── data.sql
├── roles.sql
├── database-settings-*.json
├── auth-settings.json
├── realtime-settings.json
├── storage/
│ └── [bucket-name].json
├── [project-id].storage.zip
├── storage_temp/
│ └── [project-id]/
│ └── [bucket-name]/
├── edge-functions/
│ └── [nome-da-function]/
├── supabase-temp/
├── migrations/
└── env/
├── .env.local
└── env-map.json
`
$3
Restaurar backup existente:
`bash
npx smoonb restore
`
Fluxo interativo do restore:
1. Termo de uso - Exibe e solicita aceitação dos termos
2. Validação de licença - Valida SMOONB_LICENSE_KEY (env ou prompt); aborta se a validação falhar
3. Validação Docker - Verifica se o Docker está rodando
4. Consentimento - Pede permissão para ler/escrever .env.local
5. Mapeamento de variáveis - Mapeia variáveis para o projeto de destino (inclui SUPABASE_POSTGRES_MAJOR)
6. Backup do .env.local - Cria backup automático
7. Seleção de backup - Lista e permite escolher qual backup restaurar
8. Seleção de componentes - Pergunta quais componentes restaurar:
- 📊 Database (sempre disponível)
- ⚡ Edge Functions (se disponível no backup)
- 🔐 Auth Settings (se disponível no backup)
- 📦 Storage (se disponível no backup)
- 🔧 Database Extensions and Settings (se disponível no backup)
- 🔄 Realtime Settings (se disponível no backup)
9. Resumo detalhado - Mostra backup selecionado, projeto destino e componentes
10. Confirmação final - Confirma antes de iniciar
11. Aviso - Explica que erros durante a restauração são esperados; link para documentação de restore do Dashboard Supabase; aguardar o fim do processo e testar o resultado antes de aceitar para prosseguir
12. Execução da restauração:
- 📊 Database - Restaura via psql (suporta .backup.gz e .backup)
- ⚡ Edge Functions - Copia e faz deploy no projeto destino
- 🔐 Auth Settings - Exibe configurações para aplicação manual
- 📦 Storage - Restaura buckets e arquivos do ZIP (se disponível) ou exibe informações para migração manual
- 🔧 Database Settings - Restaura extensões e configurações via SQL
- 🔄 Realtime Settings - Exibe configurações para aplicação manual
Formato de arquivos suportados:
- ✅ .backup.gz (compactado) - Descompacta automaticamente antes de restaurar
- ✅ .backup (descompactado) - Restaura diretamente
$3
Se você baixou um backup diretamente do Dashboard do Supabase (formato .backup.gz), você pode importá-lo para o formato esperado pelo smoonb. O comando também suporta importar arquivos de storage (.storage.zip) opcionalmente.
Importar apenas database:
`bash
npx smoonb import --file "caminho/completo/para/db_cluster-04-03-2024@14-16-59.backup.gz"
`
Importar database e storage juntos:
`bash
npx smoonb import --file "backup.backup.gz" --storage "meu-projeto.storage.zip"
`
O que o comando faz:
1. Lê o arquivo .backup.gz do Dashboard (obrigatório)
2. Se fornecido, lê o arquivo .storage.zip do Dashboard (opcional)
3. Extrai informações do nome do arquivo de backup (data e hora)
4. Cria uma pasta de backup no formato esperado (backup-YYYY-MM-DD-HH-MM-SS)
5. Copia o arquivo de backup para a pasta criada
6. Se fornecido, copia o arquivo de storage para a mesma pasta
7. Deixa o backup pronto para ser encontrado pelo comando restore
Exemplo completo - Apenas database (usando import + restore):
1. Baixe o backup do Dashboard do Supabase (ex.: db_cluster-04-03-2024@14-16-59.backup.gz).
2. Importe o arquivo e depois restaure:
`bash
npx smoonb import --file "C:\Downloads\db_cluster-04-03-2024@14-16-59.backup.gz"
npx smoonb restore
`
O backup importado aparecerá na lista de backups disponíveis.
Exemplo completo - Database e Storage (usando import + restore):
1. Baixe backup e storage do Dashboard do Supabase (ex.: db_cluster-04-03-2024@14-16-59.backup.gz e meu-projeto.storage.zip).
2. Importe ambos os arquivos e depois restaure:
`bash
npx smoonb import --file "C:\Downloads\db_cluster-04-03-2024@14-16-59.backup.gz" --storage "C:\Downloads\meu-projeto.storage.zip"
npx smoonb restore
`
O backup importado aparecerá na lista de backups disponíveis.
Importante:
- O arquivo de backup é obrigatório e deve estar no formato do Dashboard: db_cluster-DD-MM-YYYY@HH-MM-SS.backup.gz
- O arquivo de storage é opcional e deve estar no formato: *.storage.zip
- O storage depende de um backup, mas o backup não depende do storage
- Ambos os arquivos serão copiados para a mesma pasta de backup
- O caminho pode ser absoluto ou relativo
- O comando criará a estrutura de pastas necessária automaticamente
Após executar import, execute restore para escolher o backup importado na lista e restaurar.
🔧 Comandos Disponíveis
| Comando | Descrição |
|---------|-----------|
| npx smoonb backup | Backup completo interativo usando Docker |
| npx smoonb restore | Restauração interativa usando psql (Docker) |
| npx smoonb import --file | Importar arquivo .backup.gz e opcionalmente .storage.zip do Dashboard do Supabase |
🏗️ Arquitetura Técnica
$3
O código foi refatorado para uma arquitetura modular com etapas independentes:
#### Backup (src/commands/backup/)
`
backup/
├── index.js
├── utils.js
└── steps/
├── 00-license.js
├── 01-docker-validation.js
├── 02-database.js
├── 03-database-separated.js
├── 04-database-settings.js
├── 05-auth-settings.js
├── 06-realtime-settings.js
├── 07-storage.js
├── 08-custom-roles.js
├── 09-edge-functions.js
├── 10-supabase-temp.js
└── 11-migrations.js
`
#### Restore (src/commands/restore/)
A validação de licença (mesmo step do backup, 00-license.js em backup/steps) roda no início. Em seguida:
`
restore/
├── index.js
├── utils.js
└── steps/
├── 00-backup-selection.js
├── 01-components-selection.js
├── 02-confirmation.js
├── 03-database.js
├── 04-edge-functions.js
├── 05-auth-settings.js
├── 06-storage.js
├── 07-database-settings.js
└── 08-realtime-settings.js
`
$3
#### Database
- Backup Principal: pg_dumpall via Docker (idêntico ao Dashboard)
- Arquivo: db_cluster-XX-XX-XXXX@XX-XX-XX.backup.gz
- Compatível com restauração via Dashboard do Supabase
- Backup Separado: SQL em arquivos distintos via Supabase CLI
- schema.sql - Estrutura das tabelas
- data.sql - Dados (comandos COPY)
- roles.sql - Roles e permissões
#### Edge Functions
- Download Automático: Via Supabase CLI supabase functions download
- Reset de Link: Garante link limpo com o projeto antes do download
- Backup Completo: Código completo de cada function
#### Migrations
- Download Automático: Via supabase migration fetch
- Reset de Link: Garante link limpo com o projeto
- Backup Completo: Todas as migrations do servidor
#### Storage
- Backup Completo: Download de todos os arquivos de todos os buckets
- Estrutura Temporária: Cria storage_temp/project-id/bucket-name/arquivos... dentro do backupDir
- ZIP no Padrão Dashboard: Cria {project-id}.storage.zip com estrutura project-id/bucket-name/arquivos...
- Compatível com Restore: O ZIP criado é compatível com o processo de restore (mesmo formato do Dashboard)
- Pergunta Interativa: Após criar o ZIP, pergunta se deseja limpar a estrutura temporária
- Fallback: Se não houver credenciais do Supabase, faz backup apenas de metadados
- Management API: Usa Personal Access Token para listar buckets e objetos
- Supabase Client: Usa Service Role Key para download de arquivos
#### Auth, Realtime
- Management API: Usa Personal Access Token
- JSON Export: Configurações exportadas como JSON
- Realtime Settings: Captura interativa de 7 parâmetros:
1. Habilitar serviço Realtime
2. Permitir acesso público
3. Tamanho do pool de conexões do database
4. Máximo de clientes simultâneos
5. Máximo de eventos por segundo
6. Máximo de eventos de presença por segundo
7. Tamanho máximo do payload em KB
- Manual para alguns: Alguns settings precisam ser aplicados manualmente por segurança
$3
#### Database
- Suporte a Formatos:
- .backup.gz - Descompacta automaticamente via Docker
- .backup - Restaura diretamente via psql (Docker)
- Restauração Limpa: Pode sobrescrever dados existentes (com confirmação)
#### Edge Functions
- Deploy Limpo: Limpa supabase/functions antes do deploy
- Reset de Link: Garante link correto com projeto destino
- Deploy Automático: Usa supabase functions deploy
#### Outros Componentes
- Database Settings: Restaura via SQL
- Storage: Restaura buckets e arquivos do ZIP (se disponível) ou exibe informações para configuração manual
- Auth/Realtime: Exibe informações para configuração manual no Dashboard
$3
- Windows/macOS/Linux: Detecção automática de binários
- Multiplataforma: Usa fs.promises.cp, path.join, Docker
- Docker para Tudo: Backup, restore e compressão via Docker (garante consistência)
📊 Fluxo Recomendado
1. Configurar .env.local (primeira vez) com as credenciais do projeto origem.
2. Backup do projeto origem:
`bash
npx smoonb backup
`
(Mapeia variáveis interativamente na primeira vez, seleciona componentes, executa backup completo.)
3. Criar novo projeto Supabase (via Dashboard ou Supabase CLI).
4. Editar .env.local com as credenciais do novo projeto (apontar variáveis para o projeto destino).
5. Restaurar backup (modo interativo):
`bash
npx smoonb restore
`
(Seleciona backup desejado, componentes a restaurar, executa restauração.)
6. Aplicar configurações manuais se necessário: Auth Settings (Dashboard → Authentication → Settings), Realtime (Dashboard → Database → Replication). O Storage é restaurado automaticamente do ZIP quando disponível.
🎨 Experiência do Usuário
$3
Todas as interações são em Português do Brasil:
- Perguntas claras e diretas
- Explicações antes de cada processo
- Resumos detalhados antes de confirmar
- Confirmações com (S/n) ou (s/N) em português
$3
- Detecção Automática: Se a chave já existe com o nome esperado, pula a seleção
- Opção de Adicionar: Permite adicionar novas chaves se não existirem
- Validação de Valores: Confirma valores antes de salvar
- Backup Automático: Sempre cria backup do .env.local antes de alterações
$3
- Validação Prévia: Verifica Docker antes de começar
- Explicações Contextuais: Explica cada processo antes de perguntar
- Resumo Final: Mostra tudo que será feito antes de executar
- Feedback Visual: Cores e ícones para melhor experiência
🐛 Solução de Problemas
$3
Verifique se o Docker está instalado e em execução:
`bash
docker --version
docker ps
`
Se não estiver, inicie o Docker Desktop (Windows/macOS) ou execute sudo systemctl start docker (Linux).
$3
`bash
npm install -g supabase
`
$3
1. Verificar se SUPABASE_ACCESS_TOKEN está no .env.local
2. Gerar novo token: https://supabase.com/dashboard/account/tokens
3. Atualizar .env.local com o novo token
$3
- Verificar senha na URL de conexão
- Usar string de conexão do Dashboard Supabase (Settings → Database)
- Testar conexão: psql "sua-database-url" -c "SELECT 1"
$3
O smoonb suporta automaticamente:
- ✅ .backup.gz - Descompacta via Docker antes de restaurar
- ✅ .backup - Restaura diretamente
Se houver problemas:
1. Verificar se Docker está rodando
2. Verificar permissões do arquivo
3. Verificar espaço em disco
$3
1. Verificar se SUPABASE_ACCESS_TOKEN está configurado
2. Verificar se o projeto está linkado: supabase link
3. Verificar se as functions existem no servidor
$3
1. Verificar se SUPABASE_ACCESS_TOKEN está configurado
2. Verificar se o projeto está linkado: supabase link
3. Verificar se há migrations no servidor
🔒 Segurança
- Backup Automático: Sempre cria backup do .env.local antes de alterações
- Mapeamento Local: Mapeamento de variáveis salvo apenas localmente
- Sem Dados Sensíveis: Nenhum dado sensível é enviado para fora do seu ambiente
- Docker Isolado: Operações de database via Docker (isolamento)
💼 Acesso e assinatura
O código do Supa Moonbase é disponibilizado sob licença MIT (ver LICENSE`). Para usar o smoonb é obrigatório ter licença ativa e assinatura válida, ou estar em período de trial. A validação da licença ocorre no início do backup e do restore; sem licença e assinatura válidas (ou trial), o CLI não executa essas operações.