Branchement Neon Postgres

Le résultat de cette compétence doit être une branche Neon créée (ou une prochaine étape claire et exploitable si la création ne peut pas procéder). Choisissez le bon type de branche, puis exécutez la création de branche via MCP ou CLI.

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

Décision du type de branche

Utilisez d'abord cette règle de décision :

1. Si l'utilisateur veut tester des migrations complexes, les performances ou le comportement par rapport à des données similaires à 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 la structure du schéma car les données sont sensibles ?"

Sélection des outils : CLI ou MCP

Supportez toujours à la fois la CLI Neon et le serveur MCP Neon. Préférez l'outil que l'utilisateur a déjà installé et authentifié.

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

Ordre de sélection

1. Vérifiez d'abord MCP dans les environnements compatibles MCP :
   • Si les outils Neon MCP sont disponibles et authentifiés (par exemple, lister les projets fonctionne), utilisez MCP.
2. Si MCP n'est pas disponible ou non authentifié, vérifiez CLI :
   • Exécutez neonctl --version pour confirmer que CLI est installée.
   • Exécutez neonctl projects list pour confirmer l'auth/contexte.
3. Si CLI est manquante, orientez vers l'installation via quickstart.
4. Si CLI est installée mais non authentifiée, guidez l'utilisateur à travers neonctl auth (ou authentification par clé API), puis continuez.
5. Si les deux chemins MCP et CLI échouent, 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 les outils de lecture (par exemple, describe_branch).
4. Pour les flux de migration, privilégiez les flux de migration basés sur les branches avant d'appliquer à la branche principale.

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

Utilisez ceci quand l'utilisateur a besoin de conditions de test réalistes. Les données similaires à la production réelle peuvent exposer 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 le lancement en production.

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

Étapes

1. Utilisez MCP si déjà disponible/authentifié ; sinon vérifiez CLI avec neonctl --version.
2. Assurez-vous que le contexte du projet est défini (neonctl set-context --project-id <your-project-id>) ou incluez --project-id sur les commandes.
3. Créez la branche :

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

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

neonctl connection-string <branch-name>

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

Utilisez ceci quand 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. Utilisez MCP si déjà disponible/authentifié ; sinon vérifiez CLI avec neonctl --version.
2. Créez la branche schema-only :

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

Si plusieurs projets existent, incluez :

neonctl 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

Orientation du support Beta (Obligatoire)

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

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

Réinitialiser à partir du parent

Utilisez ceci quand une branche enfant a dérivé et que l'utilisateur veut un rafraîchissement propre à partir du schéma et des données les plus récents de la branche parent.

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

Ce qu'il fait

• Remplace complètement le schéma et les données de la branche enfant par l'état le plus récent du 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 lors de la réinitialisation.

Quand le recommander

• La branche de développement ou de staging est trop en retard sur la production.
• L'utilisateur veut commencer une nouvelle fonction à partir d'un état propre aligné avec le parent.
• L'équipe veut rafraîchir staging à partir de la production pour avoir des bases de test cohérentes.

Contraintes strictes et blocages

• 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 à partir du 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 la restauration d'une branche parent à partir d'une snapshot, reset-from-parent peut ne pas être disponible pendant jusqu'à 24 heures.
• Reset-from-parent utilise toujours l'état parent actuel ; utilisez la restauration instantanée pour les besoins de récupération à un point dans le temps.

Utilisation CLI

neonctl branches reset <id|name> --parent --preserve-under-name <backup-branch-name>

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

neonctl branches reset <id|name> --parent --preserve-under-name <backup-branch-name> --project-id <project-id>

--preserve-under-name conserve l'état pré-réinitialisation comme branche de sauvegarde pour la restauration, mais ajoute une branche supplémentaire à nettoyer plus tard.

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

neonctl set-context --project-id <project-id>

Utilisation Console et API

• Console : Ouvrez la branche enfant cible, puis sélectionnez Reset from parent dans Actions.
• API : Utilisez l'endpoint de restauration pour la branche et définissez source_branch_id sur l'ID de la branche parent.

Notes et réserves

• Les branches schema-only sont pour le clonage de structure uniquement et les contrôles de données sensibles/conformes.
• Les branches schema-only sont des branches racines indépendantes (pas de branche parent et pas d'historique partagé), donc reset-from-parent ne s'applique pas.
• Pour le test de migration qui dépend des formes, volumes et cas limites réels des lignes, préférez les branches normales.
• Les allocations de branche racine 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 flux de travail utiles

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

• Une branche par PR : Créez une branche quand la PR s'ouvre, supprimez-la quand 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émarrage du pipeline, exécutez les migrations/tests, supprimez à la fin pour une CI déterministe.
• Une branche par développeur : Environnements de développement isolés avec une forme similaire à la production ; évitez les collisions d'équipe sur les données de test partagées.
• Branchement sensible aux PII : Si la production contient des données sensibles, dérivez les branches dev/PR à partir d'une branche anonymisée ou utilisez des branches schema-only.
• Hygiène du cycle de vie éphémère : Définissez l'expiration de la branche et automatisez le nettoyage pour que les anciennes branches ne s'accumulent pas avec des coûts de stockage/historique évitables.

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

Après la création de la branche, demandez si l'utilisateur veut mettre à jour les identifiants d'environnement locaux pour pointer vers la nouvelle branche.

• Demandez : "Voulez-vous que je mette à jour votre DATABASE_URL dans .env vers cette nouvelle chaîne de connexion de branche ?"
• Si oui, écrivez la nouvelle chaîne de connexion de branche vers le fichier/clé env demandé.
• Si non, laissez les identifiants inchangés et partagez la chaîne de connexion pour un usage manuel.
• Ne remplacez jamais une clé env existante sans confirmation explicite.

Exemples

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

Entrée utilisateur : "I need to test a risky migration against production-like data."

Forme de sortie de l'agent :

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

Exemple 2 : Flux de travail de développement de données sensibles

Entrée utilisateur : "We cannot copy production data because of compliance."

Forme de sortie de l'agent :

1. Recommandez une branche schema-only et expliquez pourquoi.
2. Partagez le lien de la doc : https://neon.com/docs/guides/branching-schema-only
3. Vérifiez d'abord le chemin de l'outil disponible/authentifié (MCP, sinon CLI avec neonctl --version).
4. Fournissez la commande :
   • neonctl branches create --name compliance-dev --parent main --schema-only --project-id <your-project-id> --expires-at 2026-12-15T18:02:16Z
5. Mentionnez le chemin du 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