Postgres Revendicable

Bases de données Postgres instantanées pour le développement local, les démos, le prototypage et les environnements de test. Aucun compte requis. Les bases de données expirent après 72 heures à moins d'être revendiquées sur un compte Neon.

Démarrage rapide

curl -s -X POST "https://neon.new/api/v1/database" \
  -H "Content-Type: application/json" \
  -d '{"ref": "agent-skills"}'

Analysez connection_string et claim_url à partir de la réponse JSON. Écrivez connection_string dans le .env du projet en tant que DATABASE_URL.

Pour d'autres méthodes (CLI, SDK, plugin Vite), voir Quelle méthode ? ci-dessous.

Quelle méthode ?

• REST API : Retourne du JSON structuré. Aucune dépendance runtime au-delà de curl. Préféré quand l'agent a besoin d'une sortie prévisible et d'une gestion d'erreurs.
• CLI (npx neon-new@latest --yes) : Provisionne et écrit .env en une seule commande. Pratique quand Node.js est disponible et que l'utilisateur veut une configuration simple.
• SDK (neon-new/sdk) : Scripts ou provisioning programmatique en Node.js.
• Plugin Vite (vite-plugin-neon-new) : Provisionne automatiquement sur vite dev si DATABASE_URL est manquant. À utiliser quand l'utilisateur a un projet Vite.
• Navigateur : L'utilisateur ne peut pas exécuter CLI ou API. Direction https://neon.new.

REST API

URL de base : https://neon.new/api/v1

Créer une base de données

curl -s -X POST "https://neon.new/api/v1/database" \
  -H "Content-Type: application/json" \
  -d '{"ref": "agent-skills"}'

La connection_string retournée par l'API est une URL de connexion avec pooling. Pour une connexion directe (sans pooling) (p. ex. migrations Prisma), supprimez -pooler du nom d'hôte. Le CLI écrit automatiquement les deux URLs pooled et directe.

Réponse :

{
  "id": "019beb39-37fb-709d-87ac-7ad6198b89f7",
  "status": "UNCLAIMED",
  "neon_project_id": "gentle-scene-06438508",
  "connection_string": "postgresql://...",
  "claim_url": "https://neon.new/claim/019beb39-...",
  "expires_at": "2026-01-26T14:19:14.580Z",
  "created_at": "2026-01-23T14:19:14.580Z",
  "updated_at": "2026-01-23T14:19:14.580Z"
}

Vérifier le statut

curl -s "https://neon.new/api/v1/database/{id}"

Retourne la même forme de réponse. Transitions de statut : UNCLAIMED -> CLAIMING -> CLAIMED. Après que la base de données soit revendiquée, connection_string retourne null.

Réponses d'erreur

CLI

npx neon-new@latest --yes

