O Ciclo de Vida do Código: Local, Staging e Produção
Índice do Manual
A separação estrita entre o ambiente de Desenvolvimento (Local) e o ambiente de Produção (Nuvem) é o que distingue o trabalho de especialistas da improvisação amadora.
Contudo, ao construir sistemas críticos B2B ou atuar como um engenheiro solo de alto nível, existir apenas "Local" e "Produção" não é suficiente. Inserir código novo diretamente na base de usuários reais é um risco inaceitável.
Neste artigo, estabelecemos a nossa arquitetura oficial de 3 Camadas (Local, Staging e Produção). Vamos dissecar como o Supabase CLI orquestra esse ciclo de vida e a regra de ouro do CI/CD que protege a produção contra desastres humanos.
Camada 1: O Sandbox Local (Docker)
Todo e qualquer desenvolvimento começa na sua máquina, totalmente isolado da internet. O Supabase é 100% Open Source, e a sua CLI consegue clonar toda a estrutura pesada (Postgres, GoTrue, PostgREST) para dentro do seu computador através do Docker.
Quando você roda supabase start em uma pasta vazia, o sistema constrói mini-servidores virtuais (Containers) na sua memória RAM. O terminal devolve uma mensagem semelhante a esta:
Started supabase local development setup.
Studio URL: http://127.0.0.1:54323
Ao abrir essa URL, você ganha um Sandbox Isolado. Nele, você cria migrations, altera tabelas e força erros catastróficos. Se você destruir o banco de dados inteiro, basta rodar supabase db reset e ele renasce das cinzas em segundos, baseado nos seus arquivos SQL. Zero impacto em usuários reais.
Camada 2: A Ponte para Staging (Homologação)
Uma vez que o código está funcionando perfeitamente no seu Sandbox Local, é hora de validá-lo na nuvem real. É aqui que entra o ambiente de Staging (Homologação).
O Staging é uma réplica idêntica da Produção na nuvem, mas usada exclusivamente para testes internos e aprovação do cliente.
Nós conectamos a nossa máquina local APENAS ao Staging.
Lembra do passo no nosso Setup Inicial onde você executou o seguinte comando?
supabase link --project-ref [ID-DO-STAGING]
O que aconteceu por debaixo dos panos?
- Ao usar o Reference ID de Staging, a CLI solicitou a senha deste banco.
- Uma vez autenticado, a pasta oculta
.supabasegravou a conexão. - A partir desse momento, o seu computador e a nuvem de homologação passaram a compartilhar um túnel seguro (e a produção permaneceu intocada).
O Envio (supabase db push)
Com a ponte estabelecida, o envio de código do seu Sandbox para a nuvem de Staging resume-se a rodar:
supabase db push
Nesta fração de segundo, a CLI lê os seus arquivos .sql locais e aplica as criações e alterações das tabelas diretamente no Supabase de Staging. Agora, você (e o cliente) podem testar a nova funcionalidade online.
Camada 3: O Abismo da Produção (CI/CD)
[!CAUTION] A Regra de Ouro Corporativa: A sua máquina local NUNCA deve realizar um
supabase linkno banco de dados de Produção.
Se a sua máquina estiver plugada na Produção, você pode rodar um db push acidental ou deletar uma tabela sem querer, destruindo a empresa do cliente.
No nosso padrão de arquitetura B2B, o deploy para a Produção final é um evento sagrado e imutável, feito exclusivamente via pipelines automatizadas de CI/CD (ex: GitHub Actions).
Como a mágica acontece:
- Você testa tudo no Staging (Camada 2).
- Uma vez validado, você faz o
git commitegit pushdo seu código (incluindo as pastas de migrations) para a branchmainno GitHub. - O GitHub detecta o código novo e os robôs da nuvem assumem o controle.
- O robô aplica as migrations no banco de Produção do Supabase, rodando os scripts de forma impessoal e segura.
O seu computador nunca tocou na Produção. Se a sua máquina for formatada ou o seu token vazar, a arquitetura principal dos clientes continua 100% blindada.
4. Configurando o Robô (GitHub Actions)
Para que essa "mágica" aconteça na prática, você precisa fornecer as credenciais do banco de Produção para o GitHub, para que ele tenha permissão de aplicar as alterações quando você fizer um git push.
Passo 1: Segredos no GitHub Acesse o repositório do projeto no GitHub > Settings > Secrets and variables > Actions. Você precisa adicionar as seguintes chaves do Supabase de Produção:
SUPABASE_ACCESS_TOKEN(Seu token pessoal ou da organização)SUPABASE_DB_PASSWORD(A senha do banco de Produção)SUPABASE_PROJECT_ID(O Reference ID do projeto de Produção)
Passo 2: O Arquivo Workflow
Crie um arquivo no seu projeto local em .github/workflows/production.yml com o seguinte código. Ele ensina o GitHub a baixar a CLI do Supabase em um servidor Linux e rodar o db push de forma autônoma:
name: Deploy Supabase DB to Production
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
env:
SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }}
SUPABASE_PROJECT_ID: ${{ secrets.SUPABASE_PROJECT_ID }}
steps:
- uses: actions/checkout@v3
- name: Instalar Supabase CLI
uses: supabase/setup-cli@v1
with:
version: latest
- name: Executar DB Push
run: supabase db push
Uma vez que esse arquivo for commitado na sua base de código, o "robô" está oficialmente contratado. Toda nova funcionalidade que for aprovada e enviada para a branch main passará por esse fluxo seguro e impenetrável.
[!NOTE] E o deploy do Frontend (Vercel)? Diferente do banco de dados que exige esse arquivo YAML, a Vercel possui integração nativa com o GitHub. A partir do momento que você importa o repositório no painel da Vercel, ela automaticamente escuta os seus comandos
git push. A mesma ação que dispara o envio das tabelas pelo robô do Supabase acima, fará a Vercel compilar e subir o seu frontend atualizado simultaneamente, sem a necessidade de nenhuma linha extra de configuração.
5. Dúvida: Como funciona o Git Flow na prática?
Se você entendeu o conceito das 3 Camadas de Infraestrutura, mas não sabe quais os comandos exatos no terminal para transitar o código entre elas (como mudar de branch, abrir Pull Requests ou aprovar Merges no GitHub sem quebrar a Produção), leia o próximo capítulo: Manual Oficial de Git Flow e Go-Live. Nele, documentamos o passo a passo diário do desenvolvedor no terminal.