Supabase CLI: instale e aprenda os comandos que você vai usar

Supabase CLI

Supabase CLI: instalação, ambiente local e guia de comandos | We.Inc

Instale a Supabase CLI, rode um stack local, vincule um projeto, envie migrations, gere tipos e publique Edge Functions, com uma tabela pesquisável dos principais comandos.

A Supabase CLI é um programa de linha de comando que roda uma cópia do Supabase no seu próprio computador e leva as mudanças do banco de dados para o seu projeto em produção. Instale com Homebrew, Scoop ou npm, rode supabase init e supabase start e depois supabase link e supabase db push para enviar as migrations ao projeto hospedado.

Formas de instalar a Supabase CLI

Sistema
Comando

macOS ou Linux (Homebrew)
brew install supabase/tap/supabase

Windows (Scoop)
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git, depois scoop install supabase

Qualquer projeto (npm)
npm install supabase --save-dev, depois rode npx supabase

Pacotes Linux
.apk, .deb ou .rpm na página de releases

Digite parte de um comando ou uma palavra como types, ou escolha um grupo, para filtrar a tabela abaixo. Cada linha é um comando da referência oficial da CLI, com uma nota curta sobre quando o dono de um site recorre a ele.

Instale a CLI e um runtime de containers como o Docker Desktop, porque o stack local roda em containers.
Rode supabase init na pasta do seu projeto para criar a pasta supabase com o arquivo de configuração.
Rode supabase start para subir o stack local e depois abra o Studio, o painel do banco de dados, em http://localhost:54323.
Rode supabase login e supabase link --project-ref com o ID de referência do seu projeto para conectar o projeto hospedado.
Escreva as mudanças como migrations, teste localmente e depois rode supabase db push para aplicá-las ao banco hospedado.

A instalação via npm adiciona a CLI a um único projeto, não como comando global, então use npx antes dos comandos.
Rodar via npx ou npm exige Node.js 20 ou mais recente, segundo o guia de primeiros passos.
O Supabase recomenda pelo menos 7 GB de RAM para iniciar todos os serviços locais. Use -x para excluir os serviços de que não precisa.
Experimente primeiro supabase db push --dry-run para ver quais migrations rodariam sem mudar nada.
Gere de novo os tipos TypeScript depois de cada mudança de schema para que o seu código combine com o banco.

Perguntas frequentes

Preciso do Docker para a Supabase CLI?

Para o stack local, sim, ou de outro runtime de containers. O guia cita OrbStack, Rancher Desktop, Podman e colima como alternativas e menciona um runtime nativo experimental para Linux e Macs com Apple silicon.

Posso instalar a Supabase CLI globalmente com npm?

O guia oficial diz que o pacote npm adiciona a CLI a um único projeto, e não como comando global. Use Homebrew ou Scoop para uma instalação em todo o sistema.

Qual a diferença entre db push e db pull?

db push envia os seus arquivos de migration locais para um banco de dados. db pull lê o schema de um banco remoto e o grava em um novo arquivo de migration, o que é útil quando as mudanças foram feitas no painel.

Como gero tipos TypeScript?

Rode supabase gen types --lang typescript com --local para o banco local ou --linked para o hospedado, e redirecione a saída para um arquivo no seu projeto.

Como publico uma Edge Function?

Crie uma com supabase functions new e um nome, depois rode supabase functions deploy com esse nome. Defina os secrets dela com supabase secrets set NAME=VALUE.

Por que usar migrations em vez de clicar no painel

Uma migration é um arquivo SQL numerado que registra uma mudança no seu banco de dados. Manter as mudanças em arquivos permite testá-las localmente, revisá-las e reaplicá-las em um projeto novo na mesma ordem.
Edições pelo painel continuam acontecendo. Quando acontecem, supabase db diff ou supabase db pull transforma a diferença em uma migration para que os seus arquivos fiquem em dia.

Uma primeira sessão do início ao fim

Rode estes comandos na pasta do seu projeto. Troque o ID de referência pelo que aparece nas configurações do seu projeto.

Do stack local ao projeto hospedado

A ordem importa: crie a migration, confira localmente com um reset e depois envie.

Buscador de comandos

Pesquisar comandos

push, types, functions...

Grupo

Todos

Configuração

Stack local

Banco de dados

Tipos

Edge Functions

Comando

O que faz

{n} comandos exibidos

Nenhum comando corresponde. Limpe a busca para ver todos.

Conecta a CLI à sua conta Supabase pelo navegador, ou com --token.

Cria a pasta supabase e o arquivo de configuração no projeto atual.

Sobe o stack local em containers e mostra as URLs e chaves locais.

Desliga o stack local. Adicione --no-backup para descartar os dados locais.

Mostra de novo as URLs e chaves locais. Adicione -o env para exibi-las como variáveis de ambiente.

Cria um arquivo SQL vazio, com data e hora, em supabase/migrations para a sua mudança.

Recria o banco local a partir das migrations e roda o arquivo de seed.

Aplica as novas migrations locais ao banco vinculado. Experimente --dry-run primeiro.

Grava o schema remoto em um novo arquivo de migration. Precisa de um daemon Docker rodando.

Compara schemas e salva a diferença como uma migration com -f.

Gera tipos TypeScript para as suas tabelas. Use --local para o banco local.

Cria uma nova pasta de Edge Function com código inicial.

Roda as suas Edge Functions localmente enquanto você testa.

Envia uma Edge Function para o projeto hospedado.

Guarda um secret, como uma chave de pagamento, para as suas Edge Functions hospedadas.