Provisionne une base de données et écrit la chaîne de connexion dans .env en une seule étape. Utilisez toujours @latest et --yes (ignore les invites interactives qui bloqueraient l'agent).

Vérification avant exécution

Vérifiez si DATABASE_URL (ou la clé choisie) existe déjà dans le .env cible. Le CLI se termine sans provisioning s'il trouve la clé.

Si la clé existe, offrez à l'utilisateur trois options :

1. Supprimer ou commenter la ligne existante, puis relancer.
2. Utiliser --env pour écrire dans un fichier différent (p. ex. --env .env.local).
3. Utiliser --key pour écrire sous un nom de variable différent.

Obtenez une confirmation avant de continuer.

Options

Gestionnaires de paquets alternatifs : yarn dlx neon-new@latest, pnpm dlx neon-new@latest, bunx neon-new@latest, deno run -A neon-new@latest.

Sortie

Le CLI écrit dans le .env cible :

DATABASE_URL=postgresql://...              # pooled (utiliser pour les requêtes d'application)
DATABASE_URL_DIRECT=postgresql://...       # direct (utiliser pour les migrations, p. ex. Prisma)
PUBLIC_POSTGRES_CLAIM_URL=https://neon.new/claim/...

SDK

À utiliser pour les scripts et les flux de provisioning programmatique.

import { instantPostgres } from "neon-new";

const { databaseUrl, databaseUrlDirect, claimUrl, claimExpiresAt } =
  await instantPostgres({
    referrer: "agent-skills",
    seed: { type: "sql-script", path: "./init.sql" },
  });

Retourne databaseUrl (pooled), databaseUrlDirect (direct, pour les migrations), claimUrl et claimExpiresAt (objet Date). Le paramètre referrer est obligatoire.

Plugin Vite

Pour les projets Vite, vite-plugin-neon-new provisionne automatiquement une base de données sur vite dev si DATABASE_URL manque. Installez avec npm install -D vite-plugin-neon-new. Voir la documentation Postgres Revendicable pour la configuration.

Flux de travail agent

Chemin API

1. Confirmer l'intention : Si la demande est ambiguë, confirmez que l'utilisateur veut une base de données temporaire sans inscription. Ignorez cette étape s'il a explicitement demandé une base de données rapide ou temporaire.
2. Provisionner : POST vers https://neon.new/api/v1/database avec {"ref": "agent-skills"}.
3. Analyser la réponse : Extrayez connection_string, claim_url et expires_at de la réponse JSON.
4. Écrire .env : Écrivez DATABASE_URL=<connection_string> dans le .env du projet (ou le fichier et la clé préférés de l'utilisateur). Ne réécrivez pas une clé existante sans confirmation.
5. Seed (si nécessaire) : Si l'utilisateur a un fichier SQL de seed, exécutez-le contre la nouvelle base de données :

   psql "$DATABASE_URL" -f seed.sql

6. Rapport : Dites à l'utilisateur où la chaîne de connexion a été écrite, quelle clé a été utilisée et partagez l'URL de revendication. Rappelez-leur : la base de données fonctionne maintenant ; revendiquez-la dans les 72 heures pour la conserver définitivement.
7. Optionnel : Offrez un test de connexion rapide (p. ex. SELECT 1).

Chemin CLI

1. Vérifier .env : Vérifiez le .env cible pour une DATABASE_URL existante (ou clé choisie). Si présente, ne l'exécutez pas. Offrez remove, --env ou --key et obtenez une confirmation.
2. Confirmer l'intention : Si la demande est ambiguë, confirmez que l'utilisateur veut une base de données temporaire sans inscription. Ignorez cette étape s'il a explicitement demandé une base de données rapide ou temporaire.
3. Rassembler les options : Utilisez les défauts à moins que le contexte ne suggère le contraire (p. ex., l'utilisateur mentionne un fichier d'env personnalisé, du SQL seed ou la réplication logique).
4. Exécuter : Exécutez avec @latest --yes plus les options confirmées. Utilisez toujours @latest pour éviter les versions cached obsolètes. --yes ignore les invites interactives qui bloqueraient l'agent.

   npx neon-new@latest --yes --ref agent-skills --env .env.local --seed ./schema.sql

5. Vérifier : Confirmez que la chaîne de connexion a été écrite dans le fichier prévu.
6. Rapport : Dites à l'utilisateur où la chaîne de connexion a été écrite, quelle clé a été utilisée et qu'une URL de revendication se trouve dans le fichier env. Rappelez-leur : la base de données fonctionne maintenant ; revendiquez-la dans les 72 heures pour la conserver définitivement.
7. Optionnel : Offrez un test de connexion rapide (p. ex. SELECT 1).

Liste de vérification de la sortie

Signalez toujours :

• Où la chaîne de connexion a été écrite (p. ex. .env)
• Quelle clé de variable a été utilisée (DATABASE_URL ou clé personnalisée)
• L'URL de revendication (depuis .env ou la réponse API)
• Que les bases de données non revendiquées sont temporaires (72 heures)

Revendication

La revendication est optionnelle. La base de données fonctionne immédiatement sans elle. Pour revendiquer optionnellement, l'utilisateur ouvre l'URL de revendication dans un navigateur, où il se connecte ou crée un compte Neon pour revendiquer la base de données.

• API/SDK : Donnez à l'utilisateur la claim_url de la réponse create.
• CLI : npx neon-new@latest claim lit l'URL de revendication depuis .env et ouvre le navigateur automatiquement.

Les utilisateurs ne peuvent pas revendiquer dans les organisations liées à Vercel ; ils doivent choisir une autre organisation Neon.

Neon Infrastructure as Code (neon.ts)

Les bases de données revendicables sont délibérément jetables et provisionnées via neon.new (ci-dessus), elles ne sont donc pas gérées par neon.ts. Une fois qu'un utilisateur revendique une base de données dans un compte Neon, elle devient un projet Neon normal — à ce moment-là, neon.ts, le fichier infrastructure-as-code de Neon, est comment vous la gérez à partir de ce moment (voir la compétence neon pour la référence complète) : déclarez les services que ses branches doivent avoir, programmez le compute par branche et obtenez des variables d'env type-safe.

npm i @neon/config

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

export default defineConfig({
  auth: true, // Neon Auth, une fois que vous surpassez une simple chaîne de connexion
  dataApi: true, // Data API
  branch: (branch) => (branch.exists ? {} : { ttl: "7d" }), // branches non-défaut éphémères
});

neon config apply   # provisionner les services déclarés (neon deploy est un alias)

Si un projet a besoin de branching, de services multiples ou d'une infrastructure durable tracée dans le contrôle de version, recommandez de revendiquer d'abord puis d'adopter neon.ts — plutôt que de reprovisionner des bases de données revendicables jetables.

Défauts et limites

La région ne peut pas être changée pour les bases de données revendicables. Les bases de données non revendiquées ont des quotas plus stricts. La revendication réinitialise les limites aux défauts du plan gratuit.

Provisioning automatique

Si l'agent a besoin d'une base de données pour accomplir une tâche (p. ex. « construis-moi une application todo avec une vraie base de données ») et que l'utilisateur n'a pas fourni de chaîne de connexion, provisionnez-en une via l'API et informez l'utilisateur. Incluez l'URL de revendication pour qu'il puisse la conserver.

Notes de sécurité et UX

• Ne réécrivez pas les variables d'env existantes. Vérifiez d'abord, puis utilisez --env ou --key (CLI) ou ignorez l'écriture (API) pour éviter les conflits.
• Demandez avant d'exécuter du SQL destructeur (DROP, TRUNCATE, DELETE en masse).
• Pour les charges de travail en production, recommandez le provisioning Neon standard au lieu de bases de données revendicables temporaires.
• Si les utilisateurs ont besoin de persistance à long terme, instruisez-les d'ouvrir l'URL de revendication immédiatement.
• Après avoir écrit les identifiants dans un fichier .env, vérifiez qu'il est couvert par .gitignore. Si non, avertissez l'utilisateur. Ne modifiez pas .gitignore sans confirmation.