--- title: "Référence d'API — @nodefony/drizzle — migrator" source: docs/api/drizzle/migrator.md url: https://nodefony.github.io/nodefony-core/docs/api/drizzle/migrator/ --- [Documentation](../../../) › [Référence d'API](../../) › [`@nodefony/drizzle`](../) › migrator > Générée depuis les déclarations de types publiées de `@nodefony/drizzle` **10.0.0-beta.5** : exactement ce que reçoit une application qui l'installe. Cette page n'existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code. ## `@nodefony/drizzle` `import { … } from "@nodefony/drizzle"` — 60 symboles. ### Classes (2) #### `DrizzleMigrator` ```ts class DrizzleMigrator ``` - `constructor(options: IDrizzleMigratorOptions)` - `get connector(): string` — Connecteur servi par cet applicateur. - `get dialect(): SqlDialect` — Dialecte servi par cet applicateur. - `status(): Promise` — État complet de la migration — **lecture seule, sans verrou ni écriture**. - `compareToDeclared(expected: readonly IExpectedTable[]): Promise` — Compare la base que VISE cet applicateur aux tables que le code déclare — lecture seule, sans verrou. - `migrate(options?: IMigrateOptions): Promise` — Applique les migrations restantes, sous verrou. - `baseline(upTo?: string): Promise` - `repair(options?: { source?: string; updateHashes?: boolean; forget?: readonly { source: string; tag: string; }[]; }): Promise<{ cleared: { source: string; tag: string; }[]; rehashed: { source: string; …` — Lève les marqueurs d'échec, **après inspection humaine**. #### `MigrationVerdictError` ```ts class MigrationVerdictError extends Error ``` Erreur portant un `IMigrationVerdict` — le message n'est qu'un rendu. - `readonly verdict: IMigrationVerdict` - `constructor(verdict: IMigrationVerdict, message: string)` ### Fonctions (23) #### `action` ```ts function action(command: string): IMigrationAction ``` Fabrique une action affichable et exécutable. #### `appMigrationsDir` ```ts function appMigrationsDir(kernel: Kernel | null, dir: string): string ``` Dossier de migrations de l'application, résolu depuis la racine que le kernel connaît. #### `buildMigrator` ```ts function buildMigrator(resolution: Extract, config: IDrizzleConfig, kernel: Kernel | null): Promise ``` Construit l'applicateur d'un connecteur résolu. #### `buildReport` ```ts function buildReport(plan: IMigrationPlan, ctx: IReportContext): IMigrationReport ``` Compose la charge utile complète d'un état de migration. #### `defaultMigrationSources` ```ts function defaultMigrationSources(appDir?: string, options?: { framework?: boolean; connector?: string; }): Promise ``` Registre de sources standard : le framework, puis l'application. #### `exitCodeOf` ```ts function exitCodeOf(verdict: MigrationVerdictName, divergenceBlocks?: boolean): 0 | 1 | 2 ``` Le code de sortie d'un verdict. #### `frameworkMigrationsDir` ```ts function frameworkMigrationsDir(): Promise ``` Dossier des migrations livrées par ce paquet. #### `knownConnectors` ```ts function knownConnectors(config: IDrizzleConfig): string[] ``` Tous les noms de connecteurs qui existent, tous ORM confondus. #### `loadSources` ```ts function loadSources(sources: readonly IMigrationSource[], dialect: SqlDialect): Promise ``` Charge toutes les sources d'un registre pour un dialecte donné. #### `meaningOf` ```ts function meaningOf(verdict: MigrationVerdictName): string ``` Ce que le verdict veut dire — la CAUSE, entre le fait et le geste. #### `migrationHash` ```ts function migrationHash(content: string): string ``` Empreinte d'un fichier de migration : **normalisée** et **auto-descriptive**. #### `openMigrationDriver` ```ts function openMigrationDriver(target: IMigrationTarget): Promise ``` Ouvre le pilote à connexion unique du dialecte demandé. #### `orderSources` ```ts function orderSources(sources: readonly IMigrationSource[]): IMigrationSource[] ``` Ordonne un registre de sources : rang croissant, nom en départage. #### `readMigrationEnv` ```ts function readMigrationEnv(kernel: Kernel | null): IMigrationEnv ``` Constate l'environnement depuis le kernel et le processus. #### `renderRefusal` ```ts function renderRefusal(verdict: IMigrationVerdict, message: string, style: IStyle, ddl?: string): string ``` Rendu humain d'un REFUS de l'applicateur. #### `renderStatus` ```ts function renderStatus(report: IMigrationReport, style: IStyle): string ``` Rendu humain d'un état de migration — l'écran que voit celui qui tape `orm:migrate:status`. #### `resetAllowed` ```ts function resetAllowed(env: IMigrationEnv): boolean ``` L'effacement d'une base est-il ACCEPTÉ dans cet environnement ? #### `resolveCheckMode` ```ts function resolveCheckMode(explicit: MigrationCheckMode, env: IMigrationEnv): MigrationCheckMode ``` La conduite de la sonde de disponibilité face à un schéma en retard. #### `resolveConnector` ```ts function resolveConnector(connector: string, config: IDrizzleConfig, env: IMigrationEnv, kernel: Kernel | null, options?: { allowMigrateUrl?: boolean; }): IConnectorResolution ``` Résout un nom de connecteur en l'une des **trois** réponses possibles. #### `resolveDdlMode` ```ts function resolveDdlMode(explicit: DdlMode, env: IMigrationEnv, appHasMigrations?: boolean, volatile?: boolean): DdlMode ``` Le mode de schéma qui s'applique à un connecteur. #### `resolveDivergenceMode` ```ts function resolveDivergenceMode(config: IDrizzleConfig): DivergenceMode ``` Conduite face à la divergence, telle que la configuration la déclare. #### `styleFor` ```ts function styleFor(tty: boolean): IStyle ``` Construit le styliste : couleurs en terminal, texte nu ailleurs. #### `verdictOf` ```ts function verdictOf(plan: IMigrationPlan, divergent?: boolean): MigrationVerdictName ``` Situation d'ensemble d'un plan, dans l'ordre de gravité. ### Constantes (12) #### `APP_RANK` ```ts const APP_RANK = 1000000 ``` Rang de la source application : dernière appliquée, toujours. #### `APP_SOURCE` ```ts const APP_SOURCE = "app" ``` Nom logique RÉSERVÉ de la source livrée par l'application. #### `DEFAULT_LOCK_TIMEOUT_MS` ```ts const DEFAULT_LOCK_TIMEOUT_MS = 30000 ``` Délai d'attente du verrou, par défaut. #### `EXIT` ```ts const EXIT: { readonly ok: 0; readonly actionRequired: 1; readonly error: 2; } ``` Grille des codes de sortie — **figée, jamais réaffectée**. #### `FORMAT_MARKER` ```ts const FORMAT_MARKER = "-- nodefony:migration format=1" ``` Marqueur de format que porte la première ligne de chaque fichier `.sql`. #### `FRAMEWORK_RANK` ```ts const FRAMEWORK_RANK = 0 ``` Rang de la source framework : première appliquée, toujours. #### `FRAMEWORK_SOURCE` ```ts const FRAMEWORK_SOURCE = "framework" ``` Nom logique RÉSERVÉ de la source livrée par le framework. #### `HISTORY_TABLE` ```ts const HISTORY_TABLE = "nodefony_migrations" ``` Nom de la table d'historique — **jamais qualifié d'un schéma**. #### `MIGRATE_URL_ENV` ```ts const MIGRATE_URL_ENV = "NF_MIGRATE_DATABASE_URL" ``` URL de connexion réservée au **travail de migration**. #### `MIGRATION_FORMAT_VERSION` ```ts const MIGRATION_FORMAT_VERSION = 1 ``` Version de la charge utile `--json` **et** du plan d'administration. #### `MYSQL_LOCK_NAME_SQL` ```ts const MYSQL_LOCK_NAME_SQL: string ``` Expression SQL de l'identité du verrou — évaluée par le SERVEUR. #### `PG_LOCK_KEY` ```ts const PG_LOCK_KEY: bigint ``` Clé du verrou consultatif PostgreSQL — **figée à vie**. ### Interfaces (20) #### `IAppliedMigration` ```ts interface IAppliedMigration ``` Une ligne de la table d'historique, colonnes lues NOMMÉMENT. - `source: string` - `tag: string` - `hash: string` - `runId: string` - `startedAt: number` - `finishedAt: number | null` - `executionMs: number | null` - `success: boolean` - `error: string | null` - `appliedBy: string | null` #### `IDrizzleMigratorOptions` ```ts interface IDrizzleMigratorOptions extends IMigrationTarget ``` Options de construction de l'applicateur. - `connector: string` — Nom du connecteur — apparaît dans chaque verdict. - `sources: readonly IMigrationSource[]` — Registre de sources, espace de noms OUVERT. - `lockTimeoutMs?: number` — Délai d'attente du verrou (ms). - `appliedBy?: string` — Qui applique — hôte du job par défaut. - `now?: () => number` — Horloge, injectable pour les tests. #### `IMigrateOptions` ```ts interface IMigrateOptions ``` Assouplissements explicites d'une passe d'application. - `ignoreMissing?: boolean` — Accepte qu'une migration appliquée n'ait plus de fichier. - `outOfOrder?: boolean` — Accepte d'appliquer une migration antérieure à la dernière appliquée. - `dryRun?: boolean` — N'applique rien : rend le plan tel qu'il serait exécuté. #### `IMigrationAction` ```ts interface IMigrationAction ``` Commande à exécuter pour lever un refus — l'agent lit `nextActions[0]`. - `command: string` — Commande complète, prête à copier. - `args: string[]` — Arguments, séparés pour un appel programmatique. #### `IMigrationApplied` ```ts interface IMigrationApplied ``` Résultat de l'application d'une migration. - `source: string` - `tag: string` - `executionMs: number` #### `IMigrationDrift` ```ts interface IMigrationDrift ``` Une dérive constatée : le fichier a changé après avoir été appliqué. - `source: string` - `tag: string` - `expected: string` — Empreinte enregistrée au moment de l'application. - `actual: string` — Empreinte du fichier tel qu'il est aujourd'hui. #### `IMigrationDriver` ```ts interface IMigrationDriver extends ISchemaReader ``` Pilote de base de données de l'applicateur — **une connexion, pas un pool**. - `readonly dialect: SqlDialect` — Dialecte servi. - `readonly transactionalDdl: boolean` — Le DDL de ce dialecte est-il transactionnel ? - `exec(sql: string): Promise` — Exécute un statement sans résultat. - `query>(sql: string, params?: readonly unknown[]): Promise` — Exécute une requête paramétrée ; les paramètres s'écrivent `?`. - `begin(): Promise` — Ouvre une transaction (`BEGIN IMMEDIATE` en sqlite). - `commit(): Promise` - `rollback(): Promise` - `lock(timeoutMs: number): Promise` — Prend le verrou d'applicateur, ou lève au bout de `timeoutMs`. - `unlock(): Promise` — Libère le verrou. - `close(): Promise` — Ferme la connexion. #### `IMigrationEnv` ```ts interface IMigrationEnv ``` L'environnement tel qu'on le CONSTATE — jamais déduit à l'intérieur. - `runtime: "development" | "production"` — Mode moteur normalisé du kernel : `development` ou `production`. - `nodeEnv?: string` — `NODE_ENV` brut — seul porteur de la valeur `test`. #### `IMigrationFile` ```ts interface IMigrationFile ``` Un fichier de migration chargé depuis une source. - `source: string` — Source qui le livre. - `tag: string` — Identité immuable du fichier (`0000_framework_init`). - `idx: number` — Rang dans le journal de SA source. - `hash: string` — Empreinte auto-descriptive `sha256:` du contenu normalisé. - `statements: readonly string[]` — Statements découpés, dans l'ordre, sans les vides. - `path: string` — Chemin du fichier — pour nommer un refus. #### `IMigrationPlan` ```ts interface IMigrationPlan ``` État complet, calculé en LECTURE SEULE. - `connector: string` - `dialect: SqlDialect` - `applied: readonly IAppliedMigration[]` — Migrations appliquées avec succès, ordre d'application. - `pending: readonly IMigrationFile[]` — Migrations à appliquer, dans l'ordre (rang de source, puis journal). - `drifted: readonly IMigrationDrift[]` — Fichiers modifiés après application. - `failed: readonly IAppliedMigration[]` — Marqueurs d'échec, ou migrations jamais terminées. - `missing: readonly { source: string; tag: string; }[]` — Appliquées en base mais sans fichier, dans une source PRÉSENTE. - `ignoredSources: readonly string[]` — Sources vues en base mais absentes du registre — ignorées, jamais bloquantes. - `baselineRequired: boolean` — Historique vide alors que les tables du schéma existent déjà. #### `IMigrationReport` ```ts interface IMigrationReport ``` La charge utile figée — cœur NEUTRE au premier niveau, spécifique du pilote sous `driver`. - `formatVersion: typeof MIGRATION_FORMAT_VERSION` - `connector: string` — Connecteur observé. - `verdict: MigrationVerdictName` — Situation d'ensemble — énumération gelée. - `exitCode: 0 | 1 | 2` — Code de sortie que cette situation produit sur la ligne de commande. - `summary: string` — Le fait constaté, en une phrase française. - `nextActions: IMigrationAction[]` — Ce qu'il faut faire, du plus direct au plus assumé. - `sources: IMigrationSourceReport[]` — Une source par entrée, dans l'ordre d'application. - `divergence?: ISchemaComparison` — CE QUI diverge, nommé — présent au seul verdict `divergent`, absent partout ailleurs. - `destructive?: IDestructiveFinding[]` — Ce que le passage a DÉTRUIT, nommé — présent au seul run réel qui a appliqué une migration destructive, absent partout ailleurs. - `driver: { kind: "sql"; dialect: SqlDialect; ddl: string; historyTable: string; target?: string; fromMigrateUrl?: boolean; }` — Tout ce qui est propre au pilote SQL vit ici, et nulle part ailleurs. #### `IMigrationRun` ```ts interface IMigrationRun ``` Résultat d'un `migrate()`. - `runId: string` — Identifiant du run — groupe les migrations d'un même déploiement. - `applied: readonly IMigrationApplied[]` — Migrations effectivement appliquées, dans l'ordre. #### `IMigrationSource` ```ts interface IMigrationSource ``` Une source de migrations : un espace de noms OUVERT. - `name: string` — Nom logique, découplé du paquet qui livre le dossier. - `dir: string` — Dossier RACINE des migrations ; le sous-dossier de dialecte est dérivé. - `rank: number` — Rang d'application : `framework` = 0, modules ensuite, `app` en dernier. #### `IMigrationSourceReport` ```ts interface IMigrationSourceReport ``` Ce qu'une source de migrations donne à voir. - `name: string` — Nom logique de la source (`framework`, `app`, un module tiers). - `applied: number` — Migrations appliquées avec succès. - `pending: number` — Migrations restant à appliquer. - `failed: number` — Marqueurs d'échec à lever. - `pendingTags: string[]` — Identités en attente, dans l'ordre d'application. - `drifted: { tag: string; expected: string; actual: string; }[]` — Fichiers modifiés après avoir été appliqués. - `missing: string[]` — Identités enregistrées dont le fichier a disparu. - `entries: IMigrationEntryReport[]` — UNE LIGNE PAR MIGRATION, dans l'ordre d'application — ce que les compteurs ci-dessus agrègent. #### `IMigrationTarget` ```ts interface IMigrationTarget ``` Cible de connexion de l'applicateur. - `dialect: SqlDialect` — Dialecte du connecteur. - `filename?: string` — Fichier SQLite (dialecte `sqlite`). - `url?: string` — URL de connexion DIRECTE (dialectes `postgres` et `mysql`). #### `IMigrationVerdict` ```ts interface IMigrationVerdict ``` Verdict structuré : **la source**, dont la prose n'est qu'un rendu. - `code: MigrationVerdictCode` — Code stable du refus. - `connector: string` — Connecteur concerné. - `source?: string` — Source de migrations concernée, quand le refus en désigne une. - `tag?: string` — Tag concerné, quand le refus en désigne un. - `facts: Record` — Faits constatés, sans mise en forme — de quoi rendre la phrase. - `nextActions: IMigrationAction[]` — Ce qu'il faut faire ensuite, du plus direct au plus assumé. #### `IReportContext` ```ts interface IReportContext ``` Ce que le rendu doit savoir en plus du plan lui-même. - `ddl: string` — Mode de schéma effectif du connecteur. - `divergence?: ISchemaComparison | null` — Les écarts NOMMÉS entre la base et le schéma déclaré, tels que `describeDivergence` les rend — `null` ou absent quand il n'y en a pas. - `divergenceMode?: DivergenceMode` — `migrations.divergence`, tel que la configuration le déclare. - `canReset?: boolean` — `orm:reset` est-elle acceptée dans cet environnement ? - `target?: string` — La base RÉELLEMENT visée, telle que `describeTargetSafely` la désigne — sans identifiant ni mot de passe. - `fromMigrateUrl?: boolean` — La cible vient-elle de `NF_MIGRATE_DATABASE_URL` plutôt que de la configuration du connecteur ? #### `ISchemaComparison` ```ts interface ISchemaComparison ``` Ce que la comparaison a trouvé. - `additive: ISchemaGap[]` — Colonnes manquantes qui acceptent le vide — rattrapables sans rien inventer. - `blocking: ISchemaGap[]` — Colonnes manquantes et OBLIGATOIRES — jamais rattrapées : les poser exigerait d'inventer une valeur pour les lignes existantes, ce qui est une décision métier, pas une décision d'outil. - `missingTables: string[]` — Tables entièrement absentes de la base. #### `ISchemaGap` ```ts interface ISchemaGap ``` Une colonne attendue par le code et absente de la base. - `table: string` — Table concernée, telle qu'elle s'appelle en base. - `column: string` — Colonne attendue. - `type: string` — Type SQL attendu, dans le dialecte du connecteur. - `nullable: boolean` — La colonne accepte-t-elle le vide ? #### `IStyle` ```ts interface IStyle ``` Codes ANSI, neutralisés hors terminal (un `| jq` ne doit rien recevoir). - `bold: (s: string) => string` - `dim: (s: string) => string` - `green: (s: string) => string` - `yellow: (s: string) => string` - `red: (s: string) => string` ### Types (3) #### `IConnectorResolution` ```ts type IConnectorResolution = { kind: "ready"; connector: string; dialect: SqlDialect; target: IMigrationTarget; fromMigrateUrl: boolean; ddl: DdlMode; } | { kind: "unsupported"; connector: string; owner: string; sqlLike: boolean; driver: string; } | { kind: "url-mismatch"; connector: string; dialect: SqlDialect; urlDialect: SqlDialect | null; } | { kind: "unknown"; connector: string; known: string[ … ``` Ce qu'un connecteur est, du point de vue des migrations. #### `MigrationVerdictCode` ```ts type MigrationVerdictCode = "NF_MIGRATE_BASELINE_REQUIRED" | "NF_MIGRATE_FAILED_MARKER" | "NF_MIGRATE_HASH_MISMATCH" | "NF_MIGRATE_OUT_OF_ORDER" | "NF_MIGRATE_MISSING_FILE" | "NF_MIGRATE_UNKNOWN_FORMAT" | "NF_MIGRATE_LOCK_TIMEOUT" | "NF_MIGRATE_UNKNOWN_TAG" | "NF_MIGRATE_UNKNOWN_SOURCE" | "NF_MIGRATE_JOURNAL_MISMATCH" ``` Codes de refus stables de l'applicateur. #### `MigrationVerdictName` ```ts type MigrationVerdictName = "up-to-date" | "pending" | "drift" | "failed" | "adopt" | "divergent" ``` Verdicts possibles — **énumération GELÉE** avec `MIGRATION_FORMAT_VERSION`. --- [← Toutes les références d'API](../../)