Neon

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

Utilisez cette skill comme point de départ pour tout ce qui concerne Neon : obtenez une vue d'ensemble de ses capacités, trouvez votre chemin dans les skills et la documentation Neon, et suivez les bonnes pratiques pour bien démarrer et pour les workflows de développement branch-first.

Platform Services

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

Postgres — Postgres serverless qui scale et branch avec votre application. Généralement disponible.
Auth — Authentification gérée avec utilisateurs et sessions stockés dans Postgres. Généralement disponible.
Object Storage — Stockage d'objets compatible S3 qui branch avec vos projets. Bêta publique.
Functions — Fonctions serverless longue durée - l'offre de compute de Neon - fonctionnant près de votre base de données — pour les serveurs WebSocket, les streams HTTP longs d'agent, les APIs et les serveurs server-sent events. Bêta publique.
AI Gateway — Une API pour tous les modèles frontier et open-source, avec routage, logging et contrôles de coût, alimentée par Databricks. Bêta publique.

Disponibilité des services en bêta publique

Object Storage, Functions et AI Gateway sont en bêta publique.

L'accès aux fonctionnalités bêta n'est disponible que sur les nouveaux projets créés dans la région us-east-2 ; ils ne peuvent pas être activés 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. Si ce n'est pas le cas, il devra créer un nouveau projet dans cette région.

Architecture : comment Neon s'intègre

Neon n'est pas un endroit pour héberger votre application full-stack — ce sont des primitives de backend (Postgres, Auth, Object Storage, Functions, AI Gateway) qui se composent avec la plateforme applicative que vous utilisez déjà. Hébergez l'application sur Vercel (ou Netlify, ou un autre hôte frontend/app) ; Neon est le backend auquel elle parle.

Une configuration type :

Application full-stack sur Vercel (ou Netlify) — par exemple Next.js ou TanStack Start. Elle possède votre UI et auth (par exemple Neon Auth) et parle directement à votre base de données Neon Postgres et à Neon Object Storage.
Utilisez Neon Functions quand vous dépassez les limites de l'hôte — un serveur WebSocket ou SSE, ou des agents longue durée qui risquent de dépasser le timeout sur des serverless courts de style lambda. Exécutez cette pièce sur une Neon Function, à côté de vos données.

Vous pouvez aussi déplacer votre plan de contrôle backend complet sur Neon Functions. Ceci est particulièrement utile quand le frontend est client-only plutôt que full-stack — TanStack Router, React Router en mode client, et des SPAs similaires hébergés sur Vercel ou Netlify. Le client parle directement à Neon Functions, où vous construisez des APIs REST et des agents request/response, hébergez des serveurs MCP et exécutez n'importe quoi avec état ou qui devrait vivre près de Postgres et Object Storage. Sécurisez ces fonctions comme n'importe quelle API REST autonome — vérifiez un JWT ou une clé API au début de chaque handler (voir la skill neon-functions).

Puisque Functions sont juste votre backend, elles se composent aussi avec une application full-stack : si vous avez déjà un backend (route handlers Next.js, etc.), Neon Functions vivent à côté, et vous pouvez déplacer des morceaux entre les deux — par exemple, relocalisez un agent longue durée ou un serveur WebSocket avec état de votre hôte vers une Function quand il a besoin de plus de runtime.

Documentation Neon

La documentation Neon est la source de vérité pour toute information liée à Neon. Vérifiez toujours les affirmations par rapport aux docs officielles avant de répondre. Les features et APIs Neon évoluent, donc privilégiez la récupération des docs actuelles plutôt que de vous fier aux données d'entraînement.

Récupération des docs en Markdown

N'importe quelle page de doc 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 courte description :

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

Les URLs de doc courantes sont organisées dans les liens de thème 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

Travailler avec la base de données, les connexions, le schéma, les queries, l'autoscaling ou le CLI/MCP/API → neon-postgres.
Choisir ou créer le bon type de branche pour le dev, les previews, les tests ou les workflows CI → neon-postgres-branches.
Stocker et servir des fichiers (uploads, images, blobs) qui branchent avec la base de données → neon-object-storage.
Déployer des fonctions serverless longue durée ou streaming — APIs, agents, serveurs SSE/WebSocket — à côté de la base de données → neon-functions.
Appeler un LLM ou router entre des providers de modèles avec une seule credential — incluant la découverte des modèles servables de la branche au runtime via l'endpoint /v1/models compatible OpenAI → neon-ai-gateway.
Provisionner des bases de données Postgres temporaires instantanées et claimables (par exemple, une par utilisateur final ou démo) → claimable-postgres.
Diagnostiquer ou corriger les coûts excessifs d'egress Postgres (transfert de données réseau) dans une codebase → neon-postgres-egress-optimizer.

