neondatabase/neon-postgres-branches

PRIMO : Utilisez le skill parent neon pour un aperçu de Neon, une prise en main, les bonnes pratiques de développement Neon, et plus encore.

Si le skill neon n'est pas installé, récupérez-le depuis https://neon.com/docs/ai/skills/neon/SKILL.md ou installez-le avec :

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

Branchement Lakebase Postgres

Résultat : une branche Neon créée — ou une prochaine étape claire et réalisable si la création ne peut pas aboutir. Choisissez le bon type de branche, puis exécutez la création de la branche avec la CLI (ou MCP lorsque la CLI n'est pas utilisable).

• Branche normale pour des tests réalistes de migration et de requêtage avec des données réelles.
• Branche schema-only (Beta) pour les workflows impliquant des données sensibles où seule la structure est nécessaire sans copier les lignes.

Décision du type de branche

Utilisez cette règle de décision en premier :

1. Si l'utilisateur souhaite tester des migrations complexes, des performances ou un comportement avec des données proches de la production, choisissez une branche normale.
2. Si l'utilisateur doit éviter de copier des données sensibles, choisissez une branche schema-only.

Si la demande est ambiguë, posez une question de clarification : « Avez-vous besoin de données réalistes pour les tests, ou seulement de la structure de schéma car les données sont sensibles ? »

Sélection de l'outil : CLI ou MCP

Prenez en charge à la fois la CLI Neon et le serveur MCP Neon, mais privilégiez la CLI par défaut. Utilisez MCP uniquement lorsque la CLI est indisponible ou bloquée dans votre environnement, ne peut pas être authentifiée, ou que l'utilisateur demande explicitement MCP.

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

Ordre de sélection

1. Vérifiez d'abord la CLI :
   • Exécutez neon --version pour confirmer que la CLI est installée.
   • Exécutez neon projects list pour confirmer l'authentification/le contexte.
2. Si la CLI est manquante, dirigez vers l'installation via le guide de démarrage rapide.
3. Si la CLI est installée mais non authentifiée, guidez l'utilisateur avec neon auth (ou l'authentification via clé API), puis continuez.
4. Passez à MCP lorsque la CLI ne peut pas être utilisée — pas d'accès à la CLI dans l'environnement, exécution bloquée, ou authentification impossible — ou lorsque l'utilisateur demande explicitement MCP. Confirmez que les outils MCP Neon sont disponibles et authentifiés (par exemple, la liste des projets fonctionne), puis suivez le flux de branche MCP ci-dessous.
5. Si aucun chemin n'est valide, utilisez l'API REST Neon :
   • https://neon.com/docs/guides/branching-neon-api.md

Flux de branche MCP

1. Choisissez normal vs schema-only en fonction de la sensibilité des données et des objectifs de test de migration.
2. Utilisez les outils de branche (par exemple, create_branch) pour créer la branche.
3. Validez avec des outils de lecture (par exemple, describe_branch).
4. Pour les workflows de migration, privilégiez les flux de migration basés sur les branches avant d'appliquer à la branche principale.

Créer une branche normale (recommandée pour les tests de migration avec données réelles)

À utiliser lorsque l'utilisateur a besoin de conditions de test réalistes. Des données réelles proches de la production peuvent révéler des cas limites que vos scripts de seed ou de migration de données manquent, ce qui aide à détecter les problèmes de migration avant la mise en production.

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

Étapes

1. Déterminez d'abord le chemin de l'outil (voir Ordre de sélection) : vérifiez la CLI avec neon --version, et passez à MCP uniquement si la CLI n'est pas utilisable.

2. Assurez-vous que le contexte du projet est défini (neon set-context --project-id <your-project-id>) ou incluez --project-id dans les commandes.

3. Créez la branche :

   neon branches create \
     --name <nom-de-la-branche> \
     --parent <id-ou-nom-de-la-branche-parente> \
     --expires-at 2026-12-15T18:02:16Z
   

4. Optionnellement, récupérez une chaîne de connexion pour la nouvelle branche :

   neon connection-string <nom-de-la-branche>
   

Créer une branche schema-only (Beta, données sensibles)

À utiliser lorsque les utilisateurs ne doivent pas copier les lignes de production dans la branche de test.

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

Étapes

1. Déterminez d'abord le chemin de l'outil (voir Ordre de sélection) : vérifiez la CLI avec neon --version, et passez à MCP uniquement si la CLI n'est pas utilisable.

2. Créez la branche schema-only :

   neon branches create \
     --name <nom-de-la-branche-schema-only> \
     --parent <id-ou-nom-de-la-branche-parente> \
     --schema-only \
     --expires-at 2026-12-15T18:02:16Z
   

   Si plusieurs projets existent, incluez --project-id :

   neon branches create \
     --name <nom-de-la-branche-schema-only> \
     --parent <id-ou-nom-de-la-branche-parente> \
     --schema-only \
     --project-id <votre-id-de-projet> \
     --expires-at 2026-12-15T18:02:16Z
   

