Configuration de Prisma Postgres

Compétence procédurale qui vous guide à travers l'approvisionnement d'une nouvelle base de données Prisma Postgres via l'API de gestion et la connexion à un projet local.

Quand appliquer

Utilisez cette compétence quand :

Configurez une nouvelle base de données Prisma Postgres pour un projet
Créez un projet Prisma Postgres et connectez-le localement
Obtenez une chaîne de connexion pour Prisma Postgres
Approvisionnez une base de données via l'API de gestion (pas l'interface utilisateur de la Console)

Ne l'utilisez pas quand :

Configurez des bases de données d'aperçu CI/CD — utilisez prisma-postgres-cicd
Intégrez l'approvisionnement multi-locataire dans une application — utilisez prisma-postgres-integrator
Travaillez avec une base de données qui existe déjà et est connectée (les tâches de schéma/migration sont un Prisma CLI standard)

Prérequis

Node.js 18+
Un espace de travail Prisma Postgres (créez-en un sur https://console.prisma.io si nécessaire)
Un jeton de service d'espace de travail (voir references/auth.md)

Directives UX

Lorsque vous présentez des choix à l'utilisateur (sélection de région, suppression de projet, etc.), utilisez le mécanisme de sélection interactive de votre plateforme (par exemple, l'outil ask dans Claude Code, des invites structurées dans d'autres agents). N'affichez pas de tableaux statiques et ne demandez pas à l'utilisateur de saisir une valeur — présentez des options sélectionnables pour que l'utilisateur puisse choisir avec un effort minimal.

Flux de travail

Suivez ces étapes dans l'ordre. Chaque étape inclut l'appel API à effectuer et comment traiter la réponse.

Étape 1 : Authentifier

Vous avez besoin d'un jeton de service. Essayez ces méthodes dans l'ordre :

1a. Jeton dans le message initial de l'utilisateur

Vérifiez si l'utilisateur a inclus un jeton de service dans son message initial (par exemple, « Configurez Prisma Postgres avec le jeton eyJ... »). Si c'est le cas, utilisez-le exactement tel que fourni — ne le tronquez pas, ne le ré-encodez pas ou ne le transmettez pas à travers un fichier. Stockez-le dans une variable shell pour les appels suivants.

1b. Jeton dans l'environnement

Vérifiez la présence de PRISMA_SERVICE_TOKEN dans l'environnement ou le fichier .env.

1c. Demander à l'utilisateur d'en créer un

Si aucun jeton n'est disponible, donnez à l'utilisateur ces instructions :

Créez un jeton de service dans Prisma Console → Paramètres de l'espace de travail → Jetons de service. Copiez le jeton et collez-le ici.

Lisez references/auth.md pour plus de détails sur la création de jetons de service.

Une fois que vous avez un jeton, stockez-le dans une variable shell (PRISMA_SERVICE_TOKEN) et utilisez-le pour tous les appels API suivants.

Étape 2 : Lister les régions disponibles

Récupérez la liste des régions Prisma Postgres disponibles pour laisser l'utilisateur choisir où déployer.

curl -s -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" \
  https://api.prisma.io/v1/regions/postgres

La réponse contient un tableau de régions avec id, name et status. Présentez uniquement les régions où status est available.

Présentez les régions comme un menu interactif — laissez l'utilisateur choisir parmi les options plutôt que de saisir manuellement un ID de région.

Lisez references/endpoints.md pour la forme complète de la réponse.

Étape 3 : Créer un projet avec une base de données

curl -s -X POST https://api.prisma.io/v1/projects \
  -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<project-name>",
    "region": "<region-id>",
    "createDatabase": true
  }'

Utilisez le nom du répertoire courant comme nom de projet par défaut.

La réponse est enveloppée dans { "data": { ... } }. Extrayez :

data.id — l'ID du projet (préfixé par proj_)
data.database.id — l'ID de la base de données (préfixé par db_)
data.database.connections[0].endpoints.direct.connectionString — la chaîne de connexion PostgreSQL directe

Utilisez la chaîne de connexion directe (endpoints.direct.connectionString). N'utilisez pas les points de terminaison groupés ou accélérés — ceux-ci sont pour les anciennes configurations Accelerate et ne sont pas nécessaires pour les nouveaux projets.

Si le statut de la réponse est provisioning, attendez quelques secondes et interrogez GET /v1/databases/<database-id> jusqu'à ce que le status soit ready.

Si la création échoue en raison d'une limite de base de données, listez les projets existants de l'utilisateur et présentez-les comme un menu interactif pour suppression. Une fois que l'utilisateur en choisit un, supprimez-le et réessayez.

Lisez references/endpoints.md pour les formes complètes des requêtes/réponses.

Étape 4 : Créer une connexion nommée (optionnel)

Si vous avez besoin d'une connexion dédiée (par exemple, par développeur ou par environnement), créez-en une :

curl -s -X POST https://api.prisma.io/v1/databases/<database-id>/connections \
  -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "dev" }'

Extrayez la chaîne de connexion directe de data.endpoints.direct.connectionString.

Étape 5 : Configurer le projet local

Installez les dépendances :

npm install prisma @prisma/client @prisma/adapter-pg pg dotenv

Les cinq paquets sont obligatoires :

