Aller au contenu
Meubles Morinière

Le codeQualité et livraison5 min de lecture

Migrations Prisma

Pourquoi une migration part avant le code, le seul chemin vers la base de prod et ce qu’il refuse, et comment on retire une colonne en deux temps.

Le schéma est dans packages/db/prisma/schema.prisma, et ses migrations dans packages/db/prisma/migrations/. Seul l’ERP les applique. Le site, lui, n’a qu’un rôle limité (Données). Prisma n’a pas de down. Pour défaire une migration appliquée, il faut donc une nouvelle migration ou une restauration.

L’ordre de livraison vient de deux contraintes :

  • Le build prérend des pages qui lisent la base de prod. Il faut donc que la migration passe avant la fusion sur main. Sinon, le build lirait un schéma qui n’existe pas encore.
  • L’ERP et le site se déploient chacun de leur côté, après la migration. Tant que leur nouveau build n’est pas en ligne, c’est l’ancien code qui lit la base déjà migrée.
L’ordre de livraison d’une migrationAjouter une colonne : la base passe avant le code. 1. pnpm db:pre-deploy, la migration s’applique, le reçu s’écrit. 2. git push, le hook lit le reçu, Vercel construit. 3. ERP en ligne. 4. site en ligne. Base de production : schéma N → schéma N + 1 (1). ERP en ligne : code N → code N + 1 (3). Site en ligne : code N → code N + 1 (4). l’ancien code lit la base migrée, et le build prérend sur elle : la migration ne retire rien de ce qu’il lit. Retirer une colonne : le code passe avant la base. 1. git push, le code ne lit plus la colonne. 2. ERP en ligne. 3. site en ligne. 4. pnpm db:pre-deploy --allow-destructive, la colonne part. Base de production : avec la colonne → sans (4). ERP en ligne : la lit → ne la lit plus (2). Site en ligne : la lit → ne la lit plus (3). tant qu’un build en ligne lit la colonne, elle reste : sans l’option, le script refuse la migration.Ajouter une colonne : la base passe avant le codepnpm db:pre-deployla migrations’applique, lereçu s’écritgit pushle hook lit lereçu, VercelconstruitERP en lignesite en ligneBase de productionschéma Nschéma N + 1ERP en lignecode Ncode N + 1Site en lignecode Ncode N + 1l’ancien code lit la base migrée, et le build prérend sur elle : lamigration ne retire rien de ce qu’il litRetirer une colonne : le code passe avant la basegit pushle code ne litplus la colonneERP en lignesite en lignepnpm db:pre-deploy--allow-destructivela colonne partBase de productionavec la colonnesansERP en lignela litne la lit plusSite en lignela litne la lit plustant qu’un build en ligne lit la colonne, elle reste : sans l’option, lescript refuse la migration
Schéma sans échelle. L’ERP et le site se déploient chacun de leur côté, dans un ordre qui varie. Les outils nommés (apps/erp/scripts/pre-deploy-migrate.mts, .husky/pre-push) sont vérifiés à chaque build de cette documentation.

En local

apps/erp/scripts/local-db.mts contient les commandes de développement. db:migrate, db:reset et db:check refusent toute base qui n’est pas sur la machine locale. db:deploy accepte une base distante seulement avec --remote, et jamais derrière un pooler. Il rappelle aussi qu’il ne sauvegarde rien.

db:check vide la base d’ombre locale (SHADOW_DATABASE_URL), y applique toutes les migrations avec prisma migrate deploy, puis compare cette base au schéma avec prisma migrate diff --exit-code. Si on modifie le schéma sans sa migration, ou l’inverse, il échoue, et pnpm db:check --script affiche l’écart en SQL. Il échoue aussi quand une migration ne s’applique pas à une base vide. Il passe par migrate deploy plutôt que par --from-migrations parce que la base d’ombre de Prisma n’a pas de table _prisma_migrations, et qu’une migration qui la lit n’y passe pas. Il refuse une base d’ombre qui serait celle de DATABASE_URL. Le hook pre-push le lance quand prisma/ change. Ensuite, il applique les migrations à la base locale et lance la suite Postgres (La porte du push).

Le chemin vers la prod

