Supabase via CLI: boas práticas para desenvolver com mais controle e segurança

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 --help

Esse 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 supabase

Para inicializar um novo projeto:

npx supabase init

 A partir daí, você pode subir o ambiente local com:

npx supabase start

Isso 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_migracao

Você também pode aplicar alterações no banco local a partir das novas migrações, com o comando:

npx supabase db push --local

Também é possível aplicar alterações locais no banco de dados em produção com o comando npx supabase db push, 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 --linked

Vale 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!