prisma — CLI pour les migrations, le schéma push, la génération client
@prisma/client — le client de requête généré
@prisma/adapter-pg — adaptateur de pilote Prisma 7 pour les connexions PostgreSQL directes
pg — pilote PostgreSQL Node.js (utilisé par l'adaptateur)
dotenv — charge les variables .env pour prisma.config.ts

Écrivez la chaîne de connexion directe dans .env. Ajoutez-la au fichier s'il existe déjà — ne remplacez pas les entrées existantes :

DATABASE_URL="<direct-connection-string>"

Vérifiez que .gitignore inclut .env. Créez .gitignore s'il n'existe pas. Avertissez l'utilisateur si .env n'est pas dans gitignore.
Assurez-vous que package.json a "type": "module" défini (Prisma 7 génère une sortie ESM).
Si prisma/schema.prisma n'existe pas, exécutez npx prisma init pour scaffolder le projet. Cela crée à la fois prisma/schema.prisma et prisma.config.ts.
Assurez-vous que schema.prisma a le fournisseur postgresql et pas de url ou directUrl dans le bloc datasource (Prisma 7 gère les URL de connexion dans prisma.config.ts, pas dans le schéma) :

datasource db {
  provider = "postgresql"
}

Assurez-vous que prisma.config.ts charge l'URL de connexion de l'environnement :

import path from 'node:path'
import { defineConfig } from 'prisma/config'
import 'dotenv/config'

export default defineConfig({
  earlyAccess: true,
  schema: path.join(import.meta.dirname, 'prisma', 'schema.prisma'),
  datasource: {
    url: process.env.DATABASE_URL!,
  },
})

Notes importantes Prisma 7 :

Les URL de connexion vont dans prisma.config.ts, jamais dans schema.prisma
Le fournisseur dans schema.prisma doit être "postgresql" (pas "prismaPostgres")
dotenv/config doit être importé dans prisma.config.ts pour charger les variables .env

Étape 6 : Définir le schéma et envoyer

Si le schéma a déjà des modèles, passez à l'envoi. Sinon, présentez ces options comme un menu interactif :

« Je vais définir mon schéma manuellement » — Dites à l'utilisateur d'éditer prisma/schema.prisma et de revenir quand il est prêt. Attendez avant de continuer.
« Donnez-moi un schéma de démarrage » — Ajoutez un schéma de démarrage Blog (User, Post, Comment avec relations) à prisma/schema.prisma. Montrez à l'utilisateur ce qui a été ajouté et demandez s'il veut l'ajuster avant d'envoyer.
« Je vais décrire ce dont j'ai besoin » — Demandez à l'utilisateur de décrire son modèle de données en langage naturel (par exemple, « Je construis un gestionnaire de tâches avec des projets, des tâches et des membres d'équipe »). Générez un schéma à partir de la description, montrez-le et demandez une confirmation avant d'envoyer.

Une fois que le schéma a des modèles et que l'utilisateur est prêt, créez une migration et générez le client :

npx prisma migrate dev --name init

Cela crée des fichiers de migration dans prisma/migrations/ et génère le client en une seule étape. L'historique des migrations est essentiel pour les flux de travail CI/CD (prisma migrate deploy) et les déploiements en production.

Utilisez uniquement npx prisma db push si l'utilisateur demande explicitement un mode prototype uniquement (pas d'historique de migration). Dans ce cas, suivez-le avec npx prisma generate.

Étape 7 : Vérifier la connexion

Après la génération du client, créez et exécutez un script de vérification rapide pour confirmer que tout fonctionne de bout en bout. C'est critique — ne sautez pas cette étape.

Créez un fichier nommé test-connection.ts :

import 'dotenv/config'
import pg from 'pg'
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from './generated/prisma/client.js'

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL })
const adapter = new PrismaPg(pool)
const prisma = new PrismaClient({ adapter })

const result = await prisma.$queryRawUnsafe('SELECT 1 as connected')
console.log('Connected to Prisma Postgres:', result)

await prisma.$disconnect()
await pool.end()

Exécutez-le :

npx tsx test-connection.ts

Règles d'instanciation du client Prisma 7 :

Importez depuis ./generated/prisma/client.js (pas ./generated/prisma)
Créez un pg.Pool avec la chaîne de connexion DATABASE_URL
Enveloppez-le dans un adaptateur PrismaPg
Transmettez { adapter } au constructeur PrismaClient
N'utilisez pas datasourceUrl — cette option n'existe pas dans Prisma 7
N'utilisez pas new PrismaClient() sans arguments — cela lèvera une erreur

Après la réussite de la vérification, supprimez test-connection.ts.

Partagez ensuite des liens pour que l'utilisateur explore sa base de données :

Prisma Studio (CLI) : npx prisma studio — ouvre un navigateur de données visuel localement
Console : https://console.prisma.io/<workspaceId>/<projectId>/<databaseId>/dashboard — supprimez les préfixes (wksp_, proj_, db_) des ID retournés à l'étape 3 pour construire cette URL

Lisez references/prisma7-client.md pour la référence complète d'instanciation du client.

Gestion des erreurs

Lisez references/api-basics.md pour la référence complète des erreurs. Modèles clés d'auto-correction :

Statut HTTP	Code d'erreur	Action
401	`authentication-failed`	Le jeton de service est invalide ou expiré. Demandez à l'utilisateur d'en créer un nouveau dans Console → Paramètres de l'espace de travail → Jetons de service.
404	`resource-not-found`	Vérifiez que l'ID de ressource inclut le préfixe correct (`proj_`, `db_`, `con_`).
422	`validation-error`	Vérifiez le corps de la requête par rapport au schéma du point de terminaison. Courant : `name` manquant, `region` invalide.
429	`rate-limit-exceeded`	Attendez quelques secondes avant de réessayer.

Fichiers de référence

Des informations détaillées sur l'API et l'utilisation se trouvent dans :

references/auth.md             — Création et utilisation des jetons de service
references/api-basics.md       — URL de base, enveloppe, ID, erreurs, pagination
references/endpoints.md        — Détails des points de terminaison pour projets, bases de données, connexions, régions
references/prisma7-client.md   — Instanciation du client Prisma 7 et modèles d'utilisation