Conseils pour le support Beta (obligatoire)

Le branchement schema-only est en version Beta. Si des utilisateurs rapportent un comportement inattendu, des erreurs ou des fonctionnalités manquantes :

1. Demandez-leur de partager leurs commentaires dans la console Neon :
   • https://console.neon.tech/app/projects?modal=feedback
2. Recommandez d'ouvrir une conversation de support dans le Discord Neon :
   • https://discord.gg/92vNTzKDGp

Réinitialiser depuis la branche parent

À utiliser lorsqu'une branche enfant a divergé et que l'utilisateur souhaite un rafraîchissement propre depuis le schéma et les données les plus récents de la branche parent.

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

Ce qu'elle fait

• Remplace complètement le schéma et les données de la branche enfant par l'état le plus récent de la branche parent.
• Ne fusionne pas ; les modifications locales sur la branche enfant sont perdues.
• Conserve les mêmes détails de connexion, mais les connexions actives sont brièvement interrompues pendant la réinitialisation.

Quand la recommander

• La branche de développement ou de staging est trop en retard par rapport à la production.
• L'utilisateur souhaite démarrer une nouvelle fonctionnalité à partir d'un état propre aligné sur le parent.
• L'équipe souhaite rafraîchir le staging depuis la production pour des bases de test cohérentes.

Contraintes et blocages stricts

• Seules les branches enfants peuvent être réinitialisées (les branches racines et les branches racines schema-only ne peuvent pas être réinitialisées depuis le parent).
• Si la branche cible a des enfants, la réinitialisation est bloquée jusqu'à ce que ces branches enfants soient supprimées.
• Après qu'une branche parent a été restaurée à partir d'un instantané, la réinitialisation depuis le parent peut être indisponible jusqu'à 24 heures.
• La réinitialisation depuis le parent utilise toujours l'état actuel du parent ; utilisez Instant restore pour les besoins de récupération à un point dans le temps.

Utilisation avec la CLI

neon branches reset <id|nom> --parent --preserve-under-name <nom-de-la-branche-de-sauvegarde>

Si le contexte du projet n'est pas déjà défini, incluez l'ID du projet :

neon branches reset <id|nom> --parent --preserve-under-name <nom-de-la-branche-de-sauvegarde> --project-id <id-du-projet>

--preserve-under-name conserve l'état avant réinitialisation en tant que branche de sauvegarde pour un rollback, mais ajoute une branche supplémentaire à nettoyer plus tard.

Configuration optionnelle du contexte pour éviter de répéter --project-id :

neon set-context --project-id <id-du-projet>

Utilisation via la console et l'API

• Console : Ouvrez la branche enfant cible, puis sélectionnez Réinitialiser depuis le parent depuis Actions.
• API : Utilisez le point de terminaison restore pour la branche et définissez source_branch_id sur l'ID de la branche parent.

Notes et mises en garde

