neondatabase/neon-postgres-branches

PRIMERO: Usa la skill padre neon para una visión general de Neon, comenzar con Neon, mejores prácticas de desarrollo de Neon y más.

Si la skill neon no está instalada, obténla desde https://neon.com/docs/ai/skills/neon/SKILL.md o instálala con:

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

Ramificación de Postgres en Neon

Resultado: una rama de Neon creada — o un siguiente paso claro y procesable si la creación no puede proceder. Elige el tipo de rama correcto, luego ejecuta la creación de la rama con la CLI (o MCP donde la CLI no sea utilizable).

• Rama normal para pruebas realistas de migración y consultas con datos reales.
• Rama solo de esquema (Beta) para flujos de trabajo de datos sensibles donde se necesita la estructura sin copiar filas.

Decisión del Tipo de Rama

Usa esta regla de decisión primero:

1. Si el usuario quiere probar migraciones complejas, rendimiento o comportamiento contra datos similares a producción, elige una rama normal.
2. Si el usuario necesita evitar copiar datos sensibles, elige una rama solo de esquema.

Si la solicitud es ambigua, haz una pregunta aclaratoria: "¿Necesitas datos realistas para pruebas, o solo la estructura del esquema porque los datos son sensibles?"

Selección de Herramienta: CLI o MCP

Soporta tanto la CLI de Neon como el servidor MCP de Neon, pero por defecto usa la CLI. Usa MCP solo cuando la CLI no esté disponible o esté bloqueada en tu entorno, no pueda autenticarse, o el usuario solicite explícitamente MCP.

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

Orden de selección

1. Verifica primero la CLI:
   • Ejecuta neon --version para confirmar que la CLI está instalada.
   • Ejecuta neon projects list para confirmar autenticación/contexto.
2. Si falta la CLI, dirige a la instalación a través de la guía de inicio rápido.
3. Si la CLI está instalada pero no autenticada, guía al usuario a través de neon auth (o autenticación con clave API), luego continúa.
4. Cambia a MCP cuando la CLI no pueda usarse — sin acceso a CLI en el entorno, ejecución bloqueada, o autenticación no posible — o cuando el usuario solicite explícitamente MCP. Confirma que las herramientas MCP de Neon están disponibles y autenticadas (por ejemplo, listar proyectos funciona), luego sigue el flujo de ramas MCP a continuación.
5. Si ninguna ruta tiene éxito, usa la API REST de Neon:
   • https://neon.com/docs/guides/branching-neon-api.md

Flujo de ramas MCP

1. Elige normal vs solo de esquema según la sensibilidad de los datos y los objetivos de prueba de migración.
2. Usa herramientas de ramas (por ejemplo, create_branch) para crear la rama.
3. Valida con herramientas de lectura (por ejemplo, describe_branch).
4. Para flujos de trabajo de migración, prefiere flujos de migración basados en ramas antes de aplicar a main.

Crear una Rama Normal (Preferida para Pruebas de Migración con Datos Reales)

Usa esto cuando el usuario necesite condiciones de prueba realistas. Los datos reales similares a producción pueden exponer casos límite que tus scripts semilla o migración de datos pasan por alto, lo que ayuda a detectar problemas de migración antes de la puesta en marcha.

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

Pasos

1. Primero, decide la ruta de la herramienta (ver Orden de selección): verifica la CLI con neon --version, y recurre a MCP solo si la CLI no es utilizable.

2. Asegúrate de que el contexto del proyecto esté configurado (neon set-context --project-id <tu-id-de-proyecto>) o incluye --project-id en los comandos.

3. Crea la rama:

   neon branches create \
     --name <nombre-de-la-rama> \
     --parent <id-o-nombre-de-la-rama-padre> \
     --expires-at 2026-12-15T18:02:16Z
   

4. Opcionalmente, obtén una cadena de conexión para la nueva rama:

   neon connection-string <nombre-de-la-rama>
   

Crear una Rama Solo de Esquema (Beta, Datos Sensibles)

Usa esto cuando los usuarios no deban copiar filas de producción en la rama de prueba.

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

Pasos

1. Primero, decide la ruta de la herramienta (ver Orden de selección): verifica la CLI con neon --version, y recurre a MCP solo si la CLI no es utilizable.

