Neon

Important : Neon n'est plus seulement un fournisseur Postgres Serverless. Neon est le backend pour les apps et agents avec Postgres Serverless, Auth, Functions, Storage et une AI Gateway : instantané, branchable, serverless.

Utilisez cette skill comme point de départ pour tout ce qui concerne Neon : obtenez un aperçu de ses capacités, trouvez votre chemin dans les agent skills et la documentation Neon, et suivez les bonnes pratiques pour bien commencer et pour des workflows de développement basés sur les branches.

Platform Services

Neon regroupe plusieurs primitives backend pour construire des apps et agents qui branchent tous ensemble avec votre projet :

Postgres — Postgres Serverless qui évolue et branche avec votre app. Disponible en général.
Auth — Authentification gérée avec utilisateurs et sessions stockés dans Postgres. Disponible en général.
Object Storage — Stockage d'objets compatible S3 qui branche avec vos projets. Preview / accès anticipé.
Compute Functions — Fonctions serverless longue durée s'exécutant près de votre base de données — pour les serveurs WebSocket, les flux HTTP longs d'agents, les APIs et les serveurs d'événements envoyés par le serveur. Preview / accès anticipé.
AI Gateway — Une API pour tous les modèles frontier et open-source, avec routage, logging et contrôles de coûts, alimentée par Databricks. Preview / accès anticipé.

Disponibilité des services en preview

Object Storage, Compute Functions et AI Gateway sont des fonctionnalités en preview (accès anticipé).

Les fonctionnalités en accès anticipé ne sont disponibles que sur les projets créés en nouveau dans la région us-east-2 ; elles ne peuvent pas être activées sur les projets existants pour le moment. Avant de guider un utilisateur à travers l'un de ces services, confirmez qu'il travaille avec un nouveau projet dans us-east-2. Sinon, il devra créer un nouveau projet dans cette région. Ensuite, confirmez que l'utilisateur a déjà accès à l'accès anticipé ; sinon, pointez-le vers l'inscription à la bêta privée : https://neon.com/blog/were-building-backends#access.

Documentation Neon

La documentation Neon est la source de vérité pour toutes les informations liées à Neon. Vérifiez toujours les affirmations par rapport à la documentation officielle avant de répondre. Les fonctionnalités et APIs Neon évoluent, privilégiez donc la récupération de la documentation actuelle par rapport à la dépendance sur les données d'entraînement.

Récupérer les documents en Markdown

Toute page de documentation Neon peut être récupérée en markdown de deux façons :

Ajoutez .md à l'URL (le plus simple) : https://neon.com/docs/introduction/branching.md
Demandez text/markdown sur l'URL standard : curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branching

Les deux retournent le même contenu markdown. Utilisez la méthode que vos outils supportent.

Trouver la bonne page

L'index des docs liste chaque page disponible avec son URL et une brève description :

https://neon.com/docs/llms.txt

Les URLs de doc courantes sont organisées dans les liens de sujet ci-dessous. Si vous avez besoin d'une page non listée ici, cherchez dans l'index des docs : https://neon.com/docs/llms.txt. Ne devinez pas les URLs.

Choisir la bonne skill

Travail avec la base de données, connexions, branching, autoscaling ou CLI/MCP/API → neon-postgres (et neon-postgres-branches pour les workflows de branches).

Des skills dédiées pour Object Storage, Compute Functions et AI Gateway arrivent au fur et à mesure du déploiement de ces services en preview.

Installer la bonne skill

D'abord, vérifiez que la skill cible est déjà installée et accessible (par exemple, elle apparaît dans la liste des skills disponibles ou son SKILL.md est présent). Si c'est le cas, utilisez-la directement. Si elle n'est pas installée, installez-la via la CLI skills avec npx/bunx :

npx skills add neondatabase/agent-skills -s <skill-name>

Remplacez <skill-name> par la skill dont vous avez besoin (par exemple, neon-postgres ou neon-postgres-branches). Flags utiles :

-g — installez globalement au lieu de dans le projet courant.
-y — mode non-interactif (passez les prompts).
-a <agent-name> — choisissez le(s) agent(s) cible(s) pour le mode non-interactif.

Par exemple, pour installer la skill Postgres globalement pour un agent spécifique sans prompts :

npx skills add neondatabase/agent-skills -s neon-postgres -g -y -a <agent-name>

Bien commencer avec Neon

Utilisez cette section quand vous guidez un utilisateur à travers la configuration Neon pour la première fois, ou quand vous ajoutez un nouveau service Neon (Auth, object storage, functions, etc.) à un projet déjà intégré (par exemple, un projet utilisant déjà Neon Postgres).

