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, nós passamos 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 nosso 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), nós não precisamos perder tempo digitando SQL na mão e correndo risco de errar a sintaxe. Nós usamos 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
[!NOTE] 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.
[!NOTE] Por que usar o
db resete não omigration upaqui? Não é perigoso apagar o banco? Lembre-se do pilar da nossa 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 usássemos omigration upneste 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.sqlgerado 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).
Nossa 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.
[!WARNING] 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.
[!TIP] 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, garantimos 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, eliminando o risco operacional de perder tabelas e garantindo a resiliência absoluta da operação do negócio.
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.