2. Crea la rama solo de esquema:

   neon branches create \
     --name <nombre-de-la-rama-solo-esquema> \
     --parent <id-o-nombre-de-la-rama-padre> \
     --schema-only \
     --expires-at 2026-12-15T18:02:16Z
   

   Si existen múltiples proyectos, incluye --project-id:

   neon branches create \
     --name <nombre-de-la-rama-solo-esquema> \
     --parent <id-o-nombre-de-la-rama-padre> \
     --schema-only \
     --project-id <tu-id-de-proyecto> \
     --expires-at 2026-12-15T18:02:16Z
   

Guía de Soporte Beta (Obligatorio)

La ramificación solo de esquema está en Beta. Si los usuarios informan de comportamiento inesperado, errores o capacidades faltantes:

1. Pídeles que compartan comentarios en la Consola de Neon:
   • https://console.neon.tech/app/projects?modal=feedback
2. Recomienda abrir una conversación de soporte en el Discord de Neon:
   • https://discord.gg/92vNTzKDGp

Reseteo desde el Padre

Usa esto cuando una rama secundaria se ha desviado y el usuario quiere una actualización limpia desde el esquema y datos más recientes del padre.

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

Qué hace

• Reemplaza completamente el esquema y los datos de la rama secundaria con el estado más reciente del padre.
• No fusiona; los cambios locales en la rama secundaria se pierden.
• Mantiene los mismos detalles de conexión, pero las conexiones activas se interrumpen brevemente durante el reseteo.

Cuándo recomendarlo

• La rama de desarrollo o staging está demasiado atrasada respecto a producción.
• El usuario quiere comenzar una nueva característica desde un estado limpio alineado con el padre.
• El equipo quiere actualizar staging desde producción para bases de pruebas consistentes.

Restricciones y bloqueos importantes

• Solo se pueden resetear ramas secundarias (las ramas raíz y las ramas raíz solo de esquema no se pueden resetear desde el padre).
• Si la rama objetivo tiene ramas secundarias, el reseteo está bloqueado hasta que esas ramas secundarias se eliminen.
• Después de que una rama padre se restaure desde una instantánea, el reseteo desde el padre puede no estar disponible hasta 24 horas.
• El reseteo desde el padre siempre usa el estado actual del padre; usa Restauración instantánea para necesidades de recuperación a un punto en el tiempo.

Uso de la CLI

neon branches reset <id|nombre> --parent --preserve-under-name <nombre-de-la-rama-de-respaldo>

Si el contexto del proyecto aún no está configurado, incluye el ID del proyecto:

neon branches reset <id|nombre> --parent --preserve-under-name <nombre-de-la-rama-de-respaldo> --project-id <id-del-proyecto>

--preserve-under-name guarda el estado anterior al reseteo como una rama de respaldo para revertir, pero añade una rama extra para limpiar más tarde.

Configuración opcional de contexto para evitar repetir --project-id:

neon set-context --project-id <id-del-proyecto>

Uso de la Consola y la API

• Consola: Abre la rama secundaria objetivo, luego selecciona Resetear desde el padre desde Acciones.
• API: Usa el endpoint de restauración para la rama y establece source_branch_id en el ID de la rama padre.

Notas y Advertencias

• Las ramas solo de esquema son para clonación de solo estructura y controles de datos sensibles/compatibles.
• Las ramas solo de esquema son ramas raíz independientes (sin rama padre ni historial compartido), por lo que el reseteo desde el padre no aplica.
• Para pruebas de migración que dependen de formas de filas del mundo real, volúmenes y casos límite, prefiere ramas normales.
• Los límites de ramas raíz y los límites de almacenamiento por rama pueden limitar cuántas ramas solo de esquema pueden crear los usuarios.
• Si el usuario no está seguro, la recomendación predeterminada es:
  • Rama normal para validación de migración.
  • Rama solo de esquema para restricciones de cumplimiento y privacidad.

Patrones de Flujo de Trabajo Útiles

Si el usuario solicita recomendaciones de proceso (no solo un comando único), sugiere estos:

• Una rama por PR: Crea rama cuando el PR se abre, elimínala cuando se fusiona/cierra, mantén las pruebas de migración aisladas.
• Una rama por ejecución de prueba: Crea rama al inicio del pipeline, ejecuta migraciones/pruebas, elimínala al final para una CI determinista.
• Una rama por desarrollador: Entornos de desarrollo aislados con forma similar a producción; evita colisiones de equipo en datos de prueba compartidos.
• Ramificación consciente de PII: Si producción tiene datos sensibles, deriva las ramas de dev/PR de una rama anonimizada o usa ramas solo de esquema.
• Higiene de ciclo de vida efímero: Establece la expiración de la rama y automatiza la limpieza para que las ramas viejas no acumulen costos de almacenamiento/historial evitables.

