neondatabase/neon-postgres-branches

PRIMEIRO: Use a skill pai neon para uma visão geral do Neon, primeiros passos, melhores práticas de desenvolvimento com Neon e mais.

Se a skill neon não estiver instalada, busque-a em https://neon.com/docs/ai/skills/neon/SKILL.md ou instale-a com:

npx skills add neondatabase/agent-skills --skill neon

Ramificação (Branching) do Lakebase Postgres

Resultado esperado: uma ramificação Neon criada — ou um próximo passo claro e acionável se a criação não puder prosseguir. Escolha o tipo de ramificação correto e execute a criação com a CLI (ou MCP onde a CLI não for utilizável).

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

Decisão do Tipo de Ramificação

Use esta regra de decisão primeiro:

1. Se o usuário quiser testar migrações complexas, desempenho ou comportamento com dados semelhantes aos de produção, escolha uma ramificação normal.
2. Se o usuário precisar evitar a cópia de dados sensíveis, escolha uma ramificação somente 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

Suporte tanto a CLI do Neon quanto o servidor MCP do Neon, mas padrão para a CLI. Use MCP apenas quando a CLI não estiver disponível ou estiver bloqueada no seu ambiente, não puder ser autenticada, ou o usuário solicitar explicitamente o MCP.

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

Ordem de seleção

1. Verifique a CLI primeiro:
   • Execute neon --version para confirmar que a CLI está instalada.
   • Execute neon projects list para confirmar autenticação/contexto.
2. Se a CLI estiver ausente, instalação direta via quickstart.
3. Se a CLI estiver instalada mas não autenticada, guie o usuário através do neon auth (ou autenticação via chave de API) e prossiga.
4. Mude para MCP quando a CLI não puder ser usada — sem acesso à CLI no ambiente, execução bloqueada ou autenticação impossível — ou quando o usuário solicitar explicitamente o MCP. Confirme que as ferramentas MCP do Neon estão disponíveis e autenticadas (por exemplo, listar projetos funciona) e siga o fluxo de ramificação MCP abaixo.
5. Se nenhum dos caminhos for bem-sucedido, use a API REST do Neon:
   • https://neon.com/docs/guides/branching-neon-api.md

Fluxo de ramificação MCP

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

Criar uma Ramificação Normal (Preferida para Testes de Migração com Dados Reais)

Use quando o usuário precisar de condições de teste realistas. Dados reais semelhantes aos de produção podem expor casos limite que seus scripts de seed ou migração de dados podem perder, ajudando a detectar problemas de migração antes de ir para o ar.

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

Passos

1. Primeiro, defina o caminho da ferramenta (veja Ordem de seleção): verifique a CLI com neon --version e recorra ao MCP apenas se a CLI não for utilizável.

2. Certifique-se de que o contexto do projeto está definido (neon set-context --project-id <seu-project-id>) ou inclua --project-id nos comandos.

3. Crie a ramificação:

   neon branches create \
     --name <nome-da-ramificacao> \
     --parent <id-ou-nome-da-ramificacao-pai> \
     --expires-at 2026-12-15T18:02:16Z
   

4. Opcionalmente, obtenha uma string de conexão para a nova ramificação:

   neon connection-string <nome-da-ramificacao>
   

Criar uma Ramificação Somente Esquema (Beta, Dados Sensíveis)

Use quando os usuários não puderem copiar linhas de produção para a ramificação de teste.

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

Passos

1. Primeiro, defina o caminho da ferramenta (veja Ordem de seleção): verifique a CLI com neon --version e recorra ao MCP apenas se a CLI não for utilizável.

2. Crie a ramificação somente esquema:

   neon branches create \
     --name <nome-da-ramificacao-somente-esquema> \
     --parent <id-ou-nome-da-ramificacao-pai> \
     --schema-only \
     --expires-at 2026-12-15T18:02:16Z
   

   Se houver vários projetos, inclua --project-id:

   neon branches create \
     --name <nome-da-ramificacao-somente-esquema> \
     --parent <id-ou-nome-da-ramificacao-pai> \
     --schema-only \
     --project-id <seu-project-id> \
     --expires-at 2026-12-15T18:02:16Z
   

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

Ramificação somente esquema está em Beta. Se os usuários reportarem comportamento inesperado, erros ou funcionalidades ausentes:

1. Peça para 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 a Partir do Pai

