Migrations e Versionamento de Banco (Supabase CLI)
Índice do Manual
No desenvolvimento de sistemas corporativos de alta demanda, a improvisação é o caminho mais rápido para a falência operacional. Um dos vícios mais destrutivos presentes em equipes técnicas e agentes de código é o chamado Cowboy Coding no banco de dados: entrar no painel visual da ferramenta e adicionar uma coluna na mão.
Se uma coluna for alterada manualmente na produção, e o código do frontend que depende dela for revertido no Git (Rollback), o sistema entra em colapso catastrófico. O código e o banco perdem a sincronia.
Mas existe uma regra inegociável de infraestrutura: o painel do Supabase em produção é estritamente de leitura (Read-Only). Nunca, sob nenhuma circunstância, altera-se o esquema do banco de dados clicando em botões ou rodando ALTER TABLE diretamente no painel.
A única forma autorizada e profissional de moldar um banco de dados é através de Migrations geradas pelo Supabase CLI.
1. O Padrão Ouro: Supabase CLI e Migrations
Uma Migration (Migração) é um arquivo de texto contendo comandos SQL (ex: CREATE TABLE) que conta uma "história" sequencial das modificações do banco de dados.
Ao transformar o banco em arquivos de texto, você passa a ter controle de versão no Git. Se o projeto mudar de servidor, ou se outro programador precisar rodar o sistema, basta apertar um botão para que o banco seja recriado exatamente como estava, com precisão milimétrica.
O Fluxo Obrigatório de Trabalho
Toda nova tabela, função, Trigger ou alteração no RLS (Row Level Security) deve nascer no ambiente local, isolado da produção.
Passo 1: Iniciando o ambiente local O projeto deve possuir a infraestrutura do Supabase rodando localmente via Docker (conforme estabelecido no Setup Inicial).
# Inicializa a pasta supabase/ no projeto
supabase init
# Sobe os containers de banco local, painel e APIs
supabase start
Dúvida Arquitetural: Não entende como esse banco local funciona ou como conectá-lo ao Supabase real do seu cliente na nuvem? Leia o meu manual de Ambiente Local e Link de Produção antes de prosseguir.
Passo 2: Criando a Migration de forma Visual (A Abordagem Ágil)
Quando for necessário criar uma nova entidade (por exemplo, uma tabela de clientes), você não precisa perder tempo digitando SQL na mão e correndo risco de errar a sintaxe. Você usa a agilidade do painel local.
O Supabase CLI fornece um painel de controle (Studio) idêntico ao da nuvem que roda no seu navegador em http://localhost:54323.
- Você abre o painel local, cria a tabela
clientesclicando nos botões, configura as colunas e as regras visivelmente sem tocar em código. - Em seguida, você volta para o terminal e roda o comando mágico de verificação:
supabase db diff -f criar_tabela_clientes
O Supabase escaneia o seu banco local, detecta tudo o que você alterou visualmente, e escreve o código SQL da Migration automaticamente na pasta supabase/migrations/ para você!
(Nota: O arquivo gerado terá um nome prefixado por um carimbo de tempo, como 20260810143000_criar_tabela_clientes.sql. Esse Timestamp numérico existe para garantir que a Produção execute as criações na ordem cronológica exata.)
Passo 3: A Prova de Fogo Local (db reset)
A tabela que você acabou de criar já existe no seu painel porque você a desenhou visualmente. O último passo antes de mandar para a Homologação é aplicar a "Prova de Fogo" para garantir que o arquivo .sql gerado automaticamente no Passo 2 está perfeito.
O comando abaixo destrói o seu banco de dados local e o reconstrói do zero absoluto, aplicando todos os arquivos de Migrations na ordem:
supabase db reset
O Reset afeta a Nuvem (Staging/Produção)?
Não. Por padrão, o comando supabase db reset é uma operação estritamente local (apaga apenas o banco do Docker na sua máquina).
Se o seu banco de Staging na nuvem virar uma bagunça de testes e você quiser resetá-lo, você precisará forçar o comando no projeto vinculado: supabase db reset --linked. O Supabase possui uma trava de segurança e bloqueará este comando imediatamente se o seu terminal estiver vinculado a um projeto marcado como Produção.
Por que usar o db reset e não o migration up aqui? Não é perigoso apagar o banco?
Lembre-se do pilar desta arquitetura: o banco de dados Local é 100% descartável. Não deve existir nenhum dado real ou valioso na sua máquina (para isso existem arquivos de Seed que cospem dados falsos automaticamente).
Se você usasse o migration up neste exato cenário, o CLI não faria absolutamente nada. Por quê? Porque a tabela já existe no seu banco local (você a criou clicando nos botões no Passo 1!).
A única forma de provar matematicamente que o arquivo .sql gerado pelo Supabase é capaz de criar a tabela na Produção, é destruindo o seu banco local inteiro e obrigando o CLI a reconstruir a tabela lendo exclusivamente o código. Se a tabela não voltar, o código SQL gerado estava corrompido.
Se o comando rodar com sucesso e a tabela reaparecer no seu painel local, significa que a máquina conseguiu reconstruir sozinha aquilo que você desenhou. A sua infraestrutura está blindada e pronta para o Deploy!
2. CI/CD: A Implantação Automatizada
Quando a funcionalidade estiver pronta e testada, os arquivos de Migration são commitados no Git (GitHub, GitLab).
Esta arquitetura exige o uso do GitHub Actions (ou similar) conectado ao Supabase. No exato instante em que o código for mesclado (merged) para a ramificação principal (main ou production), a esteira de automação (CI/CD) lerá os novos arquivos de Migration e os aplicará no servidor de produção de forma silenciosa e controlada.
3. Migrations de Dados (Injetando Metadados em Produção)
Uma Migration de Dados é exatamente o mesmo arquivo .sql de uma Migration estrutural, gerada no mesmo fluxo cronológico. A única diferença é que, em vez de comandos CREATE TABLE, você escreve comandos INSERT INTO.
Existem duas formas de implementar isso no dia a dia:
Abordagem A: Junto com o Esquema (Na criação da Tabela)
Se você acabou de desenhar uma tabela que precisa nascer populada (ex: planos de assinatura), você gera a migration estrutural e adiciona os INSERTs manualmente no final do mesmo arquivo:
-- Arquivo: 20260810143000_criar_tabela_planos.sql
CREATE TABLE public.planos ( id text primary key, preco numeric );
-- Você adiciona isso embaixo:
INSERT INTO public.planos (id, preco) VALUES ('gratis', 0), ('pro', 49.90);
Abordagem B: Em um Arquivo Dedicado (Evolução Contínua)
Se a tabela já existe há meses e você precisa inserir uma nova categoria obrigatória hoje, crie uma migration vazia (supabase migration new insere_nova_categoria) e escreve o INSERT dentro dela.
A Regra de Ouro: Prós e Contras
A Vantagem (Sincronia Absoluta): Quando você sobe um código novo pro Vercel que depende do plano "Enterprise", a Migration garante que o banco terá esse dado no exato milissegundo em que o código for ao ar. Se o banco cair e você restaurar um backup antigo, as Migrations rodam sozinhas e recuperam esses dados vitais do sistema.
O Perigo (Imutabilidade): Migrations são cravadas na pedra. Se o preço do plano "Pro" subir para 59.90 na semana que vem, você não pode editar a migration antiga. Terá que criar uma nova migration escrevendo um UPDATE. Se você usar migrations para dados dinâmicos, sua pasta virará um lixo ilegível cheio de UPDATEs.
Use Migrations de Dados APENAS para Metadados do Sistema (permissões, status fixos, planos do SaaS, lista de estados do Brasil). Qualquer dado dinâmico, que mude frequentemente (produtos de e-commerce, preços variáveis, posts de blog) deve ser alterado através de um painel de Admin do seu próprio sistema (Frontend), e NUNCA via Migrations.
Precisa popular dados falsos (fakes) só para testar as telas localmente? Então você NÃO deve usar Migrations. O Supabase possui uma ferramenta exclusiva para popular dados descartáveis sempre que o banco local é resetado. Leia o manual: Seeds: Como Fazer o Banco de Dados Nascer Vivo.
4. O Veredito Arquitetural
A adoção compulsória do Supabase CLI para gerenciamento do esquema é o que separa protótipos instáveis de sistemas SaaS empresariais.
Ao obrigar o uso de Migrations, você impede que agentes autônomos e desenvolvedores não apliquem modificações isoladas que quebram o código. O banco de dados torna-se versionado, rastreável e auditável, reduzindo muito o risco operacional de perder tabelas.
O Próximo Passo: E a Lógica de Negócios Oculta?
Agora você já sabe como proteger as suas tabelas e versionar a estrutura do banco através do Supabase CLI.
Mas uma base de dados vazia não ajuda a testar o sistema. Agora que você sabe criar as tabelas de forma segura, o próximo passo lógico é aprender a popular o banco com dados de teste iniciais (categorias, planos, admin) automaticamente.
Para isso, siga para o próximo manual: Seeds: Como Fazer o Banco de Dados Nascer Vivo.
Precisa de apoio técnico para a sua empresa?
Se a sua operação busca especialistas para modernização de sistemas legados ou desenvolvimento de sistemas sob medida com arquitetura de alta performance (Next.js e Supabase), conheça meus serviços de tecnologia ou fale diretamente comigo pelo WhatsApp.