Indicación de actualización del entorno posterior a la creación

Después de la creación de la rama, pregunta si el usuario quiere actualizar las credenciales del entorno local para apuntar a la nueva rama.

• Pregunta: "¿Quieres que actualice tu DATABASE_URL de .env con esta nueva cadena de conexión de la rama?"
• Si sí, escribe la nueva cadena de conexión de la rama en el archivo/clave de entorno solicitado.
• Si no, deja las credenciales sin cambios y comparte la cadena de conexión para uso manual.
• Nunca sobrescribas una clave de entorno existente sin confirmación explícita.

Infraestructura como Código de Neon (neon.ts)

Además de crear ramas de forma imperativa (CLI / MCP / API arriba), puedes programar qué configuración reciben las nuevas ramas de forma declarativa en neon.ts — el archivo de infraestructura como código de Neon (consulta la skill neon para la referencia completa). La propiedad branch es una función de la rama que se está evaluando y devuelve su configuración, por lo que cada rama nacida de tu proyecto recibe un ciclo de vida y un perfil de cómputo consistentes sin banderas por rama.

npm i @neon/config

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

export default defineConfig({
  branch: (branch) => {
    if (branch.exists) return {}; // nunca reconciliar ramas 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 días después de la creación (máx. 30d)
        postgres: {
          computeSettings: {
            autoscalingLimitMinCu: 0.25, // escalar a cero
            autoscalingLimitMaxCu: 1, // mantener ramas desechables baratas
            suspendTimeout: "5m",
          },
        },
      };
    }
    return {};
  },
});

El closure recibe un descriptor de solo lectura de la rama objetivo — name, exists, isDefault, parentId y más — y devuelve el ajuste a aplicar: parent, ttl (auto-expiración), protected y postgres.computeSettings. Este es el complemento declarativo de los patrones de Higiene de ciclo de vida efímero y por PR / por prueba anteriores: en lugar de recordar --expires-at en cada neon branches create, el TTL y el perfil de cómputo viven en el control de versiones y se aplican a cada rama que coincida.

Como neon checkout aplica esta política cuando crea una rama, una nueva rama preview/* o dev-* aparece ya expirando y escalada a cero. Hacer checkout de una rama existente no la reconcilia — ejecuta neon deploy (alias de neon config apply) para aplicar cambios a una rama que ya existe.

Ramificación en CI/CD

Casos de uso comunes de ramas de Neon en CI/CD:

• Despliegues de vista previa por PR: Ramifica al abrir el PR, despliega la vista previa contra ella, elimínala al cerrar. Cada PR obtiene una rama de base de datos aislada. Inyectar la DATABASE_URL de la rama en la aplicación desplegada depende del proveedor de hosting — consulta preview-branches-with-cloudflare, preview-branches-with-vercel o preview-branches-with-fly para patrones probados.
• Pruebas de migración en CI: Ejecuta cambios de esquema arriesgados contra una rama con datos similares a producción antes de fusionar.
• Visibilidad de diferencias de esquema: Usa la Acción de GitHub schema-diff para comentar automáticamente una diferencia de la capa de base de datos en el PR.

Ejemplos

Ejemplo 1: Pruebas de migración con datos realistas

Entrada del usuario: "Necesito probar una migración arriesgada contra datos similares a producción."

Forma de salida del agente:

1. Recomienda una rama normal y explica por qué.
2. Comparte el enlace de documentación: https://neon.com/docs/introduction/branching
3. Verifica primero la ruta de la herramienta (CLI con neon --version; MCP solo si la CLI no es utilizable).
4. Proporciona comandos:
   • neon branches create --name migration-test --parent main --expires-at 2026-12-15T18:02:16Z
   • neon connection-string migration-test

Ejemplo 2: Flujo de trabajo de desarrollo con datos sensibles

Entrada del usuario: "No podemos copiar datos de producción debido a cumplimiento normativo."

Forma de salida del agente:

1. Recomienda una rama solo de esquema y explica por qué.
2. Comparte el enlace de documentación: https://neon.com/docs/guides/branching-schema-only
3. Verifica primero la ruta de la herramienta (CLI con neon --version; MCP solo si la CLI no es utilizable).
4. Proporciona el comando:
   • neon branches create --name compliance-dev --parent main --schema-only --project-id <tu-id-de-proyecto> --expires-at 2026-12-15T18:02:16Z
5. Menciona la ruta de soporte Beta:
   • https://console.neon.tech/app/projects?modal=feedback
   • https://discord.gg/92vNTzKDGp

Lecturas Adicionales

• 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