Installer la bonne skill

D'abord vérifiez si 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 le 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-object-storage, neon-functions ou neon-ai-gateway). Flags utiles :

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

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

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

Vous devriez aussi vous assurer que les skills sont à jour. Vous pouvez exécuter la même commande ou remplacer add par update pour mettre à jour toutes les skills Neon.

Bien démarrer 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à embarqué (par exemple, un utilisant déjà Neon Postgres).

Vérifier le statu quo

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

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

Configuration autogérée avec le 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 le CLI Neon ou le serveur MCP. Si aucun des deux n'est configuré encore, exécutez npx -y neon init. Utilisez npx -y pour sauter 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 completion avant de continuer.

npx -y neon@latest init

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

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

CLI : npm i -g neon
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>
Skill d'agent : npx skills add neondatabase/agent-skills --skill neon-postgres --skill neon --agent <agent-name> -y

Préférez le CLI au serveur MCP sauf si l'utilisateur l'indique autrement, puisqu'il fournit plus de capacités, incluant le déploiement de Neon Functions. Pour toutes les options d'installation du CLI, voir https://neon.com/docs/cli/install.md

Flux de configuration

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

Pour chaque service Neon, consultez la skill d'agent de ce composant pour les instructions de configuration spécifiques au service (Functions, Postgres, Object Storage, Gateway, etc.).

Support de reprise

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 connection strings et d'utiliser des rôles de base de données avec privilege minimum.

Flux de dev branch-first

Privilégiez par défaut une boucle branch-first qui reflète git : une branche Neon isolée par feature, ainsi rien ne fuit entre les features et il n'y a pas de connection strings partagées à copier. Deux commandes la conduisent — link une fois par projet, puis checkout par feature — et une troisième, env pull, s'exécute automatiquement en arrière-plan afin que la branche que vous épinglez soit immédiatement utilisable :

neon link — Lie interactivement le workspace à une org, un projet et une branche Neon, en écrivant les IDs dans un fichier .neon ignoré par git. Exécutez une fois par projet. Une fois lié, les commandes scoped project et branch n'ont plus besoin de --project-id ou --branch (par exemple, neon branch list).
neon checkout <branch-name> — Crée la branche si elle n'existe pas, ou la bascule si elle existe, en mettant à jour seulement le pointer de branche dans .neon. Exécutez sans nom pour un sélecteur interactif. Cela ne touche ni au code ni à Postgres local.
neon env pull — Récupère les variables d'environnement Neon de la branche actuelle (DATABASE_URL, …) dans votre .env existant, ou .env.local si vous n'en avez pas (remplacez la cible avec --file). Aucune branche ID nécessaire ; cela lit .neon. link et checkout exécutent cela pour vous par défaut, alors vous l'appelez rarement directement.

Exécutez link une fois quand vous commencez sur un projet, puis checkout par feature :

neon link                     # une fois ; récupère aussi l'env de la branche liée
neon checkout dev-add-search  # par feature ; récupère aussi l'env de la branche

Parce que link et checkout tirent l'env par défaut, le DATABASE_URL de la branche atterrit dans votre .env local automatiquement — construisez avec lui, puis checkout la branche suivante et répétez. Comme l'agent, conduisez cette boucle vous-même : exécutez checkout entre les tâches pour obtenir une base de données fraîche et isolée par feature sans état partagé pour corrompre.

Mise à jour de `.neon` sans prompts interactifs

Plain neon link / neon checkout demandent interactivement, ce qu'un agent ne peut pas répondre. Utilisez à la place l'un de ces chemins non-interactifs :

neon link --agent — une machine à états JSON pour les agents. Chaque appel retourne un seul objet JSON avec un status (needs_org → needs_project → needs_project_details → linked, ou error), les options disponibles, et le next_command_template exact à exécuter ensuite. Conduisez-le étape par étape jusqu'à status: "linked". (Les erreurs reviennent aussi en JSON avec exit code 1, donc vous pouvez toujours parser le résultat.)
neon set-context --project-id <id> --org-id <id> --branch-id <id> — quand vous connaissez déjà les IDs, écrivez les trois dans .neon en une seule fois. Ceci est une écriture destructive : elle remplace entièrement les contenus du fichier avec exactement ces champs, c'est la manière la plus directe de pointer .neon vers une org / un projet / une branche spécifique.

Les deux évitent entièrement les prompts ; attrapez set-context quand vous avez les IDs et link --agent quand vous avez besoin de les découvrir.

Opts-out des vars d'env locales

Si les vars d'env sont injectées au runtime au lieu d'être écrites sur disque — ou vous ne voulez simplement pas de secrets dans le working tree — passez --no-env-pull à link / checkout et fournissez l'env d'une autre façon :

