@nodefony/drizzle 10.0.0-alpha.9 → 10.0.0-beta.2

package/dist/nodefony/src/queryKit.js

@@ -30,12 +30,12 @@ import { sql } from "drizzle-orm";
 */
 async function findUserIdBySocialProvider(db, dialect, provider, providerId) {
 	switch (dialect) {
-		case "sqlite": return (await db.all(sql`SELECT "id" AS id FROM ${ident("sqlite", USER_TABLE_NAME)}
+		case "sqlite": return db.all(sql`SELECT "id" AS id FROM ${ident("sqlite", USER_TABLE_NAME)}
             WHERE EXISTS (
               SELECT 1 FROM json_each(${ident("sqlite", USER_TABLE_NAME)}."socialProviders")
               WHERE json_extract(value, '$.provider') = ${provider}
                 AND json_extract(value, '$.providerId') = ${providerId}
-            ) LIMIT 1`))[0]?.id ?? null;
+            ) LIMIT 1`)[0]?.id ?? null;
 		case "postgres": {
 			const pattern = JSON.stringify([{
 				provider,
@@ -95,7 +95,7 @@ async function reserveIdempotencyKeyMysql(db, args) {
 	const [inserted] = await exec.execute(sql`INSERT IGNORE INTO ${sql.raw("`idempotency_key`")}
           (${sql.raw("`key`, `fingerprint`, `state`, `response`, `expiresAt`")})
         VALUES (${key}, ${fingerprint}, 'if', NULL, ${leaseExpiresAt})`);
-	if ((inserted?.affectedRows ?? 0) === 1) return true;
+	if ((inserted.affectedRows ?? 0) === 1) return true;
 	const [stolen] = await exec.execute(sql`UPDATE ${sql.raw("`idempotency_key`")}
         SET ${sql.raw("`fingerprint`")} = ${fingerprint},
             ${sql.raw("`state`")} = 'if',
@@ -103,7 +103,7 @@ async function reserveIdempotencyKeyMysql(db, args) {
             ${sql.raw("`expiresAt`")} = ${leaseExpiresAt}
         WHERE ${sql.raw("`key`")} = ${key}
           AND ${sql.raw("`expiresAt`")} < ${now}`);
-	return (stolen?.affectedRows ?? 0) > 0;
+	return (stolen.affectedRows ?? 0) > 0;
 }
 /** Identifiant quoté selon le dialecte (`"x"` SQL standard, `` `x` `` MySQL). */
 function ident(dialect, name) {
@@ -189,7 +189,7 @@ function orderBySql(dialect, order, allowed, fallback, tiebreaker) {
 /** Exécute un SELECT et normalise le retour en tableau de lignes (API native divergente). */
 async function runSelect(db, dialect, query) {
 	switch (dialect) {
-		case "sqlite": return await db.all(query);
+		case "sqlite": return db.all(query);
 		case "postgres": return (await db.execute(query)).rows;
 		case "mysql": {
 			const [rows] = await db.execute(query);

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/DrizzleUserRepository.d.ts

@@ -40,7 +40,7 @@ export declare class DrizzleUserRepository implements IUserRepository {
     updateMany(criteria: Criteria<IPasswordAuthenticatedUser>, data: Partial<IPasswordAuthenticatedUser>): Promise<number>;
     delete(criteria: Criteria<IPasswordAuthenticatedUser>): Promise<number>;
     count(criteria?: Criteria<IPasswordAuthenticatedUser>): Promise<number>;
-    countDistinct(field: keyof IPasswordAuthenticatedUser & string, criteria?: Criteria<IPasswordAuthenticatedUser>): Promise<number>;
+    countDistinct(field: Extract<keyof IPasswordAuthenticatedUser, string>, criteria?: Criteria<IPasswordAuthenticatedUser>): Promise<number>;
     withTransaction(tx: ITransaction): IUserRepository;
     findByIdentifier(identifier: string): Promise<IPasswordAuthenticatedUser | null>;
     /**

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

@@ -35,7 +35,7 @@ export declare function defaultConnectorFilename(kernel: Kernel | null, name: st
 export interface IConnectorTarget {
     dialect: SqlDialect;
     filename?: string;
-    url?: string;
+    url?: string | undefined;
 }
 /**
  * Résout les coordonnées d'un connecteur : dialecte, et fichier ou URL.

package/dist/types/nodefony/src/migrator/DrizzleMigrator.d.ts

@@ -10,7 +10,7 @@ export interface IDrizzleMigratorOptions extends IMigrationTarget {
     /** Registre de sources, espace de noms OUVERT. */
     sources: readonly IMigrationSource[];
     /** Délai d'attente du verrou (ms). */
-    lockTimeoutMs?: number;
+    lockTimeoutMs?: number | undefined;
     /** Qui applique — hôte du job par défaut. */
     appliedBy?: string;
     /** Horloge, injectable pour les tests. */
@@ -71,12 +71,12 @@ export declare class DrizzleMigrator {
      * @returns ce qui a été levé et ré-aligné.
      */
     repair(options?: {
-        source?: string;
-        updateHashes?: boolean;
+        source?: string | undefined;
+        updateHashes?: boolean | undefined;
         forget?: readonly {
             source: string;
             tag: string;
-        }[];
+        }[] | undefined;
     }): Promise<{
         cleared: {
             source: string;

package/dist/types/nodefony/src/migrator/destructive.d.ts

@@ -155,5 +155,5 @@ export declare function touchesExistingRows(files: readonly {
  */
 export declare function checkDataAdvice(connector: string, target?: {
     dialect: string;
-    target?: string;
+    target?: string | undefined;
 }): string;

package/dist/types/nodefony/src/migrator/drivers/index.d.ts

@@ -8,9 +8,9 @@ export interface IMigrationTarget {
     /** Dialecte du connecteur. */
     dialect: SqlDialect;
     /** Fichier SQLite (dialecte `sqlite`). */
-    filename?: string;
+    filename?: string | undefined;
     /** URL de connexion DIRECTE (dialectes `postgres` et `mysql`). */
-    url?: string;
+    url?: string | undefined;
 }
 /**
  * Ouvre le pilote à connexion unique du dialecte demandé.

package/dist/types/nodefony/src/migrator/explain.d.ts

@@ -108,15 +108,15 @@ export interface IMigrationEntryReport {
     /** Où en est cette migration pour CE connecteur. */
     status: "applied" | "pending" | "failed" | "drifted" | "missing";
     /** Début de l'application, en millisecondes — absent si jamais appliquée. */
-    appliedAt?: number;
+    appliedAt?: number | undefined;
     /** Durée de l'application, en millisecondes. */
-    durationMs?: number;
+    durationMs?: number | undefined;
     /** Ce qui l'a appliquée, tel que l'historique l'a retenu. */
-    appliedBy?: string;
+    appliedBy?: string | undefined;
     /** Déploiement qui l'a portée — groupe les migrations d'un même passage. */
-    runId?: string;
+    runId?: string | undefined;
     /** Motif de l'échec, quand elle a échoué. */
-    error?: string;
+    error?: string | undefined;
 }
 /**
  * La charge utile figée — cœur NEUTRE au premier niveau, spécifique du pilote
@@ -155,7 +155,7 @@ export interface IMigrationReport {
      * Son ABSENCE est un fait, pas un oubli : sur une base conforme, il n'y a
      * rien à nommer.
      */
-    divergence?: ISchemaComparison;
+    divergence?: ISchemaComparison | undefined;
     /**
      * Ce que le passage a DÉTRUIT, nommé — présent au seul run réel qui a
      * appliqué une migration destructive, absent partout ailleurs.
@@ -166,7 +166,7 @@ export interface IMigrationReport {
      * octet de ce qu'il relit ne la mentionne. Son absence est un fait : rien
      * n'a été détruit.
      */
-    destructive?: IDestructiveFinding[];
+    destructive?: IDestructiveFinding[] | undefined;
     /** Tout ce qui est propre au pilote SQL vit ici, et nulle part ailleurs. */
     driver: {
         kind: "sql";
@@ -174,9 +174,9 @@ export interface IMigrationReport {
         ddl: string;
         historyTable: string;
         /** La base visée, sans identifiant ni mot de passe. */
-        target?: string;
+        target?: string | undefined;
         /** `true` quand la cible vient de `NF_MIGRATE_DATABASE_URL`. */
-        fromMigrateUrl?: boolean;
+        fromMigrateUrl?: boolean | undefined;
     };
 }
 /** Grille des codes de sortie — **figée, jamais réaffectée**. */

package/dist/types/nodefony/src/migrator/name.d.ts

@@ -34,7 +34,7 @@ export type MigrationNameCheck = {
      * geste qui échoue est pire que ne rien proposer, parce qu'il fait perdre
      * un aller-retour ET la confiance dans les autres suggestions.
      */
-    suggestion?: string;
+    suggestion?: string | undefined;
 };
 /**
  * Dérive un nom acceptable d'une saisie qui ne l'est pas.

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

@@ -98,9 +98,9 @@ export interface IMigrationVerdict {
     /** Connecteur concerné. */
     connector: string;
     /** Source de migrations concernée, quand le refus en désigne une. */
-    source?: string;
+    source?: string | undefined;
     /** Tag concerné, quand le refus en désigne un. */
-    tag?: string;
+    tag?: string | undefined;
     /** Faits constatés, sans mise en forme — de quoi rendre la phrase. */
     facts: Record<string, string | number | boolean | readonly string[]>;
     /** Ce qu'il faut faire ensuite, du plus direct au plus assumé. */

package/dist/types/nodefony/src/orm-core/DrizzleOrm.d.ts

@@ -13,12 +13,12 @@ export interface DrizzleOrmOptions {
      */
     dialect?: SqlDialect;
     /** Fichier SQLite (`":memory:"` par défaut) — dialecte `sqlite` uniquement. */
-    filename?: string;
+    filename?: string | undefined;
     /**
      * Chaîne de connexion (`postgres://…`, `mysql://…`) — dialectes `postgres`/
      * `mysql`. Requise pour ces dialectes.
      */
-    url?: string;
+    url?: string | undefined;
     /**
      * Container du service qui construit l'ORM — il porte le `syslog` du kernel.
      *
@@ -28,7 +28,7 @@ export interface DrizzleOrmOptions {
      * échecs des sondes, jamais le diagnostic de la reprise. Omis en usage
      * direct (bancs de test) : l'ORM reste alors autonome, comme avant.
      */
-    container?: Container;
+    container?: Container | undefined;
     /**
      * Le schéma doit-il être DÉRIVÉ du code à la connexion ?
      *

package/dist/types/nodefony/src/orm-core/DrizzleRepository.d.ts

@@ -15,7 +15,7 @@ import type { Criteria, IRepository, ITransaction, RepositoryReadOptions, Update
  * La surface d'exécution native qui DIVERGE (`db.all` vs `db.execute().rows`)
  * est routée par le `queryKit` — jamais ici.
  */
-export type DrizzleDb = BetterSQLite3Database<Record<string, never>>;
+export type DrizzleDb = BetterSQLite3Database;
 /** Table Drizzle multi-dialecte (l'union honnête des variantes colKit). */
 export type DrizzleTable = SQLiteTable | PgTable | MySqlTable;
 /** Colonne Drizzle dialecte-agnostique (classe de base — acceptée par les

package/dist/types/nodefony/src/orm-core/ddlPlan.d.ts

@@ -24,9 +24,9 @@ export interface IResolvedForeignKey {
     /** Colonnes visées, dans le même ordre que {@link columns}. */
     readonly foreignColumns: readonly string[];
     /** Politique d'effacement du parent (`restrict`, `set null`, `cascade`…). */
-    readonly onDelete?: string;
+    readonly onDelete?: string | undefined;
     /** Politique de mise à jour de la clé du parent. */
-    readonly onUpdate?: string;
+    readonly onUpdate?: string | undefined;
 }
 /** Une table à créer, et les tables que ses clés étrangères désignent. */
 export interface ITableDependency {

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

@@ -66,11 +66,11 @@ export declare function reserveIdempotencyKeyMysql(db: DrizzleDb, args: {
 }): Promise<boolean>;
 /** Filtres du listing utilisateur (sous-ensemble non portable de `IUserListQuery`). */
 export interface UserListFilters {
-    role?: string;
-    enabled?: boolean;
-    locked?: boolean;
-    hasSocial?: boolean;
-    q?: string;
+    role?: string | undefined;
+    enabled?: boolean | undefined;
+    locked?: boolean | undefined;
+    hasSocial?: boolean | undefined;
+    q?: string | undefined;
 }
 /** Fenêtre + tri résolus (le défaut `identifier ASC` est posé par l'appelant). */
 export interface UserPageWindow {
@@ -91,10 +91,10 @@ export declare function listUserIdsPage(db: DrizzleDb, dialect: SqlDialect, filt
 }>;
 /** Filtres du listing d'endpoints (sous-ensemble non portable d'`IWebhookListQuery`). */
 export interface WebhookListFilters {
-    enabled?: boolean;
-    event?: string;
-    failing?: boolean;
-    q?: string;
+    enabled?: boolean | undefined;
+    event?: string | undefined;
+    failing?: boolean | undefined;
+    q?: string | undefined;
 }
 /**
  * Sélectionne les `id` d'une **page** d'endpoints webhook (filtres + tri +

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

@@ -37,6 +37,6 @@ import type { SqlDialect } from "../config/config.js";
  */
 export declare function describeTargetSafely(target: {
     dialect: SqlDialect;
-    filename?: string;
-    url?: string;
+    filename?: string | undefined;
+    url?: string | undefined;
 }, cwd?: string, grammar?: typeof path): string;

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,19 +353,24 @@ 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`).
 
 **`filename` est volontairement sans défaut.** Le chemin dépend du kernel, qui n'existe pas quand le
 schéma est évalué. Il est résolu **au démarrage** par `DrizzleService.#defaultFilename()`
-(`DrizzleService.ts:202`) vers `<app>/var/databases/nodefony-<connecteur>.db` — sous `var/`, le dossier
+(`DrizzleService.ts:230`) vers `<app>/var/databases/nodefony-<connecteur>.db` — sous `var/`, le dossier
 commun des données runtime : « où sont mes données ? » a une réponse unique, un seul chemin à
 sauvegarder et à ignorer dans git.
 
@@ -406,13 +411,13 @@ use("@nodefony/drizzle", {
 
 > [!WARNING]
 > Une URL de connexion **porte un mot de passe**. Le module ne la journalise jamais telle quelle :
-> `redactUrl()` (`DrizzleService.ts:86`) remplace le mot de passe par `***` avant tout log de
+> `redactUrl()` (`DrizzleService.ts:99`) remplace le mot de passe par `***` avant tout log de
 > démarrage, et la sonde d'administration applique la même règle.
 
 ### Quand la connexion échoue, le démarrage échoue
 
 Un connecteur **déclaré** qui ne se connecte pas lève une `BootConfigurationError`
-(`DrizzleService.ts:340`) — en développement **comme** en production. Ce n'est pas une sévérité
+(`DrizzleService.ts:368`) — en développement **comme** en production. Ce n'est pas une sévérité
 gratuite : une infrastructure déclarée mais injoignable ne se répare pas en continuant. Un serveur qui
 démarrerait « vivant » avec ses stores morts accepterait des requêtes pour échouer plus tard, la cause
 noyée dans un avertissement. Le message d'erreur nomme le connecteur, le dialecte, la cible rédigée et
@@ -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:1504`).
+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:1149`).
+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`),
@@ -507,7 +513,7 @@ connexion**, donc leurs tables sont créées au moment où l'ORM s'ouvre.
 | Pièce                  | Rôle                                                                   | Ancre                                                        |
 | ---------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------ |
 | `Drizzle` (le module)  | valide la config, déclare le schéma framework, monte le data plane     | `index.ts` du module                                         |
-| `DrizzleService`       | ouvre un ORM par connecteur au boot, ferme tout à l'arrêt              | `connectAll()`, `DrizzleService.ts:186`                      |
+| `DrizzleService`       | ouvre un ORM par connecteur au boot, ferme tout à l'arrêt              | `connectAll()`, `DrizzleService.ts:214`                      |
 | `DrizzleOrm`           | la connexion : DDL dérivé, repositories, transactions, sonde           | `DrizzleOrm.ts:214`                                          |
 | `DrizzleRepository<T>` | le CRUD portable, les opérateurs riches, l'eager-load                  | `DrizzleRepository.ts:146`                                   |
 | `DrizzleTransaction`   | `BEGIN`/`COMMIT`/`ROLLBACK` pilotés à la main, sur les trois dialectes | `DrizzleTransaction.ts:70`                                   |
@@ -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:420`). 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:259`). 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:1745`) : 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.
@@ -718,7 +730,7 @@ le framework résout ses stores avant que l'ORM ne soit connecté — et parce q
 l'arrêt** avant que les serveurs HTTP n'aient fini de vider leurs requêtes en vol. Handle absent =
 dégradation annoncée, pas un plantage : le `SessionStorage` rend une session vide et ignore les
 écritures (`#repo()`, `SessionStorage.ts:86`), le store d'idempotence laisse passer la mutation sans
-dédup (`begin()`, `DrizzleIdempotencyStore.ts:220`).
+dédup (`begin()`, `DrizzleIdempotencyStore.ts:225`).
 
 **SQL n'a pas de TTL.** Contrairement à Redis, rien n'expire tout seul : chaque store expose un `gc()`
 applicatif qui supprime les lignes échues, déclenché par un minuteur hors du chemin chaud —
@@ -735,7 +747,7 @@ c'est ce qui interdit de conclure « nouvelle mutation » hors d'une réservatio
 en deux instructions au verdict non ambigu (`reserveIdempotencyKeyMysql()`, `queryKit.ts:152`).
 
 **Le journal d'audit** pagine par un curseur **composite auto-portant** `<horodatage>:<id>` sur un ordre
-total, plutôt que par un identifiant seul (`listPage()`, `DrizzleAuditStore.ts:169`). Deux gains : plus
+total, plutôt que par un identifiant seul (`listPage()`, `DrizzleAuditStore.ts:175`). Deux gains : plus
 d'aller-retour pour résoudre le curseur, et une pagination qui ne rembobine pas à la première page si
 l'événement de référence a été purgé entre deux appels.
 
@@ -834,7 +846,7 @@ faire lui-même).
 Côté écrans : **Database**, **ORM (vue d'ensemble et par entité)** et **Stores** — ce dernier répond à
 la question « où sont écrites mes données ? » pour chaque brique.
 
-La sonde d'un connecteur s'adapte au dialecte (`probe()`, `DrizzleOrm.ts:1835`) :
+La sonde d'un connecteur s'adapte au dialecte (`probe()`, `DrizzleOrm.ts:1873`) :
 
 - **SQLite** → `storage` : taille du fichier, mode de journal, pages libres (lus par `PRAGMA`) ;
 - **PostgreSQL / MySQL** → `pool` : taille, connexions libres, empruntées, en attente — **compteurs en
@@ -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:330`) 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/docs/migrations.md

@@ -426,7 +426,7 @@ Trois propriétés en découlent, et elles valent d'être nommées :
 - **Rien n'est appliqué deux fois.** L'historique (`nodefony_migrations`, `types.ts:23`) est écrit
   dans la même transaction que le DDL, là où le moteur le permet.
 - **Un pod en retard ne reçoit pas de trafic.** En `none` comme en `migrate`, l'état du schéma est
-  publié à la sonde de disponibilité (`#publishReadiness()`, `DrizzleService.ts:527`) : `/readyz`
+  publié à la sonde de disponibilité (`#publishReadiness()`, `DrizzleService.ts:557`) : `/readyz`
   répond 503, l'orchestrateur sort l'exemplaire du répartiteur de charge, et l'ancien continue de
   servir. `/livez` n'est jamais touché — un schéma en retard n'est pas un processus malade, et le
   redémarrer ne réparerait rien. La vérification est rejouée toutes les 15 secondes : dès que le