Use quando uma ramificação filha se desviou e o usuário deseja uma atualização limpa a partir do esquema e dados mais recentes da ramificação pai.

Link: https://neon.com/docs/guides/reset-from-parent.md

O que faz

• Substitui completamente o esquema e os dados da ramificação filha pelo estado mais recente da ramificação pai.
• Não faz merge; alterações locais na ramificação filha são perdidas.
• Mantém os mesmos detalhes de conexão, mas as conexões ativas são brevemente interrompidas durante o reset.

Quando recomendar

• Ramificação de desenvolvimento ou staging está muito desatualizada em relação à produção.
• O usuário deseja iniciar um novo recurso a partir de um estado limpo alinhado ao pai.
• A equipe deseja atualizar o staging a partir da produção para obter bases de teste consistentes.

Restrições e bloqueadores

• Apenas ramificações filhas podem ser resetadas (ramificações raiz e ramificações raiz somente esquema não podem ser resetadas a partir do pai).
• Se a ramificação alvo tiver filhos, o reset é bloqueado até que essas ramificações filhas sejam removidas.
• Após uma ramificação pai ser restaurada a partir de um snapshot, o reset a partir do pai pode ficar indisponível por até 24 horas.
• Reset a partir do pai sempre usa o estado atual do pai; use Instant restore para necessidades de recuperação point-in-time.

Uso da CLI

neon branches reset <id|nome> --parent --preserve-under-name <nome-da-ramificacao-de-backup>

Se o contexto do projeto ainda não estiver definido, inclua o ID do projeto:

neon branches reset <id|nome> --parent --preserve-under-name <nome-da-ramificacao-de-backup> --project-id <id-do-projeto>

--preserve-under-name mantém o estado pré-reset como uma ramificação de backup para rollback, mas adiciona uma ramificação extra para limpar depois.

Configuração de contexto opcional para evitar repetir --project-id:

neon set-context --project-id <id-do-projeto>

Uso no Console e API

• Console: Abra a ramificação filha alvo e selecione Resetar a partir do pai em Ações.
• API: Use o endpoint de restauração para a ramificação e defina source_branch_id como o ID da ramificação pai.

Notas e Advertências

• Ramificações somente esquema são para clonagem apenas de estrutura e controles de dados sensíveis/compliance.
• Ramificações somente esquema são ramificações raiz independentes (sem ramificação pai e sem histórico compartilhado), portanto reset a partir do pai não se aplica.
• Para testes de migração que dependem de formas de linha, volumes e casos limite do mundo real, prefira ramificações normais.
• Limites de ramificações raiz e limites de armazenamento por ramificação podem limitar quantas ramificações somente esquema os usuários podem criar.
• Se o usuário estiver em dúvida, a recomendação padrão é:
  • Ramificação normal para validação de migração.
  • Ramificação somente esquema para restrições de compliance e privacidade.

Padrões de Fluxo de Trabalho Úteis

Se o usuário pedir recomendações de processo (não apenas um comando), sugira estes:

• Uma ramificação por PR: Crie uma ramificação quando o PR for aberto, delete quando for mesclado/fechado, mantenha os testes de migração isolados.
• Uma ramificação por execução de teste: Crie uma ramificação no início do pipeline, execute migrações/testes, delete no final para CI determinístico.
• Uma ramificação por desenvolvedor: Ambientes de desenvolvimento isolados com formato semelhante ao de produção; evite colisões de equipe em dados de teste compartilhados.
• Ramificação com consciência de PII: Se a produção tiver dados sensíveis, derive ramificações de dev/PR de uma ramificação anonimizada ou use ramificações somente esquema.
• Higiene de ciclo de vida efêmero: Defina a expiração da ramificação e automatize a limpeza para que ramificações antigas não acumulem custo de armazenamento/histórico evitável.

Prompt de atualização de ambiente pós-criação

Após a criação da ramificação, pergunte se o usuário deseja atualizar as credenciais do ambiente local para apontar para a nova ramificação.

• Pergunte: "Deseja que eu atualize seu DATABASE_URL no .env para esta nova string de conexão da ramificação?"
• Se sim, escreva a nova string de conexão da ramificação no arquivo/chave de env solicitado.
• Se não, deixe as credenciais inalteradas e compartilhe a string de conexão para uso manual.
• Nunca sobrescreva uma chave de env existente sem confirmação explícita.

