@nodefony/drizzle 10.0.0-alpha.1

package/dist/nodefony/src/migrator/destructive.js

@@ -0,0 +1,213 @@
+//#region nodefony/src/migrator/destructive.ts
+/** Longueur au-delà de laquelle une instruction est tronquée à l'affichage. */
+const MAX_STATEMENT = 300;
+/**
+* Formes reconnues, de la plus grave à la plus bénigne.
+*
+* L'ordre compte : la première qui correspond gagne, pour qu'une instruction ne
+* soit pas signalée deux fois sous deux noms.
+*/
+const PATTERNS = [
+	{
+		kind: "drop-database",
+		severity: "data-loss",
+		re: /\bDROP\s+(DATABASE|SCHEMA)\b/i,
+		what: "supprime une base ou un schéma ENTIER — tout ce qu'il contient disparaît"
+	},
+	{
+		kind: "drop-table",
+		severity: "data-loss",
+		re: /\bDROP\s+TABLE\b/i,
+		what: "supprime une table et TOUTES ses lignes"
+	},
+	{
+		kind: "drop-column",
+		severity: "data-loss",
+		re: /\bDROP\s+COLUMN\b|\bALTER\s+TABLE\b[\s\S]*?\bDROP\s+(?!COLUMN\b|CONSTRAINT\b|INDEX\b|PRIMARY\b|FOREIGN\b|UNIQUE\b|CHECK\b|DEFAULT\b|NOT\s+NULL\b|IDENTITY\b|EXPRESSION\b)[`"']?\w+/i,
+		what: "supprime une colonne et TOUTES ses valeurs"
+	},
+	{
+		kind: "truncate",
+		severity: "data-loss",
+		re: /\bTRUNCATE\b/i,
+		what: "vide une table de toutes ses lignes"
+	},
+	{
+		kind: "delete-all",
+		severity: "data-loss",
+		re: /\bDELETE\s+FROM\b(?![\s\S]*\bWHERE\b)/i,
+		what: "supprime toutes les lignes d'une table (aucun filtre `WHERE`)"
+	},
+	{
+		kind: "alter-type",
+		severity: "breaking",
+		re: /\b(ALTER\s+COLUMN[\s\S]*\bTYPE\b|MODIFY\s+COLUMN\b|ALTER\s+COLUMN[\s\S]*\bSET\s+DATA\s+TYPE\b)/i,
+		what: "change le type d'une colonne — la conversion peut tronquer une valeur ou échouer sur les lignes existantes"
+	},
+	{
+		kind: "set-not-null",
+		severity: "breaking",
+		re: /\bSET\s+NOT\s+NULL\b/i,
+		what: "rend une colonne obligatoire — échoue si des lignes ont une valeur vide"
+	},
+	{
+		kind: "rename",
+		severity: "breaking",
+		re: /\bRENAME\s+(TABLE|COLUMN|TO)\b/i,
+		what: "renomme une table ou une colonne — le code de la version précédente ne la trouvera plus"
+	},
+	{
+		kind: "drop-constraint",
+		severity: "breaking",
+		re: /\bDROP\s+(CONSTRAINT|INDEX|PRIMARY\s+KEY|FOREIGN\s+KEY)\b/i,
+		what: "retire une garantie d'intégrité ou un index — les données restent, les protections non"
+	}
+];
+/**
+* Reconnaît la recréation de table de SQLite, et l'exclut de la perte de données.
+*
+* SQLite ne sait pas modifier une colonne : l'outil de génération produit alors
+* la ronde connue — créer `__new_x`, y recopier les lignes de `x`, supprimer
+* `x`, renommer. Ce `DROP TABLE` est **structurel**, les données ont été
+* recopiées juste avant ; le signaler comme une perte ferait crier au loup à
+* chaque changement de colonne, et le garde serait désarmé au bout de trois
+* fois.
+*
+* ⚠️ Ce n'est pas une garantie que rien n'est perdu : si une colonne
+* n'apparaît pas dans le `INSERT … SELECT`, ses données disparaissent bel et
+* bien. C'est pourquoi la recréation reste SIGNALÉE, avec le geste — lire le
+* SQL —, et seulement déclassée en avertissement.
+*/
+function isTableRebuild(statements) {
+	const joint = statements.join("\n");
+	return /\bCREATE\s+TABLE\s+[`"']?__new_/i.test(joint) && /\bINSERT\s+INTO\s+[`"']?__new_/i.test(joint);
+}
+/** Borne une instruction pour l'affichage, sans jamais la déformer. */
+function truncate(statement) {
+	const plat = statement.replace(/\s+/g, " ").trim();
+	return plat.length > MAX_STATEMENT ? `${plat.slice(0, MAX_STATEMENT)}…` : plat;
+}
+/**
+* Cherche, dans les migrations en attente, ce qui détruit ou casse.
+*
+* @param files - migrations qui vont être appliquées.
+* @returns une trouvaille par instruction reconnue, dans l'ordre d'application.
+*/
+function scanDestructive(files) {
+	const out = [];
+	for (const file of files) {
+		const rebuild = isTableRebuild(file.statements);
+		for (const statement of file.statements) for (const p of PATTERNS) {
+			if (!p.re.test(statement)) continue;
+			const structurel = rebuild && (p.kind === "drop-table" || p.kind === "rename");
+			out.push({
+				source: file.source,
+				tag: file.tag,
+				path: file.path,
+				severity: structurel ? "breaking" : p.severity,
+				kind: structurel ? "table-rebuild" : p.kind,
+				what: structurel ? "recrée la table pour modifier une colonne (SQLite ne sait pas faire autrement) — les lignes sont recopiées, MAIS une colonne absente du `INSERT … SELECT` serait perdue : lire le SQL" : p.what,
+				statement: truncate(statement)
+			});
+			break;
+		}
+	}
+	return out;
+}
+/** Les trouvailles qui font vraiment disparaître des données. */
+function dataLoss(findings) {
+	return findings.filter((f) => f.severity === "data-loss");
+}
+/**
+* Rend le bilan lisible par un humain — le fait, puis ce qu'il faut faire.
+*
+* @param findings - trouvailles à présenter.
+* @param bloquant - la commande refuse-t-elle d'appliquer ?
+* @returns le texte, sans mise en forme (l'appelant colore s'il le veut).
+*/
+function renderDestructive(findings, bloquant) {
+	let out = `${bloquant ? `Ces migrations DÉTRUISENT des données — rien n'a été appliqué.` : `Ces migrations touchent à des données existantes.`}\n\n`;
+	for (const f of findings) {
+		const marque = f.severity === "data-loss" ? "✗" : "!";
+		out += `  ${marque} ${f.source}/${f.tag} — ${f.what}\n`;
+		out += `      ${f.statement}\n`;
+	}
+	if (bloquant) out += "\nCe n'est pas un refus de principe : une fois appliquée, une suppression ne se rattrape que par une restauration de la base — c'est-à-dire une interruption de service et une décision, jamais un retour arrière.\n\nL'outil ne sauvegarde pas la base, et aucun outil de migration ne le fait : il n'en a ni les droits, ni la place, ni le temps, et le faire donnerait une assurance qui n'existe pas. La sauvegarde est le métier de l'exploitation (instantané de volume, restauration à un instant donné).\n\nLa vraie protection est de ne PAS détruire dans la même version que le code : ajoute la nouvelle forme, déploie, recopie les données, et ne supprime l'ancienne qu'à la version suivante. Le retour arrière porte alors sur le code, et la base n'a jamais besoin d'être restaurée.\n";
+	return out;
+}
+/** Les gestes proposés face à un refus destructif. */
+function destructiveActions(connector) {
+	const suffixe = connector === "default" ? "" : ` --connector ${connector}`;
+	return [`nodefony orm:migrate${suffixe} --dry-run`, `nodefony orm:migrate${suffixe} --allow-destructive`];
+}
+/** Résumé d'une ligne, pour un message ou un journal. */
+function summarizeDestructive(findings, connector) {
+	const losses = dataLoss(findings);
+	const names = [...new Set(losses.map((f) => `${f.source}/${f.tag}`))];
+	return `Le connecteur « ${connector} » a ${losses.length} instruction(s) qui SUPPRIMENT des données, dans ${names.length} migration(s) : ${names.join(", ")}.`;
+}
+/**
+* Les instructions qui touchent des lignes DÉJÀ EN BASE — sans détruire.
+*
+* Rien à voir avec {@link scanDestructive}, qui cherche ce qui fait perdre de
+* la donnée. Celles-ci sont parfaitement légitimes : ajouter une colonne à une
+* table peuplée, remplir cette colonne, changer une contrainte. Elles ont un
+* point commun qui les rend intéressantes — **après elles, quelqu'un se demande
+* si les données ont suivi**, et c'est à cet instant précis, mesuré sur le banc
+* de découvrabilité, qu'un agent a répondu « réinitialisons la base pour
+* vérifier », emportant la ligne témoin qu'il devait justement préserver.
+*
+* Un lot purement `CREATE TABLE` ne pose pas la question : il n'y avait rien
+* avant. C'est ce qui distingue un schéma initial d'une évolution.
+*/
+const ROW_TOUCHING_PATTERNS = [
+	/\bALTER\s+TABLE\b/i,
+	/\bUPDATE\s+/i,
+	/\bINSERT\s+INTO\b/i,
+	/\bDELETE\s+FROM\b/i
+];
+/**
+* Ce lot de migrations touche-t-il des lignes qui existaient déjà ?
+*
+* @param files - migrations sur le point d'être appliquées.
+* @returns vrai dès qu'une instruction modifie une table existante.
+*/
+function touchesExistingRows(files) {
+	for (const file of files) for (const statement of file.statements) if (ROW_TOUCHING_PATTERNS.some((re) => re.test(statement))) return true;
+	return false;
+}
+/**
+* Comment vérifier qu'une migration a préservé les données — **en UN geste**.
+*
+* Cette phrase existe parce que la sortie de SUCCÈS ne disait rien. Le produit
+* annonçait « ✓ 1 migration appliquée » et s'arrêtait là ; l'agent à qui l'on
+* demandait de prouver que les données avaient suivi n'avait aucun moyen sous
+* les yeux, et celui qu'il inventait — repartir d'une base vide — détruit
+* précisément ce qu'il fallait observer.
+*
+* 🔴 Elle NOMME la base, et c'est ce qui manquait au premier jet. Dire « une
+* copie de la base » sans dire laquelle laisse deviner un chemin : mesuré au
+* banc, l'agent a suivi le conseil, visé le mauvais fichier, vu son `cp`
+* échouer en silence, puis FABRIQUÉ une base au client SQL — avec une table
+* d'historique inventée. La migration a été refusée sur cette base bancale, et
+* c'est ce refus qui l'a renvoyé détruire la vraie. Le produit connaissait
+* pourtant l'emplacement : il le publie dans sa propre sortie.
+*
+* Elle nomme aussi les deux interpréteurs : « VAR=x commande » est de la
+* syntaxe POSIX, que celui de Windows refuse.
+*
+* @param connector - connecteur visé, pour composer la commande.
+* @param target - la base telle que le rapport la publie (`driver.target`),
+*   et son dialecte : on copie un FICHIER en sqlite, on exporte ailleurs.
+* @returns la phrase à rendre après une application réussie.
+*/
+function checkDataAdvice(connector, target) {
+	const suffixe = connector === "default" ? "" : ` --connector ${connector}`;
+	const sqlite = target?.dialect === "sqlite";
+	const named = target?.target ?? "<la base de ce connecteur>";
+	const copy = sqlite ? `copie le fichier « ${named} » (par exemple vers « essai.db ») — ne la RECRÉE pas à la main, l'historique du framework a ses propres colonnes` : `fabrique la copie par un export du moteur (« pg_dump » / « mysqldump ») depuis « ${named} » — ne la RECRÉE pas à la main, l'historique du framework a ses propres colonnes`;
+	const url = sqlite ? "sqlite:essai.db" : "<url de la copie>";
+	return `Ces migrations ont modifié des tables qui portaient déjà des lignes. Pour VÉRIFIER que les données ont suivi, ne repars pas d'une base vide : ce sont ces lignes-là qui sont la réponse, les effacer efface la question. Deux moyens. Compter et regarder sur place — « SELECT COUNT(*) » sur les tables touchées, et les valeurs des colonnes nouvellement remplies. Ou rejouer le même lot sur une COPIE, sans toucher à celle-ci : ${copy}, puis désigne-la par NF_MIGRATE_DATABASE_URL :\n  NF_MIGRATE_DATABASE_URL=${url} nodefony orm:migrate${suffixe}\n  (PowerShell : $env:NF_MIGRATE_DATABASE_URL = "${url}" ; nodefony orm:migrate${suffixe})`;
+}
+//#endregion
+export { checkDataAdvice, dataLoss, destructiveActions, renderDestructive, scanDestructive, summarizeDestructive, touchesExistingRows };

package/dist/nodefony/src/migrator/divergence.js

@@ -0,0 +1,84 @@
+import { verdictOf } from "./explain.js";
+import { hasGap } from "./schemaDiff.js";
+import { ormRegistry } from "@nodefony/orm-core";
+//#region nodefony/src/migrator/divergence.ts
+/** Le connecteur enregistré sait-il se comparer à ce que le code déclare ? */
+function comparable(connector) {
+	const orm = ormRegistry.get(connector);
+	return typeof orm?.compareToDeclared === "function" && typeof orm.isConnected === "function" ? orm : null;
+}
+/**
+* Ce que la base porte face à ce que le code DÉCLARE, sans condition de verdict.
+*
+* Séparé de {@link describeDivergence} parce que les deux répondent à des
+* questions différentes, et que la seconde REFUSE de répondre avant que le plan
+* soit à jour — ce qui est juste pour un rapport d'état (un écart n'a de sens
+* qu'une fois tout appliqué) et faux pour qui doit décider AVANT d'agir.
+*
+* Le cas qui a exigé cette séparation : l'adoption d'une base existante. Elle
+* doit constater l'état RÉEL avant d'écrire quoi que ce soit dans l'historique
+* — après, il est trop tard, l'affirmation est déjà gravée.
+*
+* Ne modifie jamais rien, et ne jette jamais : une base muette n'est pas une
+* divergence, c'est une panne, qui a sa propre voie de signalement.
+*
+* @param connector - nom du connecteur à interroger.
+* @returns les écarts nommés, ou `null` (rien à dire, ou rien d'interrogeable).
+*/
+async function gapAgainstDeclared(connector) {
+	const comparison = await comparisonAgainstDeclared(connector);
+	return comparison !== null && hasGap(comparison) ? comparison : null;
+}
+/**
+* La comparaison BRUTE — ce que la base porte face au code, écart ou non.
+*
+* Séparée de {@link gapAgainstDeclared}, qui ne rend que les écarts : il existe
+* une question à laquelle « aucun écart » est une réponse pleine, et non un
+* silence. Celle-ci : *la base porte-t-elle DÉJÀ les tables que je m'apprête à
+* créer ?* Une base parfaitement conforme y répond « oui », et c'est justement
+* le cas où il ne faut pas écrire un `CREATE TABLE`.
+*
+* Ne modifie jamais rien, et ne jette jamais : une base muette n'est pas une
+* conformité, c'est une absence de réponse — rendue `null` pour que personne
+* ne conclue à sa place.
+*
+* @param connector - nom du connecteur à interroger.
+* @returns la comparaison, ou `null` si rien n'était interrogeable.
+*/
+async function comparisonAgainstDeclared(connector) {
+	const orm = comparable(connector);
+	if (!orm?.isConnected()) return null;
+	try {
+		return await orm.compareToDeclared();
+	} catch {
+		return null;
+	}
+}
+/**
+* Ce qui diverge, NOMMÉ — ou `null` quand il n'y a rien à dire.
+*
+* Producteur UNIQUE de la troisième source : le verdict, la phrase française,
+* la charge utile `--json` et la sonde de disponibilité lisent tous ce même
+* retour. Rendre un booléen ici et recalculer le détail ailleurs ferait deux
+* lectures de la base pour une seule question, et deux réponses qui finiraient
+* par se contredire.
+*
+* Répond `null` sans rien interroger dans tous les cas où la réponse ne
+* changerait rien : plan déjà porteur d'un verdict, connecteur absent du
+* registre, connecteur non connecté, ORM d'une autre nature (mongoose n'a pas
+* de schéma déclaré à comparer). Répond `null` aussi quand la comparaison a eu
+* lieu et n'a rien trouvé — l'absence d'écart ne garde pas d'objet vide en
+* mémoire, et l'appelant n'a qu'un test à écrire.
+*
+* **Ne modifie jamais rien** — le rattrapage additif est le travail du mode de
+* schéma dérivé, au démarrage, et de lui seul.
+*
+* @param plan - plan calculé par l'applicateur, en lecture seule.
+* @returns les écarts nommés, ou `null` s'il n'y en a pas à publier.
+*/
+async function describeDivergence(plan) {
+	if (verdictOf(plan) !== "up-to-date") return null;
+	return gapAgainstDeclared(plan.connector);
+}
+//#endregion
+export { comparisonAgainstDeclared, describeDivergence, gapAgainstDeclared };

package/dist/nodefony/src/migrator/drivers/index.js

@@ -0,0 +1,39 @@
+import { MYSQL_LOCK_NAME_SQL, MYSQL_LOCK_PREFIX, MysqlMigrationDriver } from "./mysqlDriver.js";
+import { PG_LOCK_KEY, PostgresMigrationDriver } from "./postgresDriver.js";
+import { SqliteMigrationDriver } from "./sqliteDriver.js";
+//#region nodefony/src/migrator/drivers/index.ts
+/**
+* Ouvre le pilote à connexion unique du dialecte demandé.
+*
+* L'URL doit être une connexion **directe** au serveur : un répartiteur de
+* connexions en mode transaction casse les verrous consultatifs de session, et
+* le verrou de l'applicateur en est un.
+*
+* @param target - dialecte et coordonnées de la base.
+* @returns le pilote, déjà connecté.
+* @throws Error si les coordonnées manquent pour ce dialecte.
+*/
+async function openMigrationDriver(target) {
+	switch (target.dialect) {
+		case "sqlite": {
+			if (!target.filename) throw new Error("Migrations : le dialecte sqlite exige un `filename`. Une base en mémoire ne survivrait pas à la commande, et migrer une base jetable en rendant le code du succès est le pire des verdicts. Pour une base éphémère, passer explicitement « :memory: ».");
+			const driver = new SqliteMigrationDriver(target.filename);
+			await driver.connect();
+			return driver;
+		}
+		case "postgres": {
+			if (!target.url) throw new Error("Migrations : le dialecte postgres exige une `url` de connexion directe.");
+			const driver = new PostgresMigrationDriver(target.url);
+			await driver.connect();
+			return driver;
+		}
+		case "mysql": {
+			if (!target.url) throw new Error("Migrations : le dialecte mysql exige une `url` de connexion directe.");
+			const driver = new MysqlMigrationDriver(target.url);
+			await driver.connect();
+			return driver;
+		}
+	}
+}
+//#endregion
+export { MYSQL_LOCK_NAME_SQL, MYSQL_LOCK_PREFIX, MysqlMigrationDriver, PG_LOCK_KEY, PostgresMigrationDriver, SqliteMigrationDriver, openMigrationDriver };

package/dist/nodefony/src/migrator/drivers/mysqlDriver.js

@@ -0,0 +1,147 @@
+import { MigrationLockTimeoutError } from "../types.js";
+import { schemaReader } from "../catalog.js";
+//#region nodefony/src/migrator/drivers/mysqlDriver.ts
+/**
+* Préfixe de l'identité du verrou MySQL — **contrat inter-versions**.
+*
+* Au même titre que le nom de la table d'historique : deux versions du
+* framework qui ne s'excluent plus, c'est pendant un déploiement que ça se
+* paie.
+*/
+const MYSQL_LOCK_PREFIX = "nodefony:migrations:";
+/**
+* Expression SQL de l'identité du verrou — évaluée par le SERVEUR.
+*
+* **Pourquoi qualifier par `DATABASE()`** : `GET_LOCK` est global au SERVEUR,
+* pas à la base. Sans cette qualification, deux applications sans aucun rapport
+* hébergées sur la même instance se sérialiseraient — en silence, ce qui est le
+* pire des symptômes.
+*
+* **Pourquoi un repli haché** : MySQL borne le nom d'un verrou à 64 caractères
+* (MariaDB est plus permissif, mais c'est la contrainte la plus stricte qui
+* fait règle). Le préfixe en consomme 20 ; au-delà de 44 caractères de nom de
+* base, l'appel échouerait — et l'échec d'un verrou est un blocage total, avec
+* un message que rien ne rattache au nom de la base. Le repli reste
+* DÉTERMINISTE (fonction du seul nom de base), donc deux versions du framework
+* calculent toujours la même identité : le contrat tient.
+*/
+const MYSQL_LOCK_NAME_SQL = `IF(CHAR_LENGTH(DATABASE()) <= 44, CONCAT('${MYSQL_LOCK_PREFIX}', DATABASE()), CONCAT('${MYSQL_LOCK_PREFIX}#', LEFT(SHA2(DATABASE(), 256), 32)))`;
+/**
+* Pilote MySQL / MariaDB de l'applicateur — **une seule connexion**.
+*
+* `GET_LOCK` est un verrou de SESSION : un pool le rendrait inopérant. Il
+* s'auto-libère à la mort de la connexion — aucun verrou zombie.
+*
+* 🔴 **Le DDL n'est PAS transactionnel ici** : un `CREATE TABLE` valide
+* implicitement la transaction en cours. Un échec à mi-course laisse donc la
+* base dans un état partiel, avec un marqueur d'échec persistant — et c'est
+* exactement pourquoi il ne doit JAMAIS y avoir de reprise aveugle : c'est la
+* réparation, après inspection humaine, qui tranche.
+*/
+var MysqlMigrationDriver = class {
+	dialect = "mysql";
+	transactionalDdl = false;
+	#cxOrNull = null;
+	#locked = false;
+	#lost = null;
+	#url;
+	/**
+	* @param url - URL de connexion DIRECTE au serveur.
+	*/
+	constructor(url) {
+		this.#url = url;
+	}
+	/**
+	* Ouvre la connexion dédiée.
+	*
+	* @throws Error si le pilote `mysql2` n'est pas installé.
+	*/
+	async connect() {
+		let createConnection;
+		try {
+			const ns = await import("mysql2/promise");
+			const resolved = ns.createConnection ?? ns.default?.createConnection;
+			if (!resolved) throw new Error("`mysql2` did not expose `createConnection`");
+			createConnection = resolved;
+		} catch (e) {
+			throw new Error(`Le dialecte mysql exige le pilote optionnel \`mysql2\` (\`npm i mysql2\`). ${e.message}`, { cause: e });
+		}
+		const cx = await createConnection(this.#url);
+		cx.on("error", (error) => {
+			this.#lost = error?.message ?? String(error);
+		});
+		this.#lost = null;
+		this.#cxOrNull = cx;
+	}
+	/** Connexion ouverte, ou une erreur qui dit quoi faire. */
+	/** Motif de la perte de connexion, si elle a été constatée. */
+	get lostReason() {
+		return this.#lost;
+	}
+	get #cx() {
+		if (this.#cxOrNull === null) throw new Error(this.#lost === null ? "MysqlMigrationDriver : `connect()` n'a pas été appelé." : `MysqlMigrationDriver : connexion perdue — ${this.#lost}`);
+		return this.#cxOrNull;
+	}
+	/** @inheritdoc */
+	async exec(sql) {
+		await this.#cx.query(sql);
+	}
+	/** @inheritdoc */
+	async query(sql, params = []) {
+		const [rows] = await this.#cx.query(sql, params);
+		return Array.isArray(rows) ? rows : [];
+	}
+	/** Lecture du catalogue — implémentation PARTAGÉE avec l'ORM. */
+	#catalog = schemaReader("mysql", (sql, params) => this.query(sql, params));
+	/** @inheritdoc */
+	sameColumnName(declared, actual) {
+		return this.#catalog.sameColumnName(declared, actual);
+	}
+	/** @inheritdoc */
+	tableExists(table) {
+		return this.#catalog.tableExists(table);
+	}
+	/** @inheritdoc */
+	columnsOf(table) {
+		return this.#catalog.columnsOf(table);
+	}
+	/** @inheritdoc */
+	begin() {
+		return this.exec("START TRANSACTION");
+	}
+	/** @inheritdoc */
+	commit() {
+		return this.exec("COMMIT");
+	}
+	/** @inheritdoc */
+	rollback() {
+		return this.exec("ROLLBACK");
+	}
+	/**
+	* Prend le verrou nommé, avec le délai natif de `GET_LOCK`.
+	*
+	* @param timeoutMs - délai maximal d'attente.
+	* @throws Error si le verrou n'est pas obtenu dans le délai.
+	*/
+	async lock(timeoutMs) {
+		const seconds = Math.max(1, Math.ceil(timeoutMs / 1e3));
+		const got = (await this.query(`SELECT GET_LOCK(${MYSQL_LOCK_NAME_SQL}, ?) AS got`, [seconds]))[0]?.got;
+		if (Number(got) !== 1) throw new MigrationLockTimeoutError(timeoutMs, `Verrou de migration MySQL non obtenu en ${timeoutMs} ms (${got === null ? "erreur du serveur" : "délai dépassé"}) : une autre migration est en cours sur cette base.`);
+		this.#locked = true;
+	}
+	/** @inheritdoc */
+	async unlock() {
+		if (!this.#locked) return;
+		this.#locked = false;
+		await this.query(`SELECT RELEASE_LOCK(${MYSQL_LOCK_NAME_SQL}) AS released`);
+	}
+	/** @inheritdoc */
+	async close() {
+		const cx = this.#cxOrNull;
+		this.#cxOrNull = null;
+		this.#locked = false;
+		if (cx) await cx.end().catch(() => void 0);
+	}
+};
+//#endregion
+export { MYSQL_LOCK_NAME_SQL, MYSQL_LOCK_PREFIX, MysqlMigrationDriver };

package/dist/nodefony/src/migrator/drivers/postgresDriver.js

@@ -0,0 +1,151 @@
+import { MigrationLockTimeoutError } from "../types.js";
+import { schemaReader, toDollarParams } from "../catalog.js";
+import { createHash } from "node:crypto";
+//#region nodefony/src/migrator/drivers/postgresDriver.ts
+/**
+* Clé du verrou consultatif PostgreSQL — **figée à vie**.
+*
+* Elle est dérivée par une RÈGLE, pas choisie : les huit premiers octets de
+* `sha256("nodefony:migrations")`, lus en entier signé big-endian. Une identité
+* « gravée » dont la valeur serait tirée au hasard d'un commit ne serait pas
+* gravée du tout — on ne pourrait plus la recalculer pour la vérifier.
+*
+* La changer ferait que deux versions du framework ne s'excluent plus
+* mutuellement : exactement pendant un déploiement, le seul moment qui compte.
+*/
+const PG_LOCK_KEY = createHash("sha256").update("nodefony:migrations").digest().readBigInt64BE(0);
+/**
+* Pilote PostgreSQL de l'applicateur — **une seule connexion**, pas un pool.
+*
+* `pg_advisory_lock` est un verrou de SESSION : avec un pool, il serait pris
+* sur une connexion, le DDL exécuté sur une autre et la libération faite sur
+* une troisième — le verrou ne protégerait rien. D'où une connexion tenue du
+* verrou à sa libération.
+*
+* Le verrou s'auto-libère à la mort de la connexion : un process tué en plein
+* vol ne laisse **aucun verrou zombie** à lever à la main. C'est l'argument qui
+* a fait écarter une table de verrou.
+*/
+var PostgresMigrationDriver = class {
+	dialect = "postgres";
+	transactionalDdl = true;
+	#client = null;
+	#locked = false;
+	#lost = null;
+	#url;
+	/**
+	* @param url - URL de connexion DIRECTE au serveur.
+	*/
+	constructor(url) {
+		this.#url = url;
+	}
+	/**
+	* Ouvre la connexion dédiée.
+	*
+	* @throws Error si le pilote `pg` n'est pas installé.
+	*/
+	async connect() {
+		let ClientCtor;
+		try {
+			const ns = await import("pg");
+			const resolved = ns.Client ?? ns.default?.Client;
+			if (!resolved) throw new Error("`pg` did not expose a `Client` constructor");
+			ClientCtor = resolved;
+		} catch (e) {
+			throw new Error(`Le dialecte postgres exige le pilote optionnel \`pg\` (\`npm i pg\`). ${e.message}`, { cause: e });
+		}
+		const client = new ClientCtor({ connectionString: this.#url });
+		client.on("error", (error) => {
+			this.#lost = error?.message ?? String(error);
+		});
+		await client.connect();
+		this.#lost = null;
+		this.#client = client;
+	}
+	/** Connexion ouverte, ou une erreur qui dit quoi faire. */
+	get #cx() {
+		if (this.#client === null) throw new Error(this.#lost === null ? "PostgresMigrationDriver : `connect()` n'a pas été appelé." : `PostgresMigrationDriver : connexion perdue — ${this.#lost}`);
+		return this.#client;
+	}
+	/** Motif de la perte de connexion, si elle a été constatée. */
+	get lostReason() {
+		return this.#lost;
+	}
+	/** @inheritdoc */
+	async exec(sql) {
+		await this.#cx.query(sql);
+	}
+	/** @inheritdoc */
+	async query(sql, params = []) {
+		return (await this.#cx.query(toDollarParams(sql), params)).rows;
+	}
+	/** Lecture du catalogue — implémentation PARTAGÉE avec l'ORM. */
+	#catalog = schemaReader("postgres", (sql, params) => this.query(sql, params));
+	/** @inheritdoc */
+	sameColumnName(declared, actual) {
+		return this.#catalog.sameColumnName(declared, actual);
+	}
+	/** @inheritdoc */
+	tableExists(table) {
+		return this.#catalog.tableExists(table);
+	}
+	/** @inheritdoc */
+	columnsOf(table) {
+		return this.#catalog.columnsOf(table);
+	}
+	/** @inheritdoc */
+	begin() {
+		return this.exec("BEGIN");
+	}
+	/** @inheritdoc */
+	commit() {
+		return this.exec("COMMIT");
+	}
+	/** @inheritdoc */
+	rollback() {
+		return this.exec("ROLLBACK");
+	}
+	/**
+	* Prend le verrou consultatif, en attente BORNÉE.
+	*
+	* `pg_advisory_lock` attend sans limite : un pod bloqué derrière un job mort
+	* attendrait pour toujours, sans rien dire. On sonde donc avec
+	* `pg_try_advisory_lock` jusqu'au délai imparti, ce qui rend l'attente
+	* observable et l'échec explicite.
+	*
+	* `lock_timeout` est posé pour son VRAI rôle, distinct : borner l'attente des
+	* verrous de TABLE que prennent les `ALTER` — sans lui, un `ALTER` coincé
+	* derrière une transaction longue bloque toute la table en file d'attente.
+	*
+	* @param timeoutMs - délai maximal d'attente du verrou.
+	* @returns une promesse résolue une fois le verrou tenu.
+	* @throws Error si le verrou n'est pas obtenu dans le délai.
+	*/
+	async lock(timeoutMs) {
+		await this.exec(`SET lock_timeout = '${Math.max(1, timeoutMs)}ms'`);
+		const deadline = Date.now() + timeoutMs;
+		for (;;) {
+			if ((await this.query(`SELECT pg_try_advisory_lock(?::bigint) AS locked`, [PG_LOCK_KEY.toString()]))[0]?.locked === true) {
+				this.#locked = true;
+				return;
+			}
+			if (Date.now() >= deadline) throw new MigrationLockTimeoutError(timeoutMs, `Verrou de migration PostgreSQL non obtenu en ${timeoutMs} ms (clé ${PG_LOCK_KEY.toString()}) : une autre migration est en cours.`);
+			await new Promise((resolve) => setTimeout(resolve, 100));
+		}
+	}
+	/** @inheritdoc */
+	async unlock() {
+		if (!this.#locked) return;
+		this.#locked = false;
+		await this.query(`SELECT pg_advisory_unlock(?::bigint)`, [PG_LOCK_KEY.toString()]);
+	}
+	/** @inheritdoc */
+	async close() {
+		const client = this.#client;
+		this.#client = null;
+		this.#locked = false;
+		if (client) await client.end().catch(() => void 0);
+	}
+};
+//#endregion
+export { PG_LOCK_KEY, PostgresMigrationDriver, toDollarParams };