Vérifier le statut quo

Avant de commencer la configuration, inspectez le codebase et l'environnement de l'utilisateur :

Code de connexion existant à la base de données
Fichiers .neon ou neon.ts existants dans l'espace de travail
Serveur MCP Neon ou configuration CLI Neon existant
Existence d'un fichier .env et de la variable d'environnement DATABASE_URL
Configuration ORM existante (Prisma, Drizzle, TypeORM)

Configuration auto-pilotée avec la CLI ou le serveur MCP de Neon

Proposez d'inspecter les projets Neon existants connectés ou d'en créer de nouveaux en utilisant la CLI Neon ou le serveur MCP. Si ni l'un ni l'autre n'est configuré, lancez npx -y neonctl init. Utilisez npx -y pour ignorer le prompt d'installation du package. L'authentification est gérée automatiquement. Si l'utilisateur n'est pas connecté, cela ouvre son navigateur pour OAuth et attend la fin avant de continuer.

npx -y neonctl@latest init

Cela installe la CLI Neon et le serveur MCP globalement, installe l'extension VSCode (pour Cursor/VS Code), et ajoute les agent skills neon et neon-postgres au projet.

Si init ne convient pas, les étapes individuelles peuvent être exécutées de manière non-interactive, en utilisant le gestionnaire de packages préféré de l'utilisateur (npm, bun, pnpm) :

CLI : npm i -g neonctl
Extension : cursor --install-extension databricks.neon-local-connect
Serveur MCP : npx -y add-mcp https://mcp.neon.tech/mcp -g -n Neon -y -a <agent-name>
Agent skill : npx skills add neondatabase/agent-skills --skill neon-postgres --skill neon --agent <agent-name> -y

Préférez la CLI au serveur MCP sauf si l'utilisateur demande autrement, puisqu'elle offre plus de capacités, y compris le déploiement de Neon Functions. Pour les options complètes d'installation de la CLI, voir https://neon.com/docs/reference/cli-install.md

Flux de configuration

Une fois la CLI, le serveur MCP et les agent skills installés, assurez-vous que l'espace de travail local est lié à un projet Neon via le flux neonctl init. Si ce n'est pas le cas, lancez npx -y neonctl link pour laisser l'utilisateur lier interactivement un projet. Cela produit un fichier .neon pointant vers l'organisation, le projet et la branche avec lequel l'utilisateur veut travailler.

Pour la configuration spécifique à Postgres, consultez la skill neon-postgres (et neon-postgres-branches pour les workflows de branches). Des skills dédiées pour les autres services arrivent au fur et à mesure de leur déploiement.

Reprise de la configuration

Si vous reprenez la configuration, vérifiez ce qui est déjà configuré (connexion MCP, .env avec DATABASE_URL, dépendances, schéma) et continuez à partir de la prochaine étape incomplète.

Rappels de sécurité

Rappelez aux utilisateurs d'utiliser les variables d'environnement pour les credentials, de ne jamais commiter les chaînes de connexion, et d'utiliser des rôles de base de données avec le privilège minimum.

Flux de dev basé sur les branches

Adoptez par défaut une boucle basée sur les branches qui reflète git : une branche Neon isolée par feature, pour que rien ne fuite entre les features et qu'il n'y ait aucune chaîne de connexion partagée à copier. Cette boucle est construite sur trois commandes CLI :

neonctl link — Lie interactivement l'espace de travail à une org Neon, un projet et une branche, en écrivant les IDs dans un fichier .neon ignoré par git. À exécuter une fois par projet. Une fois lié, les commandes scoped au projet et à la branche ne nécessitent plus --project-id ou --branch (par exemple, neonctl branch list).
neonctl checkout <branch-name> — Crée la branche si elle n'existe pas, ou bascule vers celle existante, en mettant à jour uniquement le pointeur de branche dans .neon. À exécuter sans nom pour un sélecteur interactif. Cela ne touche pas le code ou le Postgres local.
neonctl env pull — Récupère les variables d'environnement Neon de la branche courante dans .env.local (remplacez la cible avec --env). Pas besoin d'ID de branche ; cela lit .neon.

Lancez link une fois au démarrage sur un projet :

neonctl link

Ensuite, pour chaque feature, basculez vers une branche isolée et récupérez ses détails de connexion :

neonctl checkout dev-add-search
neonctl env pull

Développez par rapport à cette branche, puis répétez checkout + env pull pour la feature suivante. En tant qu'agent, pilotez cette boucle vous-même : lancez checkout et env pull entre les tâches pour obtenir une base de données isolée et fraîche par feature sans état partagé à corrompre.