neon-env run -- <your dev command> (depuis @neon/env) récupère les vars de la branche de votre neon.ts et les injecte dans le process enfant au runtime — aucun fichier .env nécessaire. C'est l'équivalent au runtime du env pull sur disque.
neon-env export (depuis @neon/env) imprime l'env de la branche sur stdout en tant que lignes dotenv ou, avec --format json, JSON — pour piping dans un autre gestionnaire d'env plutôt que d'exécuter une commande. Par exemple, varlock peut la bulk-charger depuis un .env.schema avec @setValuesBulk(exec("neon-env export --format json"), format=json).
fetchEnv depuis @neon/env est la version programmatique de la même chose : résolvez l'env de la branche en code au runtime au lieu de sheller out vers neon-env run.
neon dev injecte les mêmes vars dans votre serveur de dev local — c'est une partie du développement local de Neon Functions (une feature en bêta publique).

Quand un agent ne devrait pas écrire un .env local, instruisez-le (par exemple dans votre AGENTS.md) d'exécuter neon checkout <branch> --no-env-pull et de se fier à l'injection au runtime.

Pour lire l'env que vous avez déjà sur disque (typé et validé par rapport à votre neon.ts), utilisez parseEnv — voir Neon Infrastructure as Code ci-dessous.

Neon Infrastructure as Code

neon.ts est le fichier de config de branche et d'infrastructure-as-code de Neon : déclarez quels services Neon les branches de votre projet devraient avoir, obtenez des vars d'env type-safe et programmez les settings de branche — tout en TypeScript. C'est la couche de config pour Neon en tant que plateforme, et elle se compose avec la boucle branch-first ci-dessus. Ajoutez-la avec @neon/config :

npm i @neon/config

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

export default defineConfig({
  auth: true,
  dataApi: true,
});

Provisionner les services avec la config neon

Chaque projet est livré avec Postgres serverless ; neon.ts vous laisse aussi déclarer Neon Auth et la Data API dès aujourd'hui, avec Functions, buckets et l'AI Gateway sous un bloc preview — chaque service pour la branche se compose en un fichier :

// neon.ts
export default defineConfig({
  auth: true,
  dataApi: true,
  preview: {
    functions: {
      /* ... */
    }, // voir la skill neon-functions
    buckets: {
      /* ... */
    }, // voir la skill neon-object-storage
    aiGateway: true, // voir la skill neon-ai-gateway
  },
});

Réconciliez la déclaration depuis le CLI — l'équivalent Neon de terraform status / plan / apply :

neon config status   # imprimer la config live de la branche (lecture seule)
neon config plan     # dry-run diff de ce qu'apply changerait (lecture seule)
neon config apply    # provisionner les services déclarés
neon deploy          # alias pour `neon config apply`

config status et config plan ne lisent que l'état. apply / deploy — comme link et checkout — provisionnent les services déclarés et tirent alors l'env de la branche dans votre .env.local local (par ex. Pulled 5 Neon variables into .env.local: DATABASE_URL, …), donc votre env local correspond toujours à ce qui est déployé.

Vars d'env type-safe avec parseEnv

parseEnv de @neon/env prend votre objet de config neon.ts et retourne un objet env parsé et typé, validé par rapport aux services que vous avez déclarés. La forme de env suit votre config — activez auth et vous obtenez env.auth, activez dataApi et vous obtenez env.dataApi — et les variables manquantes sont signalées avec des erreurs claires (pour vous et vos agents). Utilisez-le pour lire l'env que vous avez déjà (typiquement tiré dans .env par checkout / env pull) ; pour récupérer l'env au runtime sans fichier, attrapez fetchEnv / neon-env run à la place.

npm i @neon/env

import { parseEnv } from "@neon/env";
import config from "./neon";

const env = parseEnv(config);

console.log(env.postgres.databaseUrl);
console.log(env.auth.baseUrl);

Par défaut parseEnv requiert chaque variable que votre config implique. Quand un process n'en utilise qu'un sous-ensemble — un cas courant dans les frameworks comme Next.js, où vous pourriez lire DATABASE_URL mais jamais l'URL unpooled — passez un array de clés de var d'env à requérir et retourner seulement celles-ci. Les clés sont type-safe : l'autocomplete offre seulement les variables que votre config active, et la forme retournée est restreinte à exactement ce que vous avez sélectionné (donc les variables non sélectionnées ne sont ni imposées ni présentes).

import { parseEnv } from "@neon/env";
import config from "./neon";

// Seulement DATABASE_URL est requise et retournée ; DATABASE_URL_UNPOOLED n'est pas imposée.
const { postgres } = parseEnv(config, ["DATABASE_URL"]);
console.log(postgres.databaseUrl);

