@nodefony/drizzle 10.0.0-beta.1 → 10.0.0-beta.2

package/README.md

@@ -4,14 +4,15 @@ Adapter [Drizzle ORM](https://orm.drizzle.team/) pour Nodefony, branché sur
 [`@nodefony/orm-core`](https://www.npmjs.com/package/@nodefony/orm-core). driver concret du socle multi-ORM (avec
 `@nodefony/mongoose`), **type-safe-first**.
 
-> Driver de référence : `better-sqlite3` (tests, embarqué). Pour Postgres/MySQL,
+> Driver SQLite : `better-sqlite3` (dépendance de pair optionnelle, à installer avec le dialecte
+> `sqlite`). Pour Postgres/MySQL,
 > changer le client et le constructeur de table (`pgTable`/`mysqlTable`) — le
 > contrat `IRepository` reste identique.
 
 ## Installation
 
 ```bash
-npm install @nodefony/drizzle@alpha drizzle-orm better-sqlite3
+npm install @nodefony/drizzle@beta drizzle-orm better-sqlite3
 ```
 
 ## Utilisation comme module Nodefony (bootable)
@@ -43,8 +44,8 @@ l'override générique `NF__DRIZZLE__<CHEMIN>`. Sans `filename`, un connecteur S
 Au runtime, l'ORM est récupérable via le registre :
 
 ```typescript
-import { OrmRegistry } from "@nodefony/orm-core";
-const orm = OrmRegistry.get("default");
+import { ormRegistry } from "@nodefony/orm-core";
+const orm = ormRegistry.get("default");
 const users = orm.getRepository("User");
 ```
 
@@ -83,7 +84,7 @@ const users = orm.getRepository<{ id: string; email: string; age: number }>(
 const u = await users.create({ email: "a@b.c", age: 30 });
 await users.findOne({ id: u.id });
 await users.find(); // tous
-await users.update({ id: u.id }, { age: 31 });
+await users.updateOne({ id: u.id }, { age: 31 });
 await users.delete({ id: u.id });
 await users.count();
 ```
@@ -101,7 +102,8 @@ await users.find({ age: { $ne: 30 } });
 await users.find({ email: { $like: "u2%" } }); // sémantique SQL (`%`, `_`)
 ```
 
-Opérateurs supportés : `$eq $ne $gt $gte $lt $lte $in $nin $like`. Une valeur nue
+Opérateurs supportés : `$eq $ne $gt $gte $lt $lte $in $nin $like $null`, et `$or` pour une
+disjonction. Une valeur nue
 (`{ email: "a@b.c" }`) = égalité.
 
 ## Relations & eager-load
@@ -153,7 +155,7 @@ const rows = db.all(sql`SELECT ... JOIN ...`);
 ## Notes
 
 - **Dev/test** : le schéma SQLite est créé automatiquement (DDL dérivé des tables).
-  **Production** : utiliser `drizzle-kit` pour les migrations.
+  **Production** : `nodefony orm:generate` puis `nodefony orm:migrate` (voir `docs/migrations.md`).
 - `better-sqlite3` est **synchrone** : les transactions sont pilotées manuellement
   (`BEGIN`/`COMMIT`/`ROLLBACK`) pour rester compatibles avec le contrat async.
 

package/dist/_virtual/{_@oxc-project_runtime@0.151.0 → _@oxc-project_runtime@0.152.0}/helpers/esm/decorate.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.151.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.152.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);

package/dist/_virtual/{_@oxc-project_runtime@0.151.0 → _@oxc-project_runtime@0.152.0}/helpers/esm/decorateMetadata.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.151.0/helpers/esm/decorateMetadata.js
+//#region \0@oxc-project+runtime@0.152.0/helpers/esm/decorateMetadata.js
 function __decorateMetadata(k, v) {
 	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }

package/dist/index.js

@@ -38,8 +38,8 @@ import OrmMigrateStatus from "./nodefony/command/orm-migrate-status.js";
 import OrmMigrateBaseline from "./nodefony/command/orm-migrate-baseline.js";
 import OrmMigrateRepair from "./nodefony/command/orm-migrate-repair.js";
 import OrmReset from "./nodefony/command/orm-reset.js";
-import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.151.0/helpers/esm/decorateMetadata.js";
-import __decorate from "./_virtual/_@oxc-project_runtime@0.151.0/helpers/esm/decorate.js";
+import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
+import __decorate from "./_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
 import SessionStorage from "./nodefony/src/SessionStorage.js";
 import "./nodefony/src/migrator/index.js";
 import { DrizzleUserRepository } from "./nodefony/src/DrizzleUserRepository.js";

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

@@ -1,6 +1,7 @@
 import { HISTORY_TABLE } from "../types.js";
 import { schemaReader } from "../catalog.js";
 import "../../memoryDatabase.js";
+import { enableWriteAheadLog } from "../../sqliteJournal.js";
 //#region nodefony/src/migrator/drivers/sqliteDriver.ts
 /**
 * Pilote SQLite de l'applicateur — connexion `better-sqlite3` dédiée.
@@ -53,9 +54,11 @@ var SqliteMigrationDriver = class {
 			throw new Error(`Le dialecte sqlite exige le pilote optionnel \`better-sqlite3\` (\`npm i better-sqlite3\`). ${e.message}`, { cause: e });
 		}
 		const db = new Sqlite(this.#filename);
-		if (this.#filename !== ":memory:") {
-			db.pragma("journal_mode = WAL");
-			db.pragma("synchronous = NORMAL");
+		if (this.#filename !== ":memory:") try {
+			await enableWriteAheadLog(db);
+		} catch (e) {
+			db.close();
+			throw e;
 		}
 		this.#database = db;
 	}

package/dist/nodefony/src/orm-core/DrizzleOrm.js

@@ -1,5 +1,6 @@
 import { schemaReader, toDollarParams } from "../migrator/catalog.js";
 import "../memoryDatabase.js";
+import { enableWriteAheadLog } from "../sqliteJournal.js";
 import { notConfigured } from "../migrator/refusals.js";
 import { additiveSql, compareSchema, hasGap } from "../migrator/schemaDiff.js";
 import { describeTargetSafely } from "../safeTarget.js";
@@ -475,9 +476,11 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 			throw new Error(`DrizzleOrm "${this.name}": the sqlite dialect needs the optional driver \`better-sqlite3\` (run \`npm i better-sqlite3\`). ` + e.message, { cause: e });
 		}
 		const client = new Sqlite(this.#filename);
-		if (this.#filename !== ":memory:") {
-			client.pragma("journal_mode = WAL");
-			client.pragma("synchronous = NORMAL");
+		if (this.#filename !== ":memory:") try {
+			await enableWriteAheadLog(client);
+		} catch (e) {
+			client.close();
+			throw e;
 		}
 		client.pragma("foreign_keys = ON");
 		this.#client = client;

package/dist/nodefony/src/orm-core/DrizzleRepository.js

@@ -24,6 +24,25 @@ const PREPARED_CACHE_MAX = 128;
 /** Séquence des noms de prepared statements (PG les exige uniques par process). */
 let preparedNameSeq = 0;
 /**
+* Les comparaisons scalaires, dans l'ordre où elles entrent dans le `WHERE`.
+*
+* UNE table pour le chemin direct (`#pushOperators`) ET le chemin préparé
+* (`#buildPreparedSelect`) : deux listes recopiées finiraient par traduire le
+* même critère en deux SQL différents, selon que la forme est en cache ou non.
+* Leur texte SQL ne dépend que de l'opérateur, jamais de la valeur — c'est ce
+* qui les rend préparables (≠ `$in`/`$nin`, dont le SQL suit la cardinalité).
+*/
+const COMPARISONS = [
+	["$eq", eq],
+	["$ne", ne],
+	["$gt", gt],
+	["$gte", gte],
+	["$lt", lt],
+	["$lte", lte]
+];
+/** Opérateurs qu'une forme préparée sait rendre : les comparaisons et `$null`. */
+const PREPARABLE_OPERATORS = /* @__PURE__ */ new Set([...COMPARISONS.map(([op]) => op), "$null"]);
+/**
 * Repository portable (contrat {@link IRepository}) au-dessus d'une table Drizzle
 * + driver `better-sqlite3`.
 *
@@ -83,9 +102,18 @@ var DrizzleRepository = class DrizzleRepository {
 		this.#dialect = dialect;
 		this.#transactional = transactional;
 	}
-	/** Colonne Drizzle d'une table par nom logique ; `undefined` si elle n'existe pas. */
+	/**
+	* Colonne Drizzle d'une table par nom logique ; `undefined` si elle n'existe pas.
+	*
+	* 🔴 `Object.hasOwn` sur l'objet des COLONNES, jamais `table[name]` : le nom
+	* vient souvent de la requête (`?sort=`), et une clé héritée du prototype
+	* (`constructor`, `__proto__`, `toString`) ne vaut pas `undefined` — elle
+	* franchissait la liste blanche et cassait plus loin dans le pilote.
+	* `getTableColumns` rend l'objet tel quel, sans copie.
+	*/
 	#col(table, name) {
-		return table[name];
+		const columns = getTableColumns(table);
+		return Object.hasOwn(columns, name) ? columns[name] : void 0;
 	}
 	/**
 	* Colonne EXIGÉE : un nom inconnu lève au lieu de partir dans le SQL.
@@ -138,9 +166,21 @@ var DrizzleRepository = class DrizzleRepository {
 	*
 	* Fallback sans PK déclarée : `rowid` (SQLite-only — toutes les entités
 	* framework ont une PK ; une table d'app sans PK est un cas sqlite assumé).
+	*
+	* Court-circuit : un critère qui fixe TOUTES les colonnes de la PK par une
+	* égalité désigne déjà au plus une ligne — le `WHERE` nu suffit, et la
+	* sous-requête n'est plus payée. Elle coûtait ~60 µs par UPDATE en SQLite
+	* (recompilation d'un SQL plus long + table dérivée matérialisée, mesuré par
+	* `scripts/micro/micro-update-pick.mjs` du skill `nodefony-load-test`), soit
+	* l'essentiel de l'écart du banc ORM face à NestJS (#510).
+	*
+	* @param criteria - critère portable de la mutation.
+	* @returns le prédicat qui borne la mutation à au plus une ligne.
 	*/
