Configuration de Prisma Postgres

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

Quand appliquer cette skill

Utilisez cette skill quand :

• Vous configurez une nouvelle base de données Prisma Postgres pour un projet
• Vous créez un projet Prisma Postgres et le connectez localement
• Vous obtenez une chaîne de connexion pour Prisma Postgres
• Vous approvisionnez une base de données via l'API de gestion (et non l'interface Console)

N'utilisez pas cette skill quand :

• Vous configurez des bases de données de prévisualisation CI/CD — utilisez prisma-postgres-cicd
• Vous intégrez l'approvisionnement de bases de données multi-locataires dans une app — utilisez prisma-postgres-integrator
• Vous travaillez avec une base de données existante et déjà connectée (les tâches de schéma/migration sont standard avec Prisma CLI)

Prérequis

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

Directives UX

Quand vous présentez des choix à l'utilisateur (sélection de région, suppression de projet, etc.), utilisez le mécanisme de sélection interactif de votre plateforme (par ex. l'outil ask dans Claude Code, des prompts structurés dans d'autres agents). Ne pas afficher de tableaux statiques et demander à l'utilisateur de taper 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 à faire et comment traiter la réponse.

Étape 1 : Authentification

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

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

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

1b. Token dans l'environnement

Vérifiez PRISMA_SERVICE_TOKEN dans l'environnement ou le fichier .env.

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

Si aucun token n'est disponible, donnez cette instruction à l'utilisateur :

Créez un token de service dans Prisma Console → Workspace Settings → Service Tokens. Copiez le token et collez-le ici.

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

Une fois que vous avez un token, 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 taper manuellement un ID de région.

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

É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 endpoints poolés ou accelerate — ceux-ci sont pour les configurations Accelerate héritées 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 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. Après que l'utilisateur en ait choisi un, supprimez-le et réessayez.

Lisez references/endpoints.md pour les formes de requête/réponse complètes.

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

Si vous avez besoin d'une connexion dédiée (par ex. 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

1. Installez les dépendances :

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

Les cinq packages sont requis :

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

2. É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>"

3. Vérifiez que .gitignore inclut .env. Créez .gitignore s'il n'existe pas. Avertissez l'utilisateur si .env n'est pas gitignored.

4. Assurez-vous que package.json a "type": "module" configuré (Prisma 7 génère une sortie ESM).

5. Si prisma/schema.prisma n'existe pas, exécutez npx prisma init pour générer le projet. Cela crée à la fois prisma/schema.prisma et prisma.config.ts.

6. Assurez-vous que schema.prisma a le provider postgresql et aucune url ou directUrl dans le bloc datasource (Prisma 7 gère les URL de connexion dans prisma.config.ts, pas dans le schema) :

datasource db {
  provider = "postgresql"
}

7. Assurez-vous que prisma.config.ts charge l'URL de connexion depuis 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 sur Prisma 7 :

• Les URL de connexion vont dans prisma.config.ts, jamais dans schema.prisma
• Le provider 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 schema et le pousser

Si le schema a déjà des modèles, passez directement à la poussée. Sinon, présentez ces options comme un menu interactif :

1. « Je définirai mon schema manuellement » — Dites à l'utilisateur d'éditer prisma/schema.prisma et de revenir quand il est prêt. Attendez avant de continuer.
2. « Donnez-moi un schema de démarrage » — Ajoutez un schema de démarrage Blog (User, Post, Comment avec relations) à prisma/schema.prisma. Montrez à l'utilisateur ce qui a été ajouté et demandez-lui s'il veut l'ajuster avant de pousser.
3. « 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 ex. « Je construis un gestionnaire de tâches avec des projets, des tâches et des membres d'équipe »). Générez un schema à partir de la description, montrez-le et demandez une confirmation avant de pousser.

Une fois que le schema 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 les fichiers de migration dans prisma/migrations/ et génère le client en une seule étape. L'historique des migrations est essentiel pour les workflows CI/CD (prisma migrate deploy) et les déploiements en production.

N'utilisez npx prisma db push que si l'utilisateur demande explicitement le mode prototypage 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
• Passez { adapter } au constructeur PrismaClient
• Ne pas utiliser datasourceUrl — cette option n'existe pas dans Prisma 7
• Ne pas utiliser new PrismaClient() sans arguments — cela lancera une erreur

Après la vérification réussie, 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 IDs 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 d'erreur complète. Patterns clés d'auto-correction :

Fichiers de référence

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

references/auth.md             — Création et utilisation de token de service
references/api-basics.md       — URL de base, enveloppe, IDs, erreurs, pagination
references/endpoints.md        — Détails des endpoints pour projets, bases de données, connexions, régions
references/prisma7-client.md   — Patterns d'instanciation et d'utilisation du client Prisma 7