Engineering choicesDécisions d’architecture(in French)4 min read
0009 · Prisma sur Neon, migrations avant le code
Le schéma Prisma est sur Neon. Les migrations passent en prod avant la fusion, et pour revenir en arrière, on restaure la base à un instant.
Not translated yet
This page is shown in its original French. Code excerpts, tests and figures read the same in either language.
Statut : acceptée, amendée le 25 octobre et le 6 novembre 2026 · Décidée : 23 août 2026 · Sources : f3b028fd30, 8a5afbd233, ancien journal (23 août 2026), 8a23651922, ceae67825b, 7e12120ae0, AGENTS.md (demande du 13 novembre 2026)
Contexte
Le schéma est né avec le dépôt (Prisma 7, f3b028fd30). Il est dans packages/db depuis le 17 octobre. Au build, les deux applications prérendent des pages qui lisent la base de prod. Et une fusion sur main déploie.
Contraintes
- Une migration doit être en place avant le code qui la lit. Sinon le build échoue, puis les pages.
- Il n’y a pas de CI pour jouer la migration (ADR 0010).
- Les contraintes, les triggers et les droits écrits en SQL échappent au modèle de Prisma (ADR 0008).
- Les fonctions serverless ouvrent beaucoup de connexions courtes.
Alternatives
- Migrer au build Vercel. On l’a étudié et écarté le 23 août : chaque build de preview aurait visé une base, ou échoué.
- Un workflow GitHub « Migrer la prod ». Il a existé, et il est parti le 6 novembre avec les GitHub Actions (
7e12120ae0). - Une sauvegarde automatique avant chaque migration ou chaque nuit. Celle de chaque nuit est partie le 6 novembre. Celle d’avant la migration est encore le comportement par défaut de
db:pre-deploy, mais depuis le 25 octobre on migre avec--sans-sauvegarde, faute de magasin des sauvegardes. - Rien ne montre qu’on a étudié un ORM plus proche du SQL, ou du SQL écrit à la main.
Décision
- Prisma 7 utilise l’adaptateur de Neon, ou celui de Postgres en dehors de Neon (
packages/infra/src/prisma-adapter.ts#createPrismaAdapter). - Les migrations se jouent depuis l’ERP, sur la prod, avant la fusion, avec
pnpm db:pre-deploy(apps/erp/scripts/pre-deploy-migrate.mts). On fait d’abord un essai, puis on applique pour de bon, avec--sans-sauvegardeet l’URL directe de la base qui est sur mon poste (.env.prod-unpooled.local). Le script vérifie aussi les invariants de la base et le rôle du site. Et le hookpre-pushrefuse une migration qui n’a pas été jouée (Migrations Prisma). - Pour revenir en arrière, on passe par la restauration à un instant de Neon. On note donc l’heure UTC avant d’appliquer. Une copie chiffrée (
pnpm db:backup) reste un geste à faire à la main (Sauvegardes et reprise).
Raisons
Confirmées
- On ne migre pas au build : « sans base de production provisionnée, la commande ferait échouer tout build de préview » (ancien journal, 23 août 2026).
- On migre sans sauvegarde : « Le retour arrière passe par la restauration à un instant de Neon » (
8a23651922, 25 octobre). La copie de nuit échouait depuis le 1er novembre parce qu’il manquait un secret, et « la sauvegarde automatique n’est pas voulue » (ceae67825b, 6 novembre). - Le geste est outillé parce que je l’ai demandé le 13 novembre 2026 : « déployer ne doit plus être une galère, et la production reste verte » (
AGENTS.md).
Hypothèses
- Prisma et Neon viennent de la stack du projet précédent, dont le dépôt a repris l’outillage (
8a5afbd233). Et Neon s’intègre à Vercel. Aucun comparatif n’est écrit.
Compromis
- Une restauration ramène toute la base à un instant. Ce qui a été écrit depuis (ventes, encaissements) est à reprendre.
- On ne peut pas revenir plus loin que la fenêtre d’historique de l’offre Neon, sauf si on a fait une copie à la main.
- Une migration jouée avant la fusion doit rester lisible par le code qui est encore en ligne. Du coup, retirer une colonne se fait en deux temps. Et
--allow-destructivene sert que quand plus aucune des deux applications ne lit ce qui disparaît (Migrations Prisma). - Le geste dépend du poste qui a l’URL de prod.
Conséquences
- Une migration part toujours avant le code qui la lit.
- Les gardes écrites en SQL sont vérifiées à chaque migration jouée en prod (
pnpm db:invariants, relancé pardb:pre-deploy). - Aucune copie ne se fait toute seule, puisqu’on migre avec
--sans-sauvegarde. Le témoin que l’ADR 0008 imagine pour une chaîne réécrite n’existe que si quelqu’un l’a fait.
Risques résiduels
- Le SQL d’une migration s’exécute pour la première fois sur les données de prod. La base locale ne les a pas, et l’essai (
--dry-run) compte les migrations sans les appliquer. Si des lignes existantes violent une contrainte,prisma migrate deployéchoue. Le script prévient alors que la base peut être à moitié migrée, et il renvoie à la restauration. - Une migration qui réécrit une table la verrouille pour les deux applications, le temps de l’écriture. Au volume d’un magasin, les tables sont petites. Mais une table qui grossit chaque jour, comme le journal du stock, finira par rendre ce verrou visible.
Quand la revoir
- Il faudrait essayer chaque migration sur une branche Neon tirée de la prod, qui est une copie instantanée de ses données. Le moment de s’y mettre, c’est dès le premier échec sur des données réelles, ou avant la première migration qui réécrit une table entière. Le script sait déjà viser une autre base que la prod (
--target, et--allow-unpushedpour un commit local). - Pour avoir une copie hors de Neon qui se fasse toute seule, l’outil est prêt (
pnpm backup:schedule). Mais la copie automatique a été écartée le 6 novembre (Dette, risques et évolutions). - Si la partie du schéma écrite à la main (triggers, contraintes, droits) devenait l’essentiel de chaque migration, on passerait à des migrations en SQL pur, en gardant Prisma comme client.