-	#pickOne(where) {
+	#pickOne(criteria) {
+		const where = this.#where(criteria);
 		const pk = this.#pkColumns();
+		if (where && pk && this.#pinsPrimaryKey(pk, criteria)) return where;
 		if (!pk) return where ? sql`rowid in (select rowid from ${this.#table} where ${where} limit 1)` : sql`rowid in (select rowid from ${this.#table} limit 1)`;
 		const qualified = sql.join(pk, sql.raw(", "));
 		const inner = where ? sql`select ${qualified} from ${this.#table} where ${where} limit 1` : sql`select ${qualified} from ${this.#table} limit 1`;
@@ -150,6 +190,25 @@ var DrizzleRepository = class DrizzleRepository {
 		return sql`${target} in (select ${output} from (${inner}) as picked)`;
 	}
 	/**
+	* Vrai si le critère fixe chaque colonne de la PK par une égalité à une
+	* valeur (ni `null`, ni opérateur, ni branche de `$or`) — l'unicité de la
+	* PK garantit alors « au plus une ligne » sans sous-requête.
+	*
+	* @param pk - colonnes de la PK (au plus 31 : masque de bits).
+	* @param criteria - critère portable de la mutation.
+	*/
+	#pinsPrimaryKey(pk, criteria) {
+		if (criteria === void 0 || pk.length > 31) return false;
+		let pinned = 0;
+		for (const [field, value] of Object.entries(criteria)) {
+			if (field === "$or" || value === null || value === void 0 || isFieldOperators(value)) continue;
+			const col = this.#col(this.#table, field);
+			const i = col === void 0 ? -1 : pk.indexOf(col);
+			if (i !== -1) pinned |= 1 << i;
+		}
+		return pinned === (1 << pk.length) - 1;
+	}
+	/**
 	* Lignes affectées, normalisé par driver : better-sqlite3 `{changes}` /
 	* pg `{rowCount}` / mysql2 tuple `[ResultSetHeader{affectedRows}, fields]`.
 	*/
