O Supabase vem ganhando espaço como uma das soluções mais práticas para quem precisa de um backend completo e fácil de usar. Com uma proposta parecida com o Firebase, mas baseada em tecnologias abertas como PostgreSQL, ele oferece banco de dados, autenticação, armazenamento e funções serverless num pacote bem integrado.
Apesar da interface web ser intuitiva, a melhor forma de usar o Supabase em projetos reais é via linha de comando, com a Supabase CLI. Isso porque ela permite que tudo fique versionado, testável localmente e replicável entre ambientes. Ou seja, menos chances de erro e mais controle sobre a evolução do projeto.
Neste artigo, explicamos por que você deve priorizar o uso da CLI, como começar e quais boas práticas adotar para manter seu projeto tecnológico organizado, seguro e fácil de manter – tanto em time quanto individualmente. Continue a leitura!
Por que usar a Supabase CLI?
Fazer alterações diretamente na interface web pode parecer mais rápido em um primeiro momento, mas torna difícil rastrear mudanças, compartilhar configurações ou garantir que o ambiente de produção esteja alinhado com o de desenvolvimento.
A Supabase CLI resolve esses problemas ao permitir que você:
- crie e aplique migrações de banco de dados via código;
- teste alterações localmente antes de levá-las para produção;
- mantenha arquivos de configuração e scripts versionados no repositório;
- sincronize o estado do banco com facilidade entre ambientes diferentes.
Essa abordagem facilita a manutenção do projeto no longo prazo, reduz riscos e melhora a colaboração entre desenvolvedores.
Começando com a Supabase CLI
Antes de tudo, é importante garantir que você tenha o Node.js e o npm instalados na sua máquina – eles são necessários para rodar a Supabase CLI via npx. Uma vez que tudo esteja devidamente instalado, o primeiro passo para usar a Supabase via linha de comando é instalar a CLI. Ela pode ser usada com npx, sem necessidade de instalação global:
npx supabase --helpEsse comando cria os arquivos iniciais do projeto, como o supabase/config.toml, que é essencial para manter a configuração do ambiente.
Você também pode instalar globalmente com npm (opcional):
npm install -g supabasePara inicializar um novo projeto:
npx supabase init A partir daí, você pode subir o ambiente local com:
npx supabase startIsso roda containers com banco de dados PostgreSQL, Studio, autenticação e outros serviços da stack Supabase.
Já para interromper, use:
npx supabase stop
Migrações versionadas e testes locais
Ao trabalhar com banco de dados, é fundamental que alterações estruturais – como criação de tabelas ou mudança de tipos de colunas – sejam registradas de forma clara e reaplicável. A CLI do Supabase facilita isso com migrações SQL que ficam salvas no repositório.
Para criar uma nova migração, basta rodar:
npx supabase migration new nome_da_migracaoVocê também pode aplicar alterações no banco local a partir das novas migrações, com o comando:
npx supabase db push --localTambém é possível aplicar alterações locais no banco de dados em produção com o comando npx supabase dbpush, ou resetar o estado do banco com npx supabase db reset. Isso é útil para testar tudo do zero antes de levar para produção.
Outro ponto importante: sempre sincronize seu banco local com o schema atual usando npx supabase db pull e mantenha o histórico de alterações organizado no versionamento. Com isso, é possível reverter erros e acompanhar a evolução do projeto com mais confiança.
Subindo alterações para produção com segurança
Depois de testar localmente, é hora de sincronizar seu projeto com o Supabase Cloud. Você pode linkar o projeto com:
npx supabase link --project-ref <project-ref>A partir disso, é possível aplicar as alterações diretamente no ambiente remoto com o comando:
npx supabase db push --linkedVale lembrar que, mesmo com essa facilidade, o ideal é sempre revisar bem as alterações antes de aplicá-las na produção. E, claro, manter backups atualizados.
Outras funcionalidades da CLI
Além de lidar com migrações e o ambiente local, a Supabase CLI também oferece comandos úteis para manutenção e backup do banco.
Um deles é o npx supabase db dump, usado para gerar um backup (dump) do banco de dados PostgreSQL de um projeto Supabase. Ele cria um arquivo .sql contendo toda a estrutura (schema) e, opcionalmente, os dados do banco atual – funcionando de forma semelhante ao que o pg_dump do PostgreSQL faz.
Essa é uma forma prática de versionar o estado do banco ou mover dados entre ambientes com mais controle e segurança.
Ao final, o Supabase local estará disponível em http://localhost:54323. É por essa porta que você acessa o banco de dados local para testes e desenvolvimento.
Boas práticas para usar o Supabase via CLI
Pra fechar, algumas recomendações que ajudam a manter seu projeto saudável:
- Priorize sempre a CLI no lugar da interface web;
- Versione todas as migrações e inclua o supabase/config.toml no repositório;
- Use arquivos .env para guardar chaves como SUPABASE_ANON_KEY e SERVICE_ROLE_KEY;
- Não versione o arquivo .env no git e coloque-o no .gitignore;
- Teste migrações localmente antes de aplicar em produção;
- Reinicie os containers (stop e start) sempre que fizer alterações relevantes na configuração.
Aprendizado contínuo é parte do código
Usar a Supabase CLI pode parecer um passo a mais no início, mas é um investimento que vale a pena. Ela ajuda a manter seu projeto organizado, seguro e fácil de escalar; tudo isso com uma experiência de desenvolvimento fluida e moderna.
Para continuar acompanhando conteúdos sobre ferramentas, práticas e processos que fortalecem o Desenvolvimento de Software, acesse o blog da BIX e fique por dentro das novidades!
