neon-postgres

Par neondatabase · agent-skills

Guides et bonnes pratiques pour travailler avec Neon Serverless Postgres. Couvre la configuration, les méthodes de connexion, le branching, l'autoscaling, le scale-to-zero, les read replicas, le connection pooling, Neon Auth, ainsi que le Neon CLI, le serveur MCP, l'API REST, le SDK TypeScript et le SDK Python. À utiliser lorsque les utilisateurs posent des questions sur « Neon setup », « connect to Neon », « Neon project », « DATABASE_URL », « serverless Postgres », « Neon CLI », « neon », « Neon MCP », « Neon Auth », « @neondatabase/serverless », « @neondatabase/neon-js », « scale to zero », « Neon autoscaling », « Neon read replica » ou « Neon connection pooling ».

npx skills add https://github.com/neondatabase/agent-skills --skill neon-postgres

Neon Serverless Postgres

Guidez l'utilisateur à travers toute tâche liée à Neon : configuration, connexions, branching, et fonctionnalités avancées. Fournissez une connexion Neon fonctionnelle, une configuration de fonctionnalité complétée, ou une réponse spécifique de la documentation officielle Neon.

Neon est une plateforme Postgres serverless qui sépare le calcul et le stockage pour offrir l'autoscaling, le branching, la restauration instantanée et le scale-to-zero. Elle est entièrement compatible avec Postgres et fonctionne avec n'importe quel langage, framework ou ORM qui supporte Postgres.

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 officiels avant de répondre. Les fonctionnalités et APIs Neon évoluent, préférez récupérer la documentation actuelle plutôt que de vous fier aux données d'entraînement.

Récupérer les docs en Markdown

N'importe quelle page de docs Neon peut être récupérée en markdown de deux façons :

  1. Ajouter .md à l'URL (plus simple) : https://neon.com/docs/introduction/branching.md
  2. Demander 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 docs 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.

Qu'est-ce que Neon

Utilisez ceci pour les explications d'architecture et la terminologie (organisations, projets, branches, endpoints) avant de donner des conseils d'implémentation.

Lien : https://neon.com/docs/introduction/architecture-overview.md

Premiers pas

Utilisez cette section pour guider un utilisateur à travers la configuration initiale de Neon.

Vérifier le statut actuel

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

  • Code de connexion à la base de données existant
  • Configuration serveur Neon MCP ou Neon CLI existante
  • Existence d'un fichier .env et d'une variable d'environnement DATABASE_URL
  • Configuration ORM existante (Prisma, Drizzle, TypeORM)

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

Proposez d'inspecter les projets Neon connectés existants ou d'en créer de nouveaux en utilisant Neon CLI ou le serveur MCP. Si aucun n'est configuré, exécutez init avec le drapeau --agent. Utilisez npx -y pour ignorer l'invite d'installation du paquet. 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 procéder.

npx -y neon@latest init --agent <agent-name>

Valeurs --agent supportées : cursor, copilot, claude, claude-desktop, codex, opencode, cline, gemini-cli, goose, zed.

Cela installe l'extension Neon (pour Cursor/VS Code) ou le serveur MCP (pour les autres agents), crée une clé API, et ajoute la skill neon-postgres agent au projet.

Si init ne convient pas, les étapes individuelles peuvent être exécutées de manière non-interactive :

  • 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 --agent <agent-name> -y

Pour les options complètes d'installation de CLI, voir https://neon.com/docs/cli/install.md

Flux de configuration

1. Sélectionner l'organisation et le projet

Utilisez le serveur MCP ou CLI pour lister les organisations et projets. Laissez l'utilisateur sélectionner un projet existant ou en créer un nouveau.

2. Obtenir la chaîne de connexion

Utilisez le serveur MCP ou CLI pour obtenir la chaîne de connexion. Stockez-la dans .env en tant que DATABASE_URL. Lisez le fichier en premier avant de le modifier pour éviter de surcharger les valeurs existantes.

3. Choisir la méthode de connexion et le driver

Consultez le guide des méthodes de connexion pour choisir le bon driver en fonction de la plateforme de déploiement : https://neon.com/docs/connect/choose-connection.md

4. Authentification utilisateur avec Neon Auth (si nécessaire)