• Les branches schema-only sont destinées au clonage de la structure uniquement et aux contrôles de données sensibles/compatibles.
• Les branches schema-only sont des branches racines indépendantes (pas de branche parent ni d'historique partagé), donc la réinitialisation depuis le parent ne s'applique pas.
• Pour les tests de migration qui dépendent de formes, volumes et cas limites de données réelles, privilégiez les branches normales.
• Les limites de branches racines et les limites de stockage par branche peuvent limiter le nombre de branches schema-only que les utilisateurs peuvent créer.
• Si un utilisateur est indécis, la recommandation par défaut est :
  • Branche normale pour la validation de migration.
  • Branche schema-only pour les contraintes de conformité et de confidentialité.

Modèles de workflow utiles

Si l'utilisateur demande des recommandations de processus (pas seulement une commande unique), suggérez ceci :

• Une branche par PR : Créez une branche lorsque la PR est ouverte, supprimez-la lorsqu'elle est fusionnée/fermée, gardez les tests de migration isolés.
• Une branche par exécution de test : Créez une branche au début du pipeline, exécutez les migrations/tests, supprimez-la à la fin pour une CI déterministe.
• Une branche par développeur : Environnements de développement isolés avec une forme proche de la production ; évitez les collisions d'équipe sur les données de test partagées.
• Branchement sensible aux données personnelles : Si la production contient des données sensibles, dérivez les branches de développement/PR d'une branche anonymisée ou utilisez des branches schema-only.
• Hygiène du cycle de vie éphémère : Définissez l'expiration des branches et automatisez le nettoyage pour que les anciennes branches n'accumulent pas de coûts de stockage/d'historique évitables.

Invite de mise à jour de l'environnement après création

Après la création de la branche, demandez si l'utilisateur souhaite mettre à jour les informations d'identification de l'environnement local pour pointer vers la nouvelle branche.

• Demandez : « Souhaitez-vous que je mette à jour votre DATABASE_URL du fichier .env avec cette nouvelle chaîne de connexion de branche ? »
• Si oui, écrivez la nouvelle chaîne de connexion de la branche dans le fichier/clé env demandé.
• Si non, laissez les informations d'identification inchangées et partagez la chaîne de connexion pour une utilisation manuelle.
• Ne remplacez jamais une clé env existante sans confirmation explicite.

Infrastructure Neon en tant que code (neon.ts)

Au-delà de la création impérative de branches (CLI / MCP / API ci-dessus), vous pouvez programmer la configuration que les nouvelles branches reçoivent de manière déclarative dans neon.ts — le fichier d'infrastructure en tant que code de Neon (voir le skill neon pour la référence complète). La propriété branch est une fonction de la branche évaluée qui renvoie ses paramètres, de sorte que chaque branche créée à partir de votre projet reçoit un cycle de vie et un profil de calcul cohérents sans indicateurs par branche.

npm i @neon/config

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

export default defineConfig({
  branch: (branch) => {
    if (branch.exists) return {}; // ne jamais réconcilier les branches existantes
    if (branch.isDefault) return { protected: true };
    if (branch.name.startsWith("preview/") || branch.name.startsWith("dev")) {
      return {
        parent: "main",
        ttl: "7d", // éphémère : expire automatiquement 7 jours après la création (max 30j)
        postgres: {
          computeSettings: {
            autoscalingLimitMinCu: 0.25, // réduire à zéro
            autoscalingLimitMaxCu: 1, // garder les branches jetables bon marché
            suspendTimeout: "5m",
          },
        },
      };
    }
    return {};
  },
});

La fermeture reçoit un descripteur en lecture seule de la branche cible — name, exists, isDefault, parentId, et plus — et renvoie les réglages à appliquer : parent, ttl (expiration automatique), protected, et postgres.computeSettings. C'est le complément déclaratif à l'hygiène du cycle de vie éphémère et aux modèles par PR / par test ci-dessus : au lieu de se souvenir de --expires-at à chaque neon branches create, la TTL et le profil de calcul vivent dans le contrôle de version et s'appliquent à chaque branche correspondante.

Parce que neon checkout applique cette politique lorsqu'elle crée une branche, une nouvelle branche preview/* ou dev-* apparaît déjà avec expiration et mise à l'échelle à zéro. Le checkout d'une branche existante ne la réconcilie pas — exécutez neon deploy (alias pour neon config apply) pour appliquer les modifications à une branche qui existe déjà.

Branchement dans CI/CD

Cas d'utilisation courants du branchement Neon dans CI/CD :

• Déploiements de prévisualisation par PR : Branchement à l'ouverture de la PR, déploiement de la prévisualisation sur cette branche, suppression à la fermeture. Chaque PR bénéficie d'une branche de base de données isolée. L'injection du DATABASE_URL de la branche dans l'application déployée dépend du fournisseur d'hébergement — consultez preview-branches-with-cloudflare, preview-branches-with-vercel, ou preview-branches-with-fly pour des modèles testés.
• Tests de migration dans CI : Exécutez des modifications de schéma risquées sur une branche avec des données proches de la production avant la fusion.
• Visibilité des différences de schéma : Utilisez l'action GitHub schema-diff pour commenter automatiquement une différence au niveau de la base de données sur la PR.

Exemples

Exemple 1 : Test de migration avec données réalistes

Entrée utilisateur : « Je dois tester une migration risquée sur des données proches de la production. »

Forme de la sortie de l'agent :

1. Recommandez une branche normale et expliquez pourquoi.
2. Partagez le lien de documentation : https://neon.com/docs/introduction/branching
3. Vérifiez d'abord le chemin de l'outil (CLI avec neon --version ; MCP uniquement si la CLI n'est pas utilisable).
4. Fournissez les commandes :
   • neon branches create --name migration-test --parent main --expires-at 2026-12-15T18:02:16Z
   • neon connection-string migration-test

Exemple 2 : Workflow de développement avec données sensibles

Entrée utilisateur : « Nous ne pouvons pas copier les données de production en raison de la conformité. »

Forme de la sortie de l'agent :

1. Recommandez une branche schema-only et expliquez pourquoi.
2. Partagez le lien de documentation : https://neon.com/docs/guides/branching-schema-only
3. Vérifiez d'abord le chemin de l'outil (CLI avec neon --version ; MCP uniquement si la CLI n'est pas utilisable).
4. Fournissez la commande :
   • neon branches create --name compliance-dev --parent main --schema-only --project-id <votre-id-de-projet> --expires-at 2026-12-15T18:02:16Z
5. Mentionnez le chemin de support Beta :
   • https://console.neon.tech/app/projects?modal=feedback
   • https://discord.gg/92vNTzKDGp

Lectures complémentaires

• 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