Postgres Réclamable

Des 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 sauf si elles sont réclamé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"}'

Extraire connection_string et claim_url de la réponse JSON. Écrire 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 l'utilisateur veut une configuration simple.
• SDK (neon-new/sdk) : Scripts ou provisionning programmatique en Node.js.
• Plugin Vite (vite-plugin-neon-new) : Provisionne automatiquement sur vite dev si DATABASE_URL manque. À utiliser quand l'utilisateur a un projet Vite.
• Navigateur : L'utilisateur ne peut pas exécuter CLI ou API. Rediriger vers 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 en pool. Pour une connexion directe (sans pool) (ex. migrations Prisma), supprimer -pooler du nom d'hôte. La CLI écrit automatiquement les deux URLs.

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 réclamation, 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. Toujours utiliser @latest et --yes (ignore les prompts interactifs qui pourraient bloquer l'agent).

Vérification Avant Exécution

Vérifier si DATABASE_URL (ou la clé choisie) existe déjà dans le .env cible. La CLI quitte sans provisionner si elle trouve la clé.

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

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

Obtenir confirmation avant de procéder.

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

La 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, ex. Prisma)
PUBLIC_POSTGRES_CLAIM_URL=https://neon.new/claim/...

SDK

À utiliser pour les scripts et les flux de provisionning 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. Installer avec npm install -D vite-plugin-neon-new. Voir la documentation Postgres Réclamable pour la configuration.

Workflow Agent

Chemin API

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

   psql "$DATABASE_URL" -f seed.sql

6. Rapport : Dire à l'utilisateur où la chaîne de connexion a été écrite, quelle clé a été utilisée, et partager l'URL de réclamation. Rappeler : la base de données fonctionne maintenant ; réclamer dans les 72 heures pour la conserver.
7. Optionnel : Offrir un test de connexion rapide (ex. SELECT 1).

Chemin CLI

1. Vérifier .env : Vérifier le .env cible pour un DATABASE_URL existant (ou clé choisie). S'il est présent, ne pas lancer. Offrir suppression, --env ou --key et obtenir confirmation.
2. Confirmer l'intention : Si la requête est ambiguë, confirmer que l'utilisateur veut une base de données temporaire sans inscription. Ignorer si demande explicite de base rapide ou temporaire.
3. Collecter les options : Utiliser les défauts sauf si le contexte suggère autre chose (ex. utilisateur mentionne un fichier env personnalisé, seed SQL ou réplication logique).
4. Exécuter : Lancer avec @latest --yes plus les options confirmées. Toujours utiliser @latest pour éviter les versions cachées obsolètes. --yes ignore les prompts interactifs qui bloqueraient l'agent.

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

5. Vérifier : Confirmer que la chaîne de connexion a été écrite dans le fichier voulu.
6. Rapport : Dire à l'utilisateur où la chaîne de connexion a été écrite, quelle clé a été utilisée, et qu'une URL de réclamation est dans le fichier env. Rappeler : la base de données fonctionne maintenant ; réclamer dans les 72 heures pour la conserver.
7. Optionnel : Offrir un test de connexion rapide (ex. SELECT 1).

Checklist de Sortie

Toujours rapporter :

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

Réclamation

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

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

Les utilisateurs ne peuvent pas réclamer dans les orgs liés à Vercel ; ils doivent choisir une autre org Neon.

Défauts et Limites

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

Provisionning Automatique

Si l'agent a besoin d'une base de données pour accomplir une tâche (ex. « construis-moi une app todo avec une vraie base de données ») et l'utilisateur n'a pas fourni de chaîne de connexion, provisionner une via l'API et informer l'utilisateur. Inclure l'URL de réclamation pour qu'il puisse la conserver.

Notes de Sécurité et UX

• Ne pas écraser les variables env existantes. Vérifier d'abord, puis utiliser --env ou --key (CLI) ou ignorer l'écriture (API) pour éviter les conflits.
• Demander avant d'exécuter un seed SQL destructeur (DROP, TRUNCATE, DELETE en masse).
• Pour les charges de travail en production, recommander le provisionning Neon standard plutôt que les bases de données temporaires réclamables.
• Si les utilisateurs ont besoin de persistance long terme, les instruire d'ouvrir l'URL de réclamation immédiatement.
• Après écriture des identifiants dans un fichier .env, vérifier qu'il est couvert par .gitignore. Sinon, avertir l'utilisateur. Ne pas modifier .gitignore sans confirmation.