Référence d'API — @nodefony/drizzle — migrator

stable

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#

class DrizzleMigrator

• constructor(options: IDrizzleMigratorOptions)
• get connector(): string — Connecteur servi par cet applicateur.
• get dialect(): SqlDialect — Dialecte servi par cet applicateur.
• status(): Promise<IMigrationPlan> — État complet de la migration — lecture seule, sans verrou ni écriture.
• compareToDeclared(expected: readonly IExpectedTable[]): Promise<ISchemaComparison> — Compare la base que VISE cet applicateur aux tables que le code déclare — lecture seule, sans verrou.
• migrate(options?: IMigrateOptions): Promise<IMigrationRun> — Applique les migrations restantes, sous verrou.
• baseline(upTo?: string): Promise<IMigrationApplied[]>
• 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#

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#

function action(command: string): IMigrationAction

Fabrique une action affichable et exécutable.

appMigrationsDir#

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#

function buildMigrator(resolution: Extract<IConnectorResolution, { kind: "ready"; }>, config: IDrizzleConfig, kernel: Kernel | null): Promise<DrizzleMigrator>

Construit l’applicateur d’un connecteur résolu.

buildReport#

function buildReport(plan: IMigrationPlan, ctx: IReportContext): IMigrationReport

Compose la charge utile complète d’un état de migration.

defaultMigrationSources#

function defaultMigrationSources(appDir?: string, options?: { framework?: boolean; connector?: string; }): Promise<IMigrationSource[]>

Registre de sources standard : le framework, puis l’application.

exitCodeOf#

function exitCodeOf(verdict: MigrationVerdictName, divergenceBlocks?: boolean): 0 | 1 | 2

Le code de sortie d’un verdict.

frameworkMigrationsDir#

function frameworkMigrationsDir(): Promise<string>

Dossier des migrations livrées par ce paquet.

knownConnectors#

function knownConnectors(config: IDrizzleConfig): string[]

Tous les noms de connecteurs qui existent, tous ORM confondus.

loadSources#

function loadSources(sources: readonly IMigrationSource[], dialect: SqlDialect): Promise<ILoadedSources>

Charge toutes les sources d’un registre pour un dialecte donné.

meaningOf#

function meaningOf(verdict: MigrationVerdictName): string

Ce que le verdict veut dire — la CAUSE, entre le fait et le geste.

migrationHash#

function migrationHash(content: string): string

Empreinte d’un fichier de migration : normalisée et auto-descriptive.

openMigrationDriver#

function openMigrationDriver(target: IMigrationTarget): Promise<IMigrationDriver>

Ouvre le pilote à connexion unique du dialecte demandé.

orderSources#

function orderSources(sources: readonly IMigrationSource[]): IMigrationSource[]

Ordonne un registre de sources : rang croissant, nom en départage.

readMigrationEnv#

function readMigrationEnv(kernel: Kernel | null): IMigrationEnv

Constate l’environnement depuis le kernel et le processus.

renderRefusal#

function renderRefusal(verdict: IMigrationVerdict, message: string, style: IStyle, ddl?: string): string

Rendu humain d’un REFUS de l’applicateur.

renderStatus#

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#

function resetAllowed(env: IMigrationEnv): boolean

L’effacement d’une base est-il ACCEPTÉ dans cet environnement ?

resolveCheckMode#

function resolveCheckMode(explicit: MigrationCheckMode, env: IMigrationEnv): MigrationCheckMode

La conduite de la sonde de disponibilité face à un schéma en retard.

resolveConnector#

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#

function resolveDdlMode(explicit: DdlMode, env: IMigrationEnv, appHasMigrations?: boolean, volatile?: boolean): DdlMode

Le mode de schéma qui s’applique à un connecteur.

resolveDivergenceMode#

function resolveDivergenceMode(config: IDrizzleConfig): DivergenceMode

Conduite face à la divergence, telle que la configuration la déclare.

styleFor#

function styleFor(tty: boolean): IStyle

Construit le styliste : couleurs en terminal, texte nu ailleurs.

verdictOf#

function verdictOf(plan: IMigrationPlan, divergent?: boolean): MigrationVerdictName

Situation d’ensemble d’un plan, dans l’ordre de gravité.

Constantes (12)#

APP_RANK#

const APP_RANK = 1000000

Rang de la source application : dernière appliquée, toujours.

APP_SOURCE#

const APP_SOURCE = "app"

Nom logique RÉSERVÉ de la source livrée par l’application.

DEFAULT_LOCK_TIMEOUT_MS#

const DEFAULT_LOCK_TIMEOUT_MS = 30000

Délai d’attente du verrou, par défaut.

EXIT#

const EXIT: { readonly ok: 0; readonly actionRequired: 1; readonly error: 2; }

Grille des codes de sortie — figée, jamais réaffectée.

FORMAT_MARKER#

const FORMAT_MARKER = "-- nodefony:migration format=1"

Marqueur de format que porte la première ligne de chaque fichier .sql.

FRAMEWORK_RANK#

const FRAMEWORK_RANK = 0

Rang de la source framework : première appliquée, toujours.

FRAMEWORK_SOURCE#

const FRAMEWORK_SOURCE = "framework"

Nom logique RÉSERVÉ de la source livrée par le framework.

HISTORY_TABLE#

const HISTORY_TABLE = "nodefony_migrations"

Nom de la table d’historique — jamais qualifié d’un schéma.

MIGRATE_URL_ENV#

const MIGRATE_URL_ENV = "NF_MIGRATE_DATABASE_URL"

URL de connexion réservée au travail de migration.

MIGRATION_FORMAT_VERSION#

const MIGRATION_FORMAT_VERSION = 1

Version de la charge utile --json et du plan d’administration.

MYSQL_LOCK_NAME_SQL#

const MYSQL_LOCK_NAME_SQL: string

Expression SQL de l’identité du verrou — évaluée par le SERVEUR.

PG_LOCK_KEY#

const PG_LOCK_KEY: bigint

Clé du verrou consultatif PostgreSQL — figée à vie.

Interfaces (20)#

IAppliedMigration#

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#

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#

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#

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#

interface IMigrationApplied

Résultat de l’application d’une migration.

• source: string
• tag: string
• executionMs: number

IMigrationDrift#

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#

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<void> — Exécute un statement sans résultat.
• query<T extends Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<T[]> — Exécute une requête paramétrée ; les paramètres s’écrivent ?.
• begin(): Promise<void> — Ouvre une transaction (BEGIN IMMEDIATE en sqlite).
• commit(): Promise<void>
• rollback(): Promise<void>
• lock(timeoutMs: number): Promise<void> — Prend le verrou d’applicateur, ou lève au bout de timeoutMs.
• unlock(): Promise<void> — Libère le verrou.
• close(): Promise<void> — Ferme la connexion.

IMigrationEnv#

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#

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:<hex> 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#

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#

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#

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#

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#

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#

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#

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<string, string | number | boolean | readonly string[]> — 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#

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#

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#

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#

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#

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#

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#

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