La base de données cachée de Prisma et le manque de correspondance des noms : un manuel d’utilisation

Deux problèmes reviennent sans cesse lorsque les équipes adoptent Prisma avec PostgreSQL : l’outil de migration propose constamment d’écraser la base de données de développement, et les tables qu’il crée ne ressemblent en rien à celles que choisirait un administrateur Postgres. Il s’agit de comportements documentés, et non de signes que Prisma est inadapté à l’environnement de production. Ce guide explique ce qui se passe dans chaque cas et vous propose un ensemble de règles simples pour préserver vos données ainsi que vos conventions de schéma.

Pourquoi prisma migrate dev propose de réinitialiser votre base de données

L’incident typique se déroule ainsi : quelqu’un exécute npx prisma migrate dev, la commande s’arrête avec une erreur indiquant qu’une table ou un enum « existe déjà », et le moyen le plus rapide pour faire disparaître ce message semble être prisma migrate reset. Cette commande supprime toutes les tables et réexécute l’ensemble de l’historique des migrations depuis zéro.

À quoi sert la base de données fantôme

Pendant le développement, Prisma Migrate utilise une deuxième base de données temporaire appelée base de données fantôme. Son unique fonction est la détection des écarts. À chaque exécution de migrate dev, Prisma crée une base de données fantôme vierge, y applique tous vos fichiers de migration, analyse le schéma résultant et le compare avec la véritable base de développement.

Lorsque ces deux bases ne correspondent pas, quelque chose a modifié la base de développement en dehors du historique des migrations. Les causes les plus fréquentes sont :

• un prisma db push qui a modifié des tables sans écrire de fichier de migration
• une modification manuelle effectuée via un client SQL
• un fichier de migration créé par un collègue mais jamais commité

Prisma ne peut pas déterminer quelle version de la base de données vous souhaitez conserver, il propose donc la seule option automatique sûre dont il dispose pour une base de développement : la supprimer et la reconstruire à partir des migrations.

Le mode de défaillance peu documenté

Ce qui prend par surprise les équipes, c’est un autre problème produisant des symptômes similaires. Sur les services Postgres gérés tels que Neon ou Supabase, l’utilisateur de la base de données indiqué dans votre chaîne de connexion ne dispose souvent pas des permissions nécessaires pour créer ou supprimer des bases de données à volonté. Prisma ne peut alors pas créer sa base de données temporaire et échoue en raison d’une erreur de permission.

Les développeurs interprètent fréquemment cette erreur comme « les migrations sont endommagées » et, suivant les conseils des forums communautaires, exécutent migrate reset pour la résoudre. C’est dangereux, car c’est précisément cet ordre qui détruit de manière fiable les données si la chaîne de connexion pointe vers un endroit réel. Les discussions publiques sur GitHub rapportent exactement cette histoire : une erreur liée à une base de données cachée, un reset non planifié en guise de « correction », et des tables perdues au milieu d’un projet.

Règles pour assurer la sécurité des migrations

• Donnez à Prisma une base de données d’ombre dédiée. Définissez shadowDatabaseUrl sur une base de données séparée où vos utilisateurs peuvent créer et supprimer des tables librement. Ne l’orientez jamais vers une base de production ou une base d’étalonnage partagée. Selon votre version de Prisma, cette configuration se trouve soit dans la section des sources de données du fichier de schéma, soit dans le fichier de configuration Prisma ; consultez donc la documentation actuelle pour savoir où votre version l’exige.
• Tenez toujours compte du fait que migrate reset est une action destructrice. Si cela est suggéré comme première étape de dépannage, arrêtez-vous et vérifiez plutôt les identifiants, les permissions ainsi que les écarts par rapport au schéma initial.
• Comprenez que la production est différente. prisma migrate deploy n’applique que les migrations en attente. Il ne crée jamais de base de données d’ombre et ne demande jamais de réinitialisation. Ce comportement de réinitialisation fait partie intégrante du flux de travail de développement par conception.

