Branchement Neon Postgres

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

• Branche normale pour tester les migrations et requêtes de manière réaliste avec des données réelles.
• Branche schema-only (Bêta) pour les workflows 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, la performance ou le comportement par rapport à des données ressemblant à 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 du schéma parce que les données sont sensibles ? »

Sélection d'outil : CLI ou MCP

Soutenez 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/cli/quickstart.md

Ordre de sélection

1. Vérifiez d'abord MCP dans les environnements compatibles MCP :
   • Si les tools Neon MCP sont disponibles et authentifiés (par exemple, lister les projets fonctionne), utilisez MCP.
2. Si MCP n'est pas disponible ou pas authentifié, vérifiez la CLI :
   • Exécutez neon --version pour confirmer que la CLI est installée.
   • Exécutez neon projects list pour confirmer l'authentification/contexte.
3. Si la CLI est manquante, dirigez vers l'installation via quickstart.
4. Si la CLI est installée mais pas authentifiée, guidez l'utilisateur à travers neon 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 tools de branche (par exemple, create_branch) pour créer la branche.
3. Validez avec les tools de lecture (par exemple, describe_branch).
4. Pour les workflows de migration, préférez les flux de migration basés sur les branches avant d'appliquer à main.

Créer une branche normale (préférée pour tester les migrations avec données réelles)

Utilisez cette option quand l'utilisateur a besoin de conditions de test réalistes. Les données réalistes de production 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.

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

Étapes

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

neon 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 :

neon connection-string <branch-name>

Créer une branche schema-only (Bêta, données sensibles)

Utilisez cette option 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 s'il est déjà disponible/authentifié ; sinon vérifiez la CLI avec neon --version.
2. Créez la branche schema-only :

neon 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 :

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

Guidance de support Bêta (obligatoire)

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

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

Réinitialiser à partir du parent

Utilisez cette option quand une branche enfant a dérivé et que l'utilisateur veut une actualisation propre du dernier schéma et données du 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 du parent.
• N'est pas une fusion ; les changements locaux sur la branche enfant sont perdus.
• 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 veut commencer une nouvelle feature à partir d'un état parent propre et aligné.
• L'équipe veut rafraîchir staging à partir de la production pour des baselines de test cohérentes.

Contraintes strictes et bloqueurs

• Seules les branches enfants peuvent être réinitialisées (les branches root et les branches root 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'un snapshot, reset-from-parent peut être indisponible pendant jusqu'à 24 heures.
• Reset-from-parent utilise toujours l'état parent courant ; utilisez Instant restore pour les besoins de récupération point-in-time.

Utilisation CLI

neon 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 :

neon 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 le rollback, mais ajoute une branche supplémentaire à nettoyer plus tard.

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

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

Utilisation de la console et de l'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.

Remarques 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 root indépendantes (pas de branche parent et pas d'historique partagé), donc reset-from-parent ne s'applique pas.
• Pour tester les migrations qui dépendent de formes de lignes réalistes, de volumes et de cas limites, préférez les branches normales.
• Les allocations de branche root 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 incertain, 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 seule commande), suggérez ceux-ci :

• Une branche par PR : Créez une branche à l'ouverture de la PR, supprimez-la lors de la fusion/fermeture, isolez les tests de migration.
• Une branche par test run : Créez une branche au démarrage du pipeline, exécutez les migrations/tests, supprimez-la à la fin pour un CI déterministe.
• Une branche par développeur : Environnements dev isolés avec une forme ressemblant à la production ; évitez les collisions d'équipe sur les données de test partagées.
• Branchement conscient des PII : Si la production a des données sensibles, dérivez les branches dev/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/historique évitables.

Prompt de mise à jour d'environnement post-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 .env vers cette nouvelle chaîne de connexion de branche ? »
• Si oui, écrivez la nouvelle chaîne de connexion de branche dans le fichier/clé env demandé.
• Si non, laissez les identifiants inchangés et partagez la chaîne de connexion pour utilisation manuelle.
• Ne surchargez jamais une clé env existante sans confirmation explicite.

Infrastructure en tant que code Neon (neon.ts)

Au-delà de créer des branches de manière impérative (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 infrastructure-as-code de Neon (voir la skill neon pour la référence complète). La propriété branch est une fonction de la branche en cours d'évaluation qui retourne ses paramètres, donc chaque branche créée à partir de votre projet obtient un cycle de vie cohérent et un profil de compute sans flags per-branch.

npm i @neon/config

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

export default defineConfig({
  branch: (branch) => {
    if (branch.exists) return {}; // ne réconciliez jamais 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 : auto-expire 7 jours après la création (max 30d)
        postgres: {
          computeSettings: {
            autoscalingLimitMinCu: 0.25, // scale to zero
            autoscalingLimitMaxCu: 1, // gardez 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 retourne le tuning à appliquer : parent, ttl (auto-expiry), protected, et postgres.computeSettings. C'est le complément déclaratif de l'hygiène du cycle de vie éphémère et des modèles per-PR / per-test ci-dessus : au lieu de mémoriser --expires-at sur chaque neon branches create, le TTL et le profil de compute vivent dans le contrôle de version et s'appliquent à chaque branche correspondante.

Parce que neon checkout applique cette politique quand il crée une branche, une nouvelle branche preview/* ou dev-* s'exécute déjà avec expiration et scale-to-zero. Vérifier 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 en CI/CD

Cas d'usage courants de CI/CD pour les branches Neon :

• Déploiements de preview par PR : Branche à l'ouverture de la PR, déployez la preview par rapport à celle-ci, supprimez à la fermeture. Chaque PR obtient une branche de base de données isolée. Injecter la DATABASE_URL de la branche dans l'app déployée est spécifique au fournisseur d'hébergement — voir preview-branches-with-cloudflare, preview-branches-with-vercel, ou preview-branches-with-fly pour des modèles testés.
• Test de migration en CI : Exécutez les changements de schéma risqués par rapport à une branche avec des données ressemblant à la production avant la fusion.
• Visibilité de schema diff : Utilisez la GitHub Action schema-diff pour auto-commenter un diff de couche DB sur la PR.

Exemples

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

Entrée utilisateur : « Je dois tester une migration risquée par rapport à des données ressemblant à la production. »

Forme de sortie agent :

1. Recommandez une branche normale et expliquez pourquoi.
2. Partagez le lien doc : https://neon.com/docs/introduction/branching
3. Vérifiez d'abord le chemin d'outil disponible/authentifié (MCP, sinon CLI avec neon --version).
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 pour des raisons de conformité. »

Forme de sortie agent :

1. Recommandez une branche schema-only et expliquez pourquoi.
2. Partagez le lien doc : https://neon.com/docs/guides/branching-schema-only
3. Vérifiez d'abord le chemin d'outil disponible/authentifié (MCP, sinon CLI avec neon --version).
4. Fournissez la commande :
   • neon 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 de support Bêta :
   • https://console.neon.tech/app/projects?modal=feedback
   • https://discord.gg/92vNTzKDGp

Pour aller plus loin

• 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