Neon Postgres Branching

Quando Usar

Use esta habilidade quando precisar escolher e criar o tipo de branch Neon certo para testes e desenvolvimento. Use quando os usuários perguntarem sobre branching no Neon, testes de migração com dados reais, ambientes de teste isolados, fluxos de trabalho de branch apenas com esquema para dados sensíveis, ou criação de branch via Neon CLI ou Neon MCP. Gatilhos...

O resultado desta habilidade deve ser um branch Neon criado (ou um próximo passo claro e acionável se a criação não puder prosseguir). Escolha o tipo de branch correto e, em seguida, execute a criação do branch via MCP ou CLI.

• Branch normal para testes de migração e consultas realistas com dados reais.
• Branch apenas com esquema (Beta) para fluxos de trabalho de dados sensíveis onde a estrutura é necessária sem copiar linhas.

Decisão do Tipo de Branch

Use esta regra de decisão primeiro:

1. Se o usuário quiser testar migrações complexas, desempenho ou comportamento contra dados semelhantes à produção, escolha um branch normal.
2. Se o usuário precisar evitar a cópia de dados sensíveis, escolha um branch apenas com esquema.

Se a solicitação for ambígua, faça uma pergunta esclarecedora: "Você precisa de dados realistas para testes, ou apenas da estrutura do esquema porque os dados são sensíveis?"

Seleção de Ferramenta: CLI ou MCP

Sempre suporte tanto o Neon CLI quanto o servidor Neon MCP. Prefira a ferramenta que o usuário já tem instalada e autenticada.

Link do MCP: https://neon.com/docs/ai/neon-mcp-server.md Link da CLI: https://neon.com/docs/reference/cli-quickstart

Ordem de Seleção

1. Verifique o MCP primeiro em ambientes com MCP ativado:
   • Se as ferramentas Neon MCP estiverem disponíveis e autenticadas (por exemplo, listar projetos funciona), use o MCP.
2. Se o MCP não estiver disponível ou não estiver autenticado, verifique a CLI:
   • Execute neon --version para confirmar se a CLI está instalada.
   • Execute neon projects list para confirmar a autenticação/contexto.
3. Se a CLI estiver faltando, direcione a instalação via quickstart.
4. Se a CLI estiver instalada, mas não autenticada, guie o usuário através de neon auth (ou autenticação por chave de API) e continue.
5. Se ambos os caminhos MCP e CLI forem malsucedidos, use a API REST do Neon:
   • https://neon.com/docs/guides/branching-neon-api.md

Fluxo de Branch do MCP

1. Escolha entre normal e apenas com esquema com base na sensibilidade dos dados e nos objetivos de teste de migração.
2. Use as ferramentas de branch (por exemplo, create_branch) para criar o branch.
3. Valide com ferramentas de leitura (por exemplo, describe_branch).
4. Para fluxos de trabalho de migração, prefira fluxos de migração baseados em branch antes de aplicar ao principal.

Criar um Branch Normal (Preferível para Testes de Migração com Dados Reais)

Use isso quando o usuário precisar de condições de teste realistas. Dados reais semelhantes à produção podem expor casos extremos que seus scripts de seed ou migração de dados perdem, o que ajuda a capturar problemas de migração antes de ir para produção.

Link: https://neon.com/docs/introduction/branching.md

Passos

1. Use o MCP se já estiver disponível/autenticado; caso contrário, verifique a CLI com neon --version.
2. Certifique-se de que o contexto do projeto esteja definido (neon set-context --project-id <your-project-id>) ou inclua --project-id nos comandos.
3. Crie o branch:

neon branches create \
  --name <branch-name> \
  --parent <parent-branch-id-or-name> \
  --expires-at 2026-12-15T18:02:16Z

4. Opcionalmente, obtenha uma string de conexão para o novo branch:

neon connection-string <branch-name>

Criar um Branch Apenas com Esquema (Beta, Dados Sensíveis)

Use isso quando os usuários não devem copiar linhas de produção para o branch de teste.

Link: https://neon.com/docs/guides/branching-schema-only.md

Passos

1. Use o MCP se já estiver disponível/autenticado; caso contrário, verifique a CLI com neon --version.
2. Crie o branch apenas com esquema:

neon branches create \
  --name <schema-only-branch-name> \
  --parent <parent-branch-id-or-name> \
  --schema-only \
  --expires-at 2026-12-15T18:02:16Z

Se houver vários projetos, inclua:

neon branches create \
  --name <schema-only-branch-name> \
  --parent <parent-branch-id-or-name> \
  --schema-only \
  --project-id <your-project-id> \
  --expires-at 2026-12-15T18:02:16Z

Orientação de Suporte Beta (Obrigatório)

O branching apenas com esquema está em Beta. Se os usuários relatarem comportamento inesperado, erros ou recursos ausentes:

1. Peça para eles compartilharem feedback no Console Neon:
   • https://console.neon.tech/app/projects?modal=feedback
2. Recomende abrir uma conversa de suporte no Discord do Neon:
   • https://discord.gg/92vNTzKDGp

Resetar do pai

Use isso quando um branch filho se desviou e o usuário deseja uma atualização limpa do esquema e dos dados mais recentes do branch pai.

…