// Sélection entre les services — seulement ces clés sont validées/retournées.
const env = parseEnv(config, ["DATABASE_URL", "NEON_AUTH_BASE_URL"]);
console.log(env.postgres.databaseUrl, env.auth.baseUrl);

Comment checkout se compose avec neon.ts

Quand un neon.ts est présent, neon checkout applique votre politique tel qu'elle crée une branche, donc une branche fraîche vient avec ses settings déclarés et services déjà en place. Bascule à une branche existante n'en réconcilie jamais — appliquez les changements de config à elle explicitement avec neon config apply (ou neon deploy). Le env pull inclus vérifie aussi neon.ts contre la branche liée et échoue rapidement si la branche est manquante un service déclaré, vous pointant vers neon deploy pour la provisionner, donc votre env local et la branche distante ne dérivent jamais à part en silence.

Configuration de branche

Au-delà des services, neon.ts peut programmer quelle configuration nouvelle branches reçoivent via la propriété branch — une fonction de la branche en cours d'évaluation qui retourne ses settings :

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

export default defineConfig({
  auth: true,
  dataApi: true,
  branch: (branch) => {
    if (branch.exists) {
      // laisser les branches existantes intouchées
      return {};
    }
    if (branch.name.startsWith("dev")) {
      return {
        ttl: "7d", // nettoyer la branche après 7 jours
        postgres: {
          computeSettings: {
            autoscalingLimitMinCu: 0.25, // scale to zero
            autoscalingLimitMaxCu: 1, // la garder bon marché
            suspendTimeout: "5m",
          },
        },
      };
    }
    return {};
  },
});

La fonction branch reçoit la branche cible (son name, qu'elle exists encore, qu'elle soit la default, et plus) et retourne le tuning que vous voulez. Ici les nouvelles branches dev-* obtiennent un TTL de 7 jours pour qu'elles se nettoyent elles-mêmes, plus un profil de compute bon marché scale-to-zero, tandis que les branches existantes et tout le reste passent par les defaults. Parce que neon checkout applique cette politique à la création, une branche dev-* fraîche vient avec ces settings déjà en place.

Config type-safe : les setups invalides ne compilent pas

Parce que neon.ts est TypeScript, le compilateur attrape l'infrastructure invalide avant que vous jamais déployiez — et Neon encode les règles actuelles (et leurs fixes) dans les types, donc l'erreur vous dit quoi faire plutôt que d'échouer avec un useless Type 'true' is not assignable to type 'never'. Le cas canonique : la Data API vérifie les requêtes avec Neon Auth par défaut, donc l'activer tout seul est une type error sur dataApi :

export default defineConfig({
  dataApi: true, // type error: `dataApi` (authProvider par défaut 'neon') requiert Neon Auth
});

Le message nomme les deux fixes, donc choisissez une :

// 1. Activez Neon Auth (le fournisseur d'auth Data API par défaut) :
export default defineConfig({ auth: true, dataApi: true });

// 2. Ou vérifiez un IdP tiers au lieu de Neon Auth :
export default defineConfig({
  dataApi: {
    authProvider: "external",
    jwksUrl: "https://your-idp/.well-known/jwks.json",
  },
});

Traitez une type error neon.ts comme la config vous disant quels services doivent aller ensemble — lisez le message, il épelle les combinaisons valides.

Gotchas

Neon Auth : « invalid domain »

Neon Auth redirige seulement vers les domaines de sa liste trusted-domains. À chaque fois que le domaine sur lequel votre app tourne change — un nouveau domaine custom production, une nouvelle deploy/preview URL, passer de localhost à un environnement hébergé, et ainsi de suite — vous devez enregistrer le nouveau domaine avec Neon Auth. Autrement sign-in et les callbacks OAuth échouent avec une erreur invalid domain parce que la cible de redirection n'est pas trusted.

La façon la plus facile de corriger cela est le CLI. Avec le workspace lié au projet (voir le flux branch-first ci-dessus), ajoutez le nouveau domaine à la liste trusted :

neon neon-auth domain add <domain>   # par ex. neon neon-auth domain add https://app.example.com
neon neon-auth domain list           # vérifier ce qui est actuellement trusted
neon neon-auth domain delete <domain> # supprimer un que vous n'utilisez plus

Si le workspace n'est pas lié, passez --project-id <id> (et --branch <id|name>) explicitement. Pour le développement local, neon neon-auth domain allow-localhost gère si localhost est permis. Enregistrez le domaine avant de pointer les utilisateurs vers la nouvelle URL, ainsi ils n'ont jamais l'erreur invalid domain.