Modèles en PascalCase versus tables en snake_case

Le deuxième point de friction concerne la nomenclature. Le langage de schéma de Prisma recommande des noms de modèles en PascalCase et des noms de champs en camelCase, ce qui correspond aux conventions habituelles de JavaScript et TypeScript. Le monde Postgres attend généralement le contraire : des identifiants en snake_case, souvent avec des noms de tables au pluriel.

Avec les paramètres par défaut, un modèle nommé User contenant un champ firstName devient une table nommée User avec une colonne nommée firstName. Postgres accepte cela, mais les identifiants mélangeant majuscules et minuscules doivent être encadrés de guillemets doubles dans du SQL brut, ce qui peut sembler étranger aux DBA, aux outils de reporting et à tout service qui lit la base de données sans passer par Prisma.

Mappage des noms avec @map et @@map

Prisma résout ce problème grâce à deux attributs : @map permet de renommer la colonne d’un champ unique, tandis que @@map renomme la table associée à un modèle. Votre code TypeScript conserve user.firstName, tandis que la base de données stocke users.first_name. La mise en correspondance fonctionne bien, mais elle n’est pas appliquée automatiquement. Vous avez deux options :

• annoter manuellement chaque champ et modèle, ce qui est fastidieux mais complètement explicite et facile à vérifier
• utiliser l’outil tiers prisma-case-format CLI, qui réécrit en masse la casse des fichiers de schéma et peut être exécuté à nouveau pour empêcher que les nouveaux champs ne reviennent aux valeurs par défaut

Quelle que soit votre choix, prenez une décision avant la première migration. Renommer les tables et les colonnes ultérieurement signifie devoir écrire des migrations qui modifient les données existantes, et chaque requête SQL brute dans le code doit être adaptée en conséquence.

Comment Drizzle gère le même problème

Drizzle, l’alternative la plus notable axée sur TypeScript en premier lieu, propose une option casing qui convertit les noms de type camelCase dans le code en noms de type snake_case dans la base de données pour l’ensemble du schéma. C’est un cas rare où la logique habituelle est inversée. Prisma est généralement décrit comme l’outil le plus abstrait, tandis que Drizzle est considéré comme étant plus proche de SQL ; pourtant, le schéma basé sur le code de Drizzle facilite la gestion du casage global, alors que le langage de schéma distinct de Prisma fait que l’ajout d’une option globale reste une demande de fonctionnalité persistante à ce jour.

Points clés

• Une demande de réinitialisation issue de migrate dev indique soit un écart par rapport au schéma initial, soit un problème de permissions concernant la base de données fantôme, et non des migrations corrompues.
• Configurez une base de données fantôme explicite et isolée pour tout fournisseur Postgres hébergé.

N’utilisez jamais migrate reset comme solution générale ; les déploiements en production reposent sur migrate deploy, qui ne peut rien réinitialiser.

Sélectionnez une stratégie de nommage avec @map et @@map (manuellement ou à l’aide de prisma-case-format) avant votre première migration, et non après.

Si vous envisagez Prisma par rapport à Drizzle de manière plus générale, notre comparaison de SQL brut, Prisma et Drizzle aborde les compromis associés.

Lectures complémentaires

• MovieVault Walkthrough : une API de liste de visionnage avec Express 5, Prisma 7 et JWT — Une spécification d’exercice full-stack chronométré ainsi que son backend basé sur Express, Prisma et JWT, accompagnée de notes d’analyse concernant les vérifications de propriété, les cascades et la gestion des erreurs.
• Mise en place de Prisma 7 avec PostgreSQL dans un projet TypeScript Node.js — Correction des erreurs fréquentes de configuration de Prisma 7 en TypeScript, allant des URLs non définies ou en chaîne de caractères aux problèmes liés à rootDir, ainsi que l’intégration de PostgreSQL via l’adaptateur pg driver.