Infraestrutura como Código do Neon (neon.ts)

Além de criar ramificações de forma imperativa (CLI / MCP / API acima), você pode programar qual configuração as novas ramificações receberão de forma declarativa no neon.ts — o arquivo de infraestrutura como código do Neon (veja a skill neon para a referência completa). A propriedade branch é uma função da ramificação sendo avaliada que retorna suas configurações, de modo que toda ramificação nascida do seu projeto receba um ciclo de vida e perfil de compute consistentes, sem flags por ramificação.

npm i @neon/config

// neon.ts
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  branch: (branch) => {
    if (branch.exists) return {}; // nunca reconciliar ramificações existentes
    if (branch.isDefault) return { protected: true };
    if (branch.name.startsWith("preview/") || branch.name.startsWith("dev")) {
      return {
        parent: "main",
        ttl: "7d", // efêmero: auto-expira 7 dias após a criação (máx 30d)
        postgres: {
          computeSettings: {
            autoscalingLimitMinCu: 0.25, // escalar para zero
            autoscalingLimitMaxCu: 1, // manter ramificações descartáveis baratas
            suspendTimeout: "5m",
          },
        },
      };
    }
    return {};
  },
});

O closure recebe um descritor somente leitura da ramificação alvo — name, exists, isDefault, parentId e mais — e retorna os ajustes a aplicar: parent, ttl (auto-expiração), protected e postgres.computeSettings. Este é o complemento declarativo para os padrões de Higiene de ciclo de vida efêmero e por PR / por teste acima: em vez de lembrar --expires-at em todo neon branches create, o TTL e o perfil de compute vivem no controle de versão e se aplicam a toda ramificação correspondente.

Como o neon checkout aplica esta política quando cria uma ramificação, uma nova ramificação preview/* ou dev-* já surge expirando e escalada para zero. Fazer checkout de uma ramificação existente não a reconcilia — execute neon deploy (alias para neon config apply) para aplicar alterações a uma ramificação que já existe.

Ramificação em CI/CD

Casos de uso comuns de ramificação Neon em CI/CD:

• Deploy de preview por PR: Ramificação ao abrir PR, faça deploy da preview contra ela, delete ao fechar. Cada PR recebe uma ramificação de banco de dados isolada. Injetar o DATABASE_URL da ramificação no aplicativo implantado é específico do provedor de hospedagem — veja preview-branches-with-cloudflare, preview-branches-with-vercel ou preview-branches-with-fly para padrões testados.
• Teste de migração em CI: Execute alterações arriscadas de esquema contra uma ramificação com dados semelhantes aos de produção antes do merge.
• Visibilidade de diff de esquema: Use a GitHub Action de schema-diff para comentar automaticamente um diff da camada de banco de dados no PR.

Exemplos

Exemplo 1: Teste de migração com dados realistas

Entrada do usuário: "Preciso testar uma migração arriscada com dados semelhantes aos de produção."

Formato de saída do agente:

1. Recomende uma ramificação normal e explique o porquê.
2. Compartilhe o link da documentação: https://neon.com/docs/introduction/branching
3. Verifique o caminho da ferramenta primeiro (CLI com neon --version; MCP apenas se a CLI não for utilizável).
4. Forneça comandos:
   • neon branches create --name migration-test --parent main --expires-at 2026-12-15T18:02:16Z
   • neon connection-string migration-test

Exemplo 2: Fluxo de trabalho de desenvolvimento com dados sensíveis

Entrada do usuário: "Não podemos copiar dados de produção por causa de compliance."

Formato de saída do agente:

1. Recomende uma ramificação somente esquema e explique o porquê.
2. Compartilhe o link da documentação: https://neon.com/docs/guides/branching-schema-only
3. Verifique o caminho da ferramenta primeiro (CLI com neon --version; MCP apenas se a CLI não for utilizável).
4. Forneça comando:
   • neon branches create --name compliance-dev --parent main --schema-only --project-id <seu-project-id> --expires-at 2026-12-15T18:02:16Z
5. Mencione o caminho de suporte Beta:
   • https://console.neon.tech/app/projects?modal=feedback
   • https://discord.gg/92vNTzKDGp

Leitura Adicional

• https://neon.com/docs/guides/branch-expiration.md
• https://neon.com/docs/guides/neon-github-integration.md
• https://neon.com/docs/ai/neon-mcp-server.md
• https://neon.com/branching