Sautez cette étape pour les outils CLI, scripts ou applications sans comptes utilisateur. Si l'application a besoin d'authentification : utilisez l'outil serveur MCP provision_neon_auth, puis consultez la vue d'ensemble de l'authentification (https://neon.com/docs/auth/overview.md) pour la configuration. Pour l'authentification + les requêtes de base de données, voir la référence JavaScript SDK (https://neon.com/docs/reference/javascript-sdk.md).

5. Configuration ORM (optionnelle)

Vérifiez un ORM existant (Prisma, Drizzle, TypeORM). Si aucun, demandez s'ils en veulent un. Pour l'intégration Drizzle, voir https://neon.com/docs/guides/drizzle.md.

6. Configuration du schéma

  • Vérifiez les fichiers de migration existants ou les schémas ORM
  • Si aucun : proposez de créer un exemple de schéma ou d'en concevoir un ensemble

Support de reprise

En cas de reprise de configuration, vérifiez ce qui est déjà configuré (connexion MCP, .env avec DATABASE_URL, dépendances, schéma) et continuez à partir de l'étape incomplète suivante.

Rappels de sécurité

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

Méthodes de connexion et drivers

Utilisez ceci quand vous devez choisir le bon transport et driver en fonction des contraintes d'exécution (TCP, HTTP, WebSocket, edge, serverless, long-running).

Lien : https://neon.com/docs/connect/choose-connection.md

Recommandé : Drizzle + le bon driver pour votre runtime

Associez toujours Neon avec un ORM comme Drizzle pour la gestion facile du schéma et les migrations. Choisissez le driver en fonction de la façon dont le runtime traite votre code :

  • Environnements long-running ou runtime partagé → node-postgres (pg). Neon Functions et tout hôte où le runtime de la fonction est partagé entre les requêtes / s'exécute sur un calcul fluide (par ex. Vercel avec calcul fluide) gardent un processus au niveau du module vivant sur de nombreuses requêtes. Ouvrez un pool pg une fois au niveau du module et réutilisez-le à travers les requêtes.
  • Serverless entièrement isolé (style Lambda) → Neon serverless driver (@neondatabase/serverless). Des hôtes comme Netlify créent une instance fraîche et isolée par requête, donc un pool TCP persistant ne peut pas être réutilisé ; le serverless driver interroge sur HTTP et est construit pour cela.

Neon Functions / Vercel / calcul fluide — Drizzle + node-postgres :

import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import * as schema from "./schema";

// Créé une fois au niveau du module ; réutilisé par chaque requête que l'instance gère.
const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
const db = drizzle({ client: pool, schema });

Sur Vercel (calcul fluide) attachez aussi le pool avec attachDatabasePool de @vercel/functions, pour que le runtime de la fonction draine les connexions inactives avant qu'une instance se suspende :

import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import { attachDatabasePool } from "@vercel/functions";
import * as schema from "./schema";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
attachDatabasePool(pool); // laissez le runtime Vercel gérer les connexions en pool
const db = drizzle({ client: pool, schema });

Netlify et autre serverless entièrement isolé — Drizzle + Neon serverless driver :

import { drizzle } from "drizzle-orm/neon-http";
import { neon } from "@neondatabase/serverless";

const sql = neon(process.env.DATABASE_URL!);
const db = drizzle({ client: sql });

Serverless Driver

Utilisez ceci pour les modèles @neondatabase/serverless, y compris les requêtes HTTP, les transactions WebSocket, et les optimisations spécifiques au runtime.

Lien : https://neon.com/docs/serverless/serverless-driver.md

Neon JS SDK

Utilisez ceci pour les workflows combinés Neon Auth + Data API avec requêtes de style PostgREST et configuration de client typée.

Lien : https://neon.com/docs/reference/javascript-sdk.md

Outils de développement

Utilisez ceci pour l'activation du développement local avec npx -y neon@latest init --agent <agent-name>, la configuration de l'extension VSCode, et la configuration du serveur Neon MCP.

Outil URL
Commande CLI Init https://neon.com/docs/cli/init.md
Extension VSCode https://neon.com/docs/local/vscode-extension.md
Serveur MCP https://neon.com/docs/ai/neon-mcp-server.md
Neon CLI https://neon.com/docs/cli.md

Neon CLI

Utilisez ceci pour les workflows en ligne de commande, scripts, et automatisation CI/CD avec neon.

Lien : https://neon.com/docs/cli.md

Neon Admin API

L'API Neon Admin peut être utilisée pour gérer les ressources Neon de façon programmatique. Elle est utilisée en arrière-plan par Neon CLI et le serveur MCP, mais peut aussi être utilisée directement pour les workflows d'automatisation plus complexes ou lors de l'intégration de Neon dans d'autres applications.

Neon REST API

Utilisez ceci pour l'automatisation HTTP directe, le contrôle au niveau des endpoints, l'authentification par clé API, la gestion des rate limits, et le polling des opérations.

Lien : https://neon.com/docs/reference/api-reference.md

Neon TypeScript SDK

Utilisez ceci lors de l'implémentation du contrôle programmatique typé des ressources Neon en TypeScript via @neon/sdk (le successeur sans dépendances basé sur fetch à @neondatabase/api-client). Pour la surface complète de l'API — config client, le modèle de résultat { data, error }, les erreurs typées, les helpers de préparation/workflow (createAndConnect, createWithCompute), la pagination, chaque namespace de ressource, et la couche brute — voir references/neon-sdk.md.

Lien : https://neon.com/docs/reference/typescript-sdk.md

Neon Python SDK

Utilisez ceci lors de l'implémentation de la gestion programmatique de Neon en Python avec le paquet neon-api.

Lien : https://neon.com/docs/reference/python-sdk.md

Neon Auth

Utilisez ceci pour la configuration de l'authentification utilisateur gérée, les composants UI, les méthodes d'authentification, et les pièges d'intégration Neon Auth dans les applications Next.js et React.

Lien : https://neon.com/docs/auth/overview.md

Neon Auth est aussi intégré dans le Neon JS SDK. Selon votre cas d'usage, vous pouvez vouloir utiliser le Neon JS SDK au lieu de Neon Auth seul. Voir https://neon.com/docs/connect/choose-connection.md pour plus de détails.

Neon Infrastructure as Code (neon.ts)

neon.ts est le fichier de config de branche et infrastructure-as-code de Neon : déclarez quels services vos branches ont, obtenez des variables d'environnement type-safe, et programmez le calcul par branche — tout en TypeScript (voir la skill neon pour la référence complète). Postgres existe toujours sur chaque branche, donc vous ne déclarez jamais la base de données elle-même ; ce que vous codifiez ici est la surface adjacente à Postgres — Neon Auth, l'API Data, et les paramètres de calcul par branche (autoscaling et scale-to-zero).

Ajoutez-le avec @neon/config :

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

export default defineConfig({
  auth: true, // Neon Auth (ajoute les vars d'env NEON_AUTH_*)
  dataApi: true, // Data API (ajoute NEON_DATA_API_URL); nécessite auth: true (ou un IdP externe)
  // Postgres existe sur chaque branche ; ajustez son calcul par branche :
  branch: (branch) => {
    if (branch.exists) return {}; // laissez les branches existantes inchangées
    if (branch.isDefault) return { protected: true }; // la prod garde le calcul par défaut
    return {
      ttl: "7d", // les branches non-prod expirent automatiquement (max 30d)
      postgres: {
        computeSettings: {
          autoscalingLimitMinCu: 0.25, // scale à zéro
          autoscalingLimitMaxCu: 1, // gardez dev/preview bon marché
          suspendTimeout: "5m",
        },
      },
    };
  },
});

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

neon config status   # affiche la config de branche en direct
neon config plan     # dry-run diff de ce que apply changerait
neon config apply    # mettez en place les services/paramètres déclarés
neon deploy          # alias pour `neon config apply`

Parce que neon checkout applique la politique en créant une branche, une branche fraîche arrive avec ces paramètres de calcul (et Auth / Data API) déjà en place. Vérifier une branche existante n'en réconcilie jamais — exécutez neon deploy pour appliquer les changements.

Puisque neon.ts est TypeScript, les combinaisons invalides échouent à la compilation avec un message actif : l'API Data vérifie les requêtes avec Neon Auth par défaut, donc dataApi: true sans auth: true est une erreur de type (la correction — auth: true, ou authProvider: 'external' avec une jwksUrl — est dans le message). Voir la note de config type-safe de la skill neon.

Relisez les variables d'env résultantes, typées et validées selon la politique, avec parseEnv de @neon/env :

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

const env = parseEnv(config);
env.postgres.databaseUrl; // typé ; l'activation d'auth / dataApi ci-dessus expose env.auth / env.dataApi

Branching

Utilisez ceci quand l'utilisateur planifie des environnements isolés, des tests de migration de schéma, des déploiements de preview, ou une automatisation du cycle de vie des branches.

Points clés :

  • Les branches sont des clones instantanés avec copie-à-écriture (pas de copie complète de données).
  • Chaque branche a son propre endpoint de calcul.
  • Utilisez la CLI neon ou le serveur MCP pour créer, inspecter et comparer les branches.

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

Pour les workflows détaillés de création de branche (branches normales vs schema-only, reset-from-parent, sélection CLI/MCP), utilisez la skill neon-postgres-branches si disponible

Ou récupérez la skill branching complète à partir de l'URL suivante :

https://neon.com/docs/ai/skills/neon-postgres-branches/SKILL.md

Si cette skill n'est pas installée, vous pouvez utiliser la commande suivante pour l'installer :

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

Autoscaling

Utilisez ceci quand l'utilisateur a besoin que le calcul se mette à l'échelle automatiquement avec la charge de travail et veut des conseils sur le dimensionnement des CU et le comportement d'exécution.

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

Scale to Zero

Utilisez ceci lors de l'optimisation des coûts inactifs et de la discussion sur le comportement de suspension/reprise, y compris les compromis de démarrage à froid.

Points clés :

  • Les calculs inactifs se suspendent automatiquement (5 minutes par défaut, configurable) (sauf s'ils sont désactivés - plan launch & scale uniquement)
  • La première requête après suspension a généralement une pénalité de démarrage à froid (environ des centaines de ms)
  • Le stockage reste actif pendant que le calcul est suspendu.

Lien : https://neon.com/docs/introduction/scale-to-zero.md

Instant Restore

Utilisez ceci quand l'utilisateur a besoin d'une récupération à un moment précis dans le temps ou veut restaurer l'état des données sans workflows de restauration de sauvegarde traditionnels.

Points clés :

  • Les fenêtres d'historique pour la restauration instantanée dépendent des limites du plan.
  • Les utilisateurs peuvent créer des branches à partir de points dans le temps historiques.
  • Les requêtes Time Travel peuvent être utilisées pour les workflows d'inspection historique.

Lien : https://neon.com/docs/introduction/branch-restore.md

Read Replicas

Utilisez ceci pour les charges de travail lourdes en lecture où l'utilisateur a besoin d'un calcul dédié en lecture seule sans dupliquer le stockage.

Points clés :

  • Les répliques sont des endpoints de calcul en lecture seule partageant le même stockage.
  • La création est rapide et la mise à l'échelle est indépendante du calcul principal.
  • Les cas d'usage typiques : analytique, reporting, et APIs lourdes en lecture.

Lien : https://neon.com/docs/introduction/read-replicas.md

Connection Pooling

Utilisez ceci quand l'utilisateur est dans des environnements serverless ou haute concurrence et a besoin d'une gestion sûre et scalable des connexions Postgres.

Points clés :

  • Le pooling Neon utilise PgBouncer.
  • Ajoutez -pooler aux noms d'hôte des endpoints pour utiliser les connexions en pool.
  • Le pooling est particulièrement important dans les runtimes serverless avec concurrence variable.

Lien : https://neon.com/docs/connect/connection-pooling.md

IP Allow Lists

Utilisez ceci quand l'utilisateur a besoin de restreindre l'accès à la base de données par réseaux de confiance, IPs, ou plages CIDR.

Lien : https://neon.com/docs/introduction/ip-allow.md

Logical Replication

Utilisez ceci lors de l'intégration de pipelines CDC, synchronisation Postgres externe, ou mouvement de données basé sur la réplication.

Points clés :

  • Neon supporte les workflows de réplication logique natifs.
  • Utile pour la réplication vers/à partir de systèmes Postgres externes.

Lien : https://neon.com/docs/guides/logical-replication-guide.md

Skills similaires

neon-functions
neondatabase / agent-skills

Déployer et gérer des fonctions HTTP longue durée colocalisées avec une base Postgres Neon.

81
neon-functions
neondatabase / agent-skills

Déployer des fonctions Node.js longue durée directement sur une branche Neon, près de la base de données.

81
neon
neondatabase / agent-skills

Naviguer dans l'écosystème Neon pour construire des apps et agents backend serverless.

81
llm-obs-eval-bootstrap
datadog-labs / agent-skills

Générer une suite d'évaluateurs prêts à l'emploi à partir de traces LLM en production.

146
agent-observability-eval-bootstrap
datadog-labs / agent-skills

Analyser des traces LLM de production pour générer et publier une suite d'évaluateurs Datadog.

146