pnpm db:pre-deploy (apps/erp/scripts/pre-deploy-migrate.mts) est le seul moyen de migrer la prod. Chaque étape écrit une ligne JSON (predeploy.*), et --dry-run s’arrête juste avant d’appliquer.

  1. La cible se donne explicitement (--target). Le script ne la lit jamais dans l’environnement. Il refuse une cible derrière un pooler, parce que PgBouncer rejette les instructions préparées du DDL et que la migration casserait en plein milieu.
  2. Le SQL appliqué doit être celui du push. prisma/ doit être propre dans l’arbre de travail, et HEAD doit se trouver sur une branche distante (--allow-unpushed pour un essai sur une branche Neon).
  3. Le script vérifie l’historique de la base (judgeMigrationLedger, scripts/lib/migration-ledger.ts). Il refuse une migration en échec dans _prisma_migrations. Il refuse aussi une migration appliquée à la base mais absente du dossier. Dans ce cas, la branche réécrirait l’histoire, et migrate deploy rejouerait la première migration sur des tables qui existent déjà.
  4. S’il n’y a rien en attente, le script vérifie quand même les invariants et les droits du site. Sur la production, il écrit ensuite le reçu des migrations que la base porte telles que le dossier les écrit : Prisma garde le SHA-256 du fichier appliqué (_prisma_migrations.checksum). C’est la relance qui suit un réalignement des droits du site.
  5. Le SQL en attente s’affiche, migration par migration.
  6. Une migration destructive est refusée sans --allow-destructive (plus bas).
  7. Le script prend une copie de la base. Avec --sans-sauvegarde, il l’annonce clairement, et le retour arrière passe alors par la restauration à un instant donné de Neon (la décision est notée dans le script). Si la copie échoue, tout s’arrête (Sauvegardes et reprise).
  8. prisma migrate deploy applique la migration. S’il échoue, la base peut être à moitié migrée. Le script demande alors de regarder où en est la base, de résoudre ou de restaurer, et surtout de ne pas fusionner.
  9. Le script vérifie la base une nouvelle fois : plus rien en attente ni en échec, puis db:invariants.
  10. Il compare les droits du rôle du site au plan (db:role --check). S’il y a un écart, le script sort en erreur, sans reçu, et demande de les réaligner puis de le relancer.
  11. Il écrit un reçu dans le dépôt Git commun, sans identifiant ni mot de passe, seulement si la cible est la base de .env.prod-unpooled.local. Le reçu porte l’arbre git du dossier de chaque migration appliquée (apps/erp/scripts/lib/pre-deploy-receipt.ts). C’est ce reçu que lit le hook pre-push. Sur une autre base, le script le dit et n’écrit rien.

Une migration destructive se fait en deux temps

L’ancien code lit la base migrée. Donc une migration qui supprime une table, une colonne ou un type, ou qui renomme quelque chose, casserait l’application en ligne. Le script cherche ces instructions dans le SQL exécutable. Il ignore les commentaires, les chaînes et les corps de fonctions :

apps/erp/scripts/lib/destructive-migrations.ts
export type DestructiveStatement = {
	readonly migration: string;
	readonly statement: string;
};

const DESTRUCTIVE = [
	/\bDROP\s+TABLE\b/i,
	/\bDROP\s+COLUMN\b/i,
	/\bDROP\s+TYPE\b/i,
	/\bRENAME\s+(?!CONSTRAINT\b)/i,
] as const;

const HARMLESS_RENAME = /^\s*ALTER\s+INDEX\b/i;

const INERT_TEXT = /\$(\w*)\$[\s\S]*?\$\1\$|'(?:[^']|'')*'|\/\*[\s\S]*?\*\/|--[^\n]*/g;

function executableSql(sql: string): string {
	return sql.replace(INERT_TEXT, " ");
}

export function destructiveStatements(migration: string, sql: string): DestructiveStatement[] {
	return executableSql(sql)
		.split(";")
		.map((statement) => statement.replace(/\s+/g, " ").trim())
		.filter(
			(statement) =>
				statement !== "" &&
				DESTRUCTIVE.some((pattern) => pattern.test(statement)) &&
				!(HARMLESS_RENAME.test(statement) && !/\bDROP\b/i.test(statement)),
		)
		.map((statement) => ({ migration, statement }));
}

S’il en trouve, il refuse et il explique quoi faire. D’abord, on déploie le code qui ne lit plus ce qui va disparaître, ou qui lit déjà le nouveau nom. Ensuite, on relance avec --allow-destructive. Avec cette règle, le code précédent reste compatible avec la base tant que la deuxième étape n’est pas faite.

Ce que le schéma Prisma ne dit pas

Il y a des garanties qu’on ne peut pas écrire dans schema.prisma : des CHECK écrits à la main dans les migrations, des triggers, des fonctions, des séquences, des valeurs par défaut, l’initialisation des compteurs de numérotation. db:invariants (apps/erp/scripts/check-db-invariants.mts) vérifie qu’une base migrée les a toutes. Il la compare aux listes de apps/erp/scripts/constants/db-invariants.ts (EXPECTED_CHECKS, EXPECTED_TRIGGERS, EXPECTED_COUNTER_SERIES…). Il contrôle aussi le stock par rapport à son journal, et la chaîne des encaissements (Des encaissements qui ne se retouchent pas).

Les droits du rôle du site doivent suivre le schéma, et on les met à jour à la main (apps/site/scripts/lib/database-grants.ts). C’est pour ça que db:pre-deploy les compare au plan après chaque migration. J’explique pourquoi dans l’étude de cas Le site n’a que les droits qu’il lui faut.

Les outils sont testés

apps/erp/scripts/lib/__tests__ couvre la vérification de l’historique (migration-ledger.test.ts), la détection des instructions destructives (destructive-migrations.test.ts) et la lecture des invariants (db-invariants.test.ts). apps/erp/test/main-push-guard.regression.test.ts vérifie trois choses : que db:pre-deploy n’écrit son reçu qu’en dernier, après les invariants et les droits du site, et pour la production seule ; que le hook ne l’accepte que pour le contenu poussé ; et qu’il sait le lire depuis un worktree comme depuis le dépôt principal.

Sur cette page