@@ -228,12 +287,10 @@ var DrizzleRepository = class DrizzleRepository {
 	}
 	/** Empile les conditions d'un objet d'opérateurs riches sur une colonne. */
 	#pushOperators(conds, col, ops) {
-		if (ops.$eq !== void 0) conds.push(eq(col, ops.$eq));
-		if (ops.$ne !== void 0) conds.push(ne(col, ops.$ne));
-		if (ops.$gt !== void 0) conds.push(gt(col, ops.$gt));
-		if (ops.$gte !== void 0) conds.push(gte(col, ops.$gte));
-		if (ops.$lt !== void 0) conds.push(lt(col, ops.$lt));
-		if (ops.$lte !== void 0) conds.push(lte(col, ops.$lte));
+		for (const [op, compare] of COMPARISONS) {
+			const value = ops[op];
+			if (value !== void 0) conds.push(compare(col, value));
+		}
 		if (ops.$in !== void 0) conds.push(inArray(col, [...ops.$in]));
 		if (ops.$nin !== void 0) conds.push(notInArray(col, [...ops.$nin]));
 		if (ops.$like !== void 0) conds.push(likeCond(this.#dialect, sql`${col}`, ops.$like));
@@ -246,7 +303,13 @@ var DrizzleRepository = class DrizzleRepository {
 		for (const [field, value] of Object.entries(criteria)) {
 			if (field === "$or") {
 				if (!Array.isArray(value)) throw new Error(`DrizzleRepository(${getTableName(this.#table)}): $or attend un tableau de critères.`);
-				const [first, ...rest] = value.map((branch) => this.#where(branch)).filter((branch) => branch !== void 0);
+				if (value.length === 0) {
+					conds.push(sql`1 = 0`);
+					continue;
+				}
+				const branches = value.map((branch) => this.#where(branch));
+				if (branches.some((branch) => branch === void 0)) continue;
+				const [first, ...rest] = branches;
 				if (first !== void 0) conds.push(rest.length === 0 ? first : or(first, ...rest));
 				continue;
 			}
@@ -267,8 +330,14 @@ var DrizzleRepository = class DrizzleRepository {
 	* présence de limit/offset. Les VALEURS n'en font jamais partie : elles
 	* deviennent des placeholders (`p<i>`, `lim`, `off`) bindés à l'exécution.
 	*
-	* Repli (`null`) par construction : `$or` et opérateurs riches (le SQL varie
-	* avec la cardinalité — `$in` — ou la combinaison d'opérateurs), valeur
+	* Les comparaisons scalaires ({@link COMPARISONS}) et `$null` entrent dans la
+	* forme : la COMBINAISON d'opérateurs d'un champ fait partie de la clé, leurs
+	* valeurs deviennent des placeholders `p<i>$<op>`. C'est le chemin des
+	* lectures bornées dans le temps (`expiresAt: { $gt: now }` — la révocation
+	* des jetons, lue à chaque requête authentifiée).
+	*
+	* Repli (`null`) par construction : `$or`, `$in`/`$nin` (le SQL suit la
+	* cardinalité), `$like` (clause d'échappement propre au dialecte), valeur
 	* `undefined` (le chemin actuel la rejette, même contrat), transaction
 	* (cf ctor), cache plein ({@link PREPARED_CACHE_MAX}).
 	*/
@@ -278,7 +347,22 @@ var DrizzleRepository = class DrizzleRepository {
 		if (criteria) {
 			let i = 0;
 			for (const [field, value] of Object.entries(criteria)) {
-				if (field === "$or" || value === void 0 || isFieldOperators(value)) return null;
+				if (field === "$or" || value === void 0) return null;
+				if (isFieldOperators(value)) {
+					let ops = "";
+					for (const op in value) if (!PREPARABLE_OPERATORS.has(op)) return null;
+					for (const [op] of COMPARISONS) {
+						const operand = value[op];
+						if (operand !== void 0) {
+							ops += op;
+							params[`p${i}${op}`] = operand;
+						}
+					}
+					if (value.$null !== void 0) ops += value.$null ? "$null1" : "$null0";
+					key += `${field}\x04${ops}\x00`;
+					i++;
+					continue;
+				}
 				if (value === null) key += `${field}\x01\x00`;
 				else {
 					key += `${field}\x00`;
@@ -322,6 +406,12 @@ var DrizzleRepository = class DrizzleRepository {
 			let i = 0;
 			for (const [field, value] of Object.entries(criteria)) {
 				const col = this.#requireCol(field);
+				if (isFieldOperators(value)) {
+					for (const [op, compare] of COMPARISONS) if (value[op] !== void 0) conds.push(compare(col, sql.param(sql.placeholder(`p${i}${op}`), col)));
+					if (value.$null !== void 0) conds.push(value.$null ? isNull(col) : isNotNull(col));
+					i++;
+					continue;
+				}
 				conds.push(value === null ? isNull(col) : eq(col, sql.param(sql.placeholder(`p${i}`), col)));
 				i++;
 			}
@@ -435,7 +525,7 @@ var DrizzleRepository = class DrizzleRepository {
 	}
 	async updateOne(criteria, data) {
 		if (this.#dialect === "mysql") return this.#mysqlUpdateOneReturning(data, criteria);
-		const pick = this.#pickOne(this.#where(criteria));
+		const pick = this.#pickOne(criteria);
 		return (await this.#prof(this.#db.update(execTable(this.#table)).set(data).where(pick).returning()))[0] ?? null;
 	}
 	/**
@@ -502,7 +592,7 @@ var DrizzleRepository = class DrizzleRepository {
 			setObj[field] = sql`${col} + ${delta}`;
 		}
 		if (this.#dialect === "mysql") return this.#mysqlUpdateOneReturning(setObj, criteria);
-		const pick = this.#pickOne(this.#where(criteria));
+		const pick = this.#pickOne(criteria);
 		return (await this.#prof(this.#db.update(execTable(this.#table)).set(setObj).where(pick).returning()))[0] ?? null;
 	}
 	async delete(criteria) {
@@ -521,7 +611,7 @@ var DrizzleRepository = class DrizzleRepository {
 	}
 	/** DELETE atomique d'AU PLUS une ligne (PK via `#pickOne`), RETURNING la ligne. */
 	async #deleteOneReturning(criteria) {
-		const pick = this.#pickOne(this.#where(criteria));
+		const pick = this.#pickOne(criteria);
 		return this.#prof(this.#db.delete(execTable(this.#table)).where(pick).returning());
 	}
 	/** PK obligatoire en mysql (les verbes re-SELECTent par PK). Fail-loud sinon. */

package/dist/nodefony/src/sqliteJournal.js

@@ -0,0 +1,54 @@
+//#region nodefony/src/sqliteJournal.ts
+/** Échéance par défaut : au-delà, une base occupée l'est pour de bon. */
+const WAL_DEADLINE_MS = 1e4;
+const sleepFor = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* L'erreur est-elle un conflit de verrou, qui se règle en réessayant ?
+*
+* @param e - erreur levée par `better-sqlite3`
+* @returns vrai pour `SQLITE_BUSY*` et `SQLITE_LOCKED*`
+*/
+function isSqliteBusy(e) {
+	const code = e?.code;
+	return typeof code === "string" && (code.startsWith("SQLITE_BUSY") || code.startsWith("SQLITE_LOCKED"));
+}
+/**
+* Passe la base en WAL (`synchronous = NORMAL`), en tolérant les ouvertures
+* CONCURRENTES d'une base neuve.
+*
+* Basculer en WAL exige un verrou exclusif. Deux processus qui ouvrent la même
+* base neuve au même instant — l'application et `orm:migrate` lancé par
+* `docker exec`, ou les workers de `nodefony cluster` — tiennent chacun un
+* verrou partagé et veulent l'exclusif : SQLite tranche l'impasse par un
+* `SQLITE_BUSY` IMMÉDIAT, sans passer par l'attente (`timeout`) de la
+* connexion. Mesuré : 23 ouvertures sur 40 échouaient avec trois processus
+* synchronisés, et la forge a vu un `orm:migrate` refusé au démarrage.
+*
+* Le mode WAL est PERSISTANT (écrit dans le fichier) : on le lit d'abord, et
+* seul le premier ouvreur bascule. Un conflit se réessaie, à délai croissant,
+* jusqu'à {@link WAL_DEADLINE_MS} ; toute autre erreur remonte telle quelle.
+*
+* @param db - connexion ouverte sur un FICHIER (sans objet sur `:memory:`)
+* @param options - échéance, attente et horloge (injectées en test)
+* @throws La dernière erreur `SQLITE_BUSY` si l'échéance est dépassée, ou
+*   toute autre erreur au premier essai
+*/
+async function enableWriteAheadLog(db, options = {}) {
+	const deadlineMs = options.deadlineMs ?? 1e4;
+	const sleep = options.sleep ?? sleepFor;
+	const now = options.now ?? Date.now;
+	const start = now();
+	for (let attempt = 1;; attempt++) try {
+		if (db.pragma("journal_mode", { simple: true }) !== "wal") {
+			const mode = db.pragma("journal_mode = WAL", { simple: true });
+			if (mode !== "wal") throw Object.assign(/* @__PURE__ */ new Error(`journal_mode resté « ${String(mode)} »`), { code: "SQLITE_BUSY" });
+		}
+		db.pragma("synchronous = NORMAL");
+		return;
+	} catch (e) {
+		if (!isSqliteBusy(e) || now() - start >= deadlineMs) throw e;
+		await sleep(Math.min(20 * attempt, 250));
+	}
+}
+//#endregion
+export { WAL_DEADLINE_MS, enableWriteAheadLog, isSqliteBusy };

package/dist/types/nodefony/src/sqliteJournal.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Mise en WAL d'une base SQLite — UNE implémentation, appelée par les deux
+ * ouvreurs de fichier du paquet : l'adapter ORM (`DrizzleOrm`) et le pilote de
+ * migration (`sqliteDriver`). Une base migrée puis ouverte par l'application ne
+ * doit pas changer de mode en route, et les deux doivent survivre à la même
+ * concurrence.
+ */
+/** Ce que la mise en WAL lit d'une connexion `better-sqlite3`. */
+export interface ISqlitePragmaClient {
+    pragma(source: string, options?: {
+        simple?: boolean;
+    }): unknown;
+}
+/** Réglages de la mise en WAL — injectables pour l'éprouver sans attendre. */
+export interface IWriteAheadLogOptions {
+    /** Durée maximale des réessais, en millisecondes. */
+    deadlineMs?: number;
+    /** Attente entre deux essais. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Horloge (millisecondes). */
+    now?: () => number;
+}
+/** Échéance par défaut : au-delà, une base occupée l'est pour de bon. */
+export declare const WAL_DEADLINE_MS = 10000;
+/**
+ * L'erreur est-elle un conflit de verrou, qui se règle en réessayant ?
+ *
+ * @param e - erreur levée par `better-sqlite3`
+ * @returns vrai pour `SQLITE_BUSY*` et `SQLITE_LOCKED*`
+ */
+export declare function isSqliteBusy(e: unknown): boolean;
+/**
+ * Passe la base en WAL (`synchronous = NORMAL`), en tolérant les ouvertures
+ * CONCURRENTES d'une base neuve.
+ *
+ * Basculer en WAL exige un verrou exclusif. Deux processus qui ouvrent la même
+ * base neuve au même instant — l'application et `orm:migrate` lancé par
+ * `docker exec`, ou les workers de `nodefony cluster` — tiennent chacun un
+ * verrou partagé et veulent l'exclusif : SQLite tranche l'impasse par un
+ * `SQLITE_BUSY` IMMÉDIAT, sans passer par l'attente (`timeout`) de la
+ * connexion. Mesuré : 23 ouvertures sur 40 échouaient avec trois processus
+ * synchronisés, et la forge a vu un `orm:migrate` refusé au démarrage.
+ *
+ * Le mode WAL est PERSISTANT (écrit dans le fichier) : on le lit d'abord, et
+ * seul le premier ouvreur bascule. Un conflit se réessaie, à délai croissant,
+ * jusqu'à {@link WAL_DEADLINE_MS} ; toute autre erreur remonte telle quelle.
+ *
+ * @param db - connexion ouverte sur un FICHIER (sans objet sur `:memory:`)
+ * @param options - échéance, attente et horloge (injectées en test)
+ * @throws La dernière erreur `SQLITE_BUSY` si l'échéance est dépassée, ou
+ *   toute autre erreur au premier essai
+ */
+export declare function enableWriteAheadLog(db: ISqlitePragmaClient, options?: IWriteAheadLogOptions): Promise<void>;

package/docs/index.md

@@ -200,7 +200,7 @@ Le tableau pour situer en cinq secondes ; les cards en dessous pour savoir où l
     "desc": "Ce qui reste identique (les noms de colonnes, le contrat du repository) et ce qui diverge, avec la raison : types epoch/date/JSON, absence de `RETURNING` en MySQL, `OFFSET` sans `LIMIT`.",
     "meta": "à lire avant de changer de base, pas après le premier incident" },
   { "icon": "🚧", "title": "migrations", "href": "#migrations--deux-chemins-un-seul-schéma",
-    "desc": "En développement, les tables sont créées au démarrage par un DDL dérivé de tes schémas. Ce DDL ne fait aucun `ALTER`, n'émet ni `DEFAULT` SQL ni index : la section dit ce que ça implique en production, et ce que le framework ne fournit pas encore.",
+    "desc": "En développement, les tables sont créées au démarrage par un DDL dérivé de tes schémas : index et clés étrangères compris, aucun `DEFAULT` SQL, et seules les colonnes facultatives ajoutées sont rattrapées. La section dit ce que ça implique en production.",
     "meta": "le point à ne pas rater avant le premier déploiement" }
 ]
 ```
@@ -353,13 +353,18 @@ importable et testable sans serveur.
 
 ### Les options
 
-| Option                    | Type                                | Défaut             | Effet                                                                  |
-| ------------------------- | ----------------------------------- | ------------------ | ---------------------------------------------------------------------- |
-| `connectors`              | `Record<string, Connector>`         | `{ default: {…} }` | Les connexions, indexées par nom (= clé du registre des ORM).          |
-| `connectors.<n>.dialect`  | `"sqlite" \| "postgres" \| "mysql"` | `"sqlite"`         | Choisit le driver (`better-sqlite3` / `pg` / `mysql2`).                |
-| `connectors.<n>.filename` | `string`                            | _résolu au boot_   | Fichier SQLite. `:memory:` = base éphémère. Ignoré hors `sqlite`.      |
-| `connectors.<n>.url`      | `string`                            | —                  | Chaîne de connexion `postgres://…` / `mysql://…`. **Porte un secret.** |
-| `frameworkEntities`       | `boolean`                           | `true`             | Déclare (ou non) le schéma des huit briques durables sur `default`.    |
+| Option                     | Type                                | Défaut              | Effet                                                                                                  |
+| -------------------------- | ----------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------ |
+| `connectors`               | `Record<string, Connector>`         | `{ default: {…} }`  | Les connexions, indexées par nom (= clé du registre des ORM).                                          |
+| `connectors.<n>.dialect`   | `"sqlite" \| "postgres" \| "mysql"` | `"sqlite"`          | Choisit le driver (`better-sqlite3` / `pg` / `mysql2`).                                                |
+| `connectors.<n>.filename`  | `string`                            | _résolu au boot_    | Fichier SQLite. `:memory:` = base éphémère. Ignoré hors `sqlite`.                                      |
+| `connectors.<n>.url`       | `string`                            | —                   | Chaîne de connexion `postgres://…` / `mysql://…`. **Porte un secret.**                                 |
+| `connectors.<n>.ddl`       | `"auto" \| "migrate" \| "none"`     | _par environnement_ | `auto` en développement et en test (`migrate` dès que l'app versionne une migration), `none` ailleurs. |
+| `migrations.dir`           | `string`                            | `"migrations"`      | Dossier des migrations versionnées.                                                                    |
+| `migrations.check`         | `"fail" \| "warn" \| "off"`         | _par environnement_ | Schéma en retard : `fail` retient `/readyz` (production), `warn` ailleurs.                             |
+| `migrations.lockTimeoutMs` | `number`                            | `30000`             | Attente du verrou de migration entre exemplaires.                                                      |
+| `migrations.divergence`    | `"report" \| "fail" \| "off"`       | `"report"`          | Conduite face à une migration appliquée qui a changé depuis.                                           |
+| `frameworkEntities`        | `boolean`                           | `true`              | Déclare (ou non) le schéma des huit briques durables sur `default`.                                    |
 
 Table dérivée de `drizzleConfigSchema` (`config.ts:136`) et de `SQL_DIALECTS` (`config.ts:37`).
 
@@ -420,20 +425,21 @@ la piste à vérifier.
 
 Pour les dialectes réseau, la connexion fait un **ping réel** au démarrage : les pools `pg` et `mysql2`
 sont paresseux, sans ce `SELECT 1` une base morte « se connecterait » et n'échouerait qu'à la première
-requête métier (`#connectPostgres()`, `DrizzleOrm.ts:1193` · `#connectMysql()`, `DrizzleOrm.ts:1514`).
+requête métier (`#connectPostgres()`, `DrizzleOrm.ts:1206` · `#connectMysql()`, `DrizzleOrm.ts:1521`).
 
 ## Dialectes — une base par déploiement, un seul code
 
 Trois dialectes au même contrat. Le tableau dit ce qu'il faut installer et ce qu'on obtient.
 
-| Dialecte   | Driver           | Statut du paquet           | Cible                                      | Configuration |
-| ---------- | ---------------- | -------------------------- | ------------------------------------------ | ------------- |
-| `sqlite`   | `better-sqlite3` | **dépendance** (fournie)   | développement, tests, production mono-nœud | `filename`    |
-| `postgres` | `pg`             | dépendance **optionnelle** | production multi-pod (recommandé)          | `url`         |
-| `mysql`    | `mysql2`         | dépendance **optionnelle** | production — **MySQL 8.4 et MariaDB 11.4** | `url`         |
+| Dialecte   | Driver           | Statut du paquet                   | Cible                                      | Configuration |
+| ---------- | ---------------- | ---------------------------------- | ------------------------------------------ | ------------- |
+| `sqlite`   | `better-sqlite3` | dépendance de pair **optionnelle** | développement, tests, production mono-nœud | `filename`    |
+| `postgres` | `pg`             | dépendance de pair **optionnelle** | production multi-pod (recommandé)          | `url`         |
+| `mysql`    | `mysql2`         | dépendance de pair **optionnelle** | production — **MySQL 8.4 et MariaDB 11.4** | `url`         |
 
-Les drivers réseau sont chargés **paresseusement** au moment de la connexion : une application SQLite
-ne paie ni l'installation ni le chargement de `pg`/`mysql2`.
+Les trois drivers sont des dépendances de pair optionnelles, posées par le scaffold pour le dialecte
+choisi et chargées **paresseusement** à la connexion : une application n'installe, et ne charge, que
+le pilote de son dialecte.
 
 ### Ce qui ne change pas
 
@@ -467,7 +473,7 @@ En MySQL, les verbes « qui rendent la ligne écrite » (`create`, `updateOne`,
 `findOneAndDelete`) se décomposent en sélection de la cible → mutation bornée par la clé primaire **avec
 le critère revérifié dans le `WHERE`** → relecture. Deux à trois allers-retours au lieu d'un : c'est le
 prix du dialecte, payé **uniquement** en MySQL. Une course perdue rend `null`, jamais une mutation hors
-critère (`#mysqlInsertReturning()`, `DrizzleRepository.ts:1105`).
+critère (`#mysqlInsertReturning()`, `DrizzleRepository.ts:1228`).
 
 Le SQL brut nécessaire aux entités du framework est lui aussi routé par dialecte, dans un seul fichier
 (`queryKit.ts`) : recherche dans une colonne JSON (`findUserIdBySocialProvider()`, `queryKit.ts:76`),
@@ -518,12 +524,17 @@ connexion**, donc leurs tables sont créées au moment où l'ORM s'ouvre.
 ### Le DDL dérivé — comment les tables apparaissent
 
 Drizzle ne « synchronise » pas un schéma. L'adapter dérive lui-même un `CREATE TABLE IF NOT EXISTS`
-depuis chaque table déclarée (`#buildCreateTable()`, `DrizzleOrm.ts:509`) et l'exécute à la connexion.
-Trois conséquences à connaître **avant** de dépendre de ce mécanisme :
-
-1. il **crée**, il ne **modifie** pas — aucun `ALTER` n'est émis ;
-2. il n'émet **ni `DEFAULT` SQL ni index** — d'où la règle des défauts en `$defaultFn` ;
-3. il ne connaît que les colonnes, les clés primaires, `NOT NULL` et `UNIQUE`.
+depuis chaque table déclarée (`#buildCreateTable()`, `DrizzleOrm.ts:509`) et l'exécute à la connexion
+**quand le connecteur est en `ddl: "auto"`** — le défaut en développement et en test ; en production
+le défaut est `none`, et un travail extérieur lance `orm:migrate`. Trois conséquences à connaître
+**avant** de dépendre de ce mécanisme :
+
+1. il **crée** les tables, leurs index et leurs clés étrangères ; il ne rattrape ensuite que les
+   colonnes ajoutées qui **acceptent le vide** — jamais une colonne obligatoire, jamais une
+   suppression ;
+2. il n'émet **aucun `DEFAULT` SQL** — d'où la règle des défauts en `$defaultFn` ;
+3. pour tout le reste (renommer, rendre obligatoire, supprimer), c'est une migration
+   (`orm:generate`, `orm:migrate`).
 
 C'est un confort de développement, pas un outil de migration. La suite est dans
 [Migrations](#migrations--deux-chemins-un-seul-schéma).
@@ -559,7 +570,7 @@ await posts.count({ views: { $gte: 10 } });
 
 Les opérateurs (`$eq $ne $gt $gte $lt $lte $in $nin $like`) sont **ceux d'orm-core**, identiques sur
 tous les drivers ; la traduction en `eq()`/`inArray()` se fait dans `#where()`
-(`DrizzleRepository.ts:445`). Leur référence complète est dans
+(`DrizzleRepository.ts:521`). Leur référence complète est dans
 [la page d'orm-core](../../orm-core/docs/index.md).
 
 `$like` est émis avec sa clause `ESCAPE '\'` (`likeSql.ts`), ce qui rend un `%` ou un `_` **littéral**
@@ -570,11 +581,12 @@ lui-même en SQLite : le même critère ne rendait pas les mêmes lignes selon l
 Deux points de comportement qui évitent des surprises :
 
 - **« au plus une ligne »** est garanti par construction pour `updateOne`/`deleteOne`/`increment` :
-  la mutation est bornée par la clé primaire découverte de la table, jamais par un `LIMIT` sur un
-  `UPDATE` (`#pickOne()`, `DrizzleRepository.ts:284`). C'est ce qui rend ces verbes portables — MySQL
+  la mutation est bornée à une ligne : `WHERE <pk> = ?` quand le critère fixe toute la clé primaire,
+  sinon `WHERE pk IN (SELECT pk FROM (SELECT pk … LIMIT 1) AS picked)` — jamais un `LIMIT` sur
+  l'`UPDATE` lui-même (`#pickOne()`, `DrizzleRepository.ts:324`). C'est ce qui rend ces verbes portables — MySQL
   interdit la forme naïve.
 - **l'eager-load est manuel** : une requête `IN (…)` par relation déclarée, puis regroupement en
-  mémoire (`#populate()`, `DrizzleRepository.ts:694`). Choix assumé — pas de couche de relations à
+  mémoire (`#populate()`, `DrizzleRepository.ts:817`). Choix assumé — pas de couche de relations à
   déclarer une seconde fois, et le comportement est le même sur les trois dialectes.
 
 ### Transactions — une connexion dédiée, jamais le pool
@@ -627,7 +639,7 @@ const rows = await db.all(sql`
 `);
 ```
 
-C'est l'**anti-blocage** du modèle Repository (`getNativeConnection()`, `DrizzleOrm.ts:1783`) : CTE,
+C'est l'**anti-blocage** du modèle Repository (`getNativeConnection()`, `DrizzleOrm.ts:1792`) : CTE,
 fonctions de fenêtre, sous-requêtes corrélées, jointures arbitraires. Deux contreparties assumées :
 ce SQL n'est plus portable entre dialectes, et il **ne passe pas** par la sonde de profilage des
 requêtes.
@@ -851,7 +863,7 @@ l'emplacement **est** l'infra déclarée, déjà affichée ailleurs (`location`,
 ## ⚡ Performance & mémoire
 
 **La sonde de requêtes ne coûte rien quand elle est éteinte.** Chaque exécution passe par un point de
-mesure unique (`#prof()`, `DrizzleRepository.ts:355`) qui alimente deux consommateurs — le profileur
+mesure unique (`#prof()`, `DrizzleRepository.ts:433`) qui alimente deux consommateurs — le profileur
 par requête (barre de debug) et l'agrégat de flux. Les deux sont gardés par un drapeau : si aucun n'est
 actif, la fonction rend le constructeur de requête tel quel, sans allocation. Le flux est **désactivé
 en production** par défaut.
@@ -875,8 +887,7 @@ connexions. Les chiffres vivent dans la sortie du banc, pas ici — ils dépende
 | -------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
 | Une écriture dans `transaction()` n'est pas annulée                  | repository obtenu par `getRepository()` → passe par le **pool**, hors tx   | `repo.withTransaction(tx)` — le seul moyen d'entrer dans la transaction   |
 | `NOT NULL constraint failed` sur une colonne pourtant « par défaut » | `.default()` SQL : le DDL dérivé ne l'émet pas                             | poser le défaut côté JS : `$defaultFn(() => …)`                           |
-| Colonne ajoutée, table inchangée                                     | le DDL dérivé **ne fait aucun `ALTER`**                                    | supprimer la base de dev, ou passer par `drizzle-kit`                     |
-| Index déclaré, absent en base                                        | les index ne sortent que via `drizzle-kit`                                 | migration `drizzle-kit` en production                                     |
+| Colonne **obligatoire** ajoutée, table inchangée                     | le rattrapage de développement n'ajoute que les colonnes facultatives      | `nodefony orm:reset` (dev), ou `orm:generate` puis `orm:migrate`          |
 | Le démarrage échoue sur le connecteur                                | infra déclarée injoignable → `BootConfigurationError` (voulu)              | corriger l'URL / démarrer la base / retirer le connecteur                 |
 | `cannot start a transaction within a transaction` (SQLite)           | deux `BEGIN` concurrents sur la connexion unique                           | rien à faire : la file d'attente interne les sérialise                    |
 | Une entité fonctionne en SQLite, échoue en PostgreSQL                | table Drizzle **figée** sur un dialecte, posée sur le connecteur `default` | fixer l'entité sur son propre connecteur SQLite, ou la porter au dialecte |
@@ -941,7 +952,7 @@ npm run test:load   # charge, limites, mémoire
 - 🧭 **L'abstraction au-dessus** : [`@nodefony/orm-core`](../../orm-core/docs/index.md) — contrats
   `IOrm`/`IRepository`/`ITransaction`, `Criteria` et opérateurs riches, registres. À lire pour tout ce
   qui est **portable** ; cette page-ci ne documente que le driver SQL.
-- 🗄️ **Déployer un schéma** : [Migrations de schéma](migrations.md) — les cinq commandes, le
+- 🗄️ **Déployer un schéma** : [Migrations de schéma](migrations.md) — les six commandes, le
   rattrapage de développement, le travail d'orchestrateur et l'expansion/contraction.
 - 📗 **Tutoriel** : [créer une entité pas à pas](../../orm-core/docs/tutorial-entity.md)
 - 🧩 **L'autre driver** : [`@nodefony/mongoose`](../../mongoose/docs/index.md) — même contrat, MongoDB.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/drizzle",
-  "version": "10.0.0-beta.1",
+  "version": "10.0.0-beta.2",
   "description": "Moteur SQL de Nodefony sur Drizzle ORM (SQLite, PostgreSQL, MySQL) : dépôts typés, migrations de schéma et adoption d'une base existante",
   "nodefony": {
     "storeKind": "durable",
@@ -60,29 +60,29 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@nodefony/framework": "^10.0.0-beta.1",
-    "@nodefony/http": "^10.0.0-beta.1",
-    "@nodefony/orm-core": "^10.0.0-beta.1",
-    "@nodefony/security": "^10.0.0-beta.1",
-    "@nodefony/user": "^10.0.0-beta.1",
+    "@nodefony/framework": "^10.0.0-beta.2",
+    "@nodefony/http": "^10.0.0-beta.2",
+    "@nodefony/orm-core": "^10.0.0-beta.2",
+    "@nodefony/security": "^10.0.0-beta.2",
+    "@nodefony/user": "^10.0.0-beta.2",
     "@types/better-sqlite3": "9.6.0",
     "@types/node": "26.6.3",
     "@types/pg": "8.23.1",
     "better-sqlite3": "13.0.3",
     "drizzle-kit": "0.31.11",
-    "mysql2": "3.24.4",
-    "nodefony": "^10.0.0-beta.1",
-    "pg": "8.23.0"
+    "mysql2": "3.24.5",
+    "nodefony": "^10.0.0-beta.2",
+    "pg": "8.23.1"
   },
   "peerDependencies": {
-    "@nodefony/framework": "^10.0.0-beta.1",
-    "@nodefony/http": "^10.0.0-beta.1",
-    "@nodefony/orm-core": "^10.0.0-beta.1",
-    "@nodefony/security": "^10.0.0-beta.1",
-    "@nodefony/user": "^10.0.0-beta.1",
+    "@nodefony/framework": "^10.0.0-beta.2",
+    "@nodefony/http": "^10.0.0-beta.2",
+    "@nodefony/orm-core": "^10.0.0-beta.2",
+    "@nodefony/security": "^10.0.0-beta.2",
+    "@nodefony/user": "^10.0.0-beta.2",
     "better-sqlite3": "^13.0.0",
     "mysql2": "^3.24.0",
-    "nodefony": "^10.0.0-beta.1",
+    "nodefony": "^10.0.0-beta.2",
     "pg": "^8.23.0"
   },
   "repository": {