@spinajs/orm 2.0.486 → 2.0.488

package/lib/cjs/migration-runner.js

@@ -0,0 +1,216 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (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);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MigrationRunner = exports.MIGRATION_FILE_REGEXP = void 0;
+const log_common_1 = require("@spinajs/log-common");
+const luxon_1 = require("luxon");
+const symbols_js_1 = require("./symbols.js");
+const descriptor_js_1 = require("./descriptor.js");
+const exceptions_js_1 = require("./exceptions.js");
+const migration_service_js_1 = require("./migration-service.js");
+/**
+ * Re-exported from `./symbols.js` ( a leaf module ) rather than defined here, so this module can
+ * sit in `Orm`'s require cycle without closing it one hop earlier. This is still the import path
+ * the rest of the package - and `@spinajs/orm-cli` - use, and stays that way.
+ */
+var symbols_js_2 = require("./symbols.js");
+Object.defineProperty(exports, "MIGRATION_FILE_REGEXP", { enumerable: true, get: function () { return symbols_js_2.MIGRATION_FILE_REGEXP; } });
+/**
+ * Cross-connection orchestrator: validates and orders the migration registry, groups it by the
+ * connection each migration declared, and hands each group to that connection's
+ * `OrmMigrationService`. Everything that touches a database lives in the service; everything
+ * that spans connections lives here.
+ */
+class MigrationRunner {
+    constructor(orm) {
+        this.orm = orm;
+    }
+    /**
+     * Applies every pending migration on every configured connection, or only `name` when one is
+     * given, in `(created, name)` order.
+     *
+     * A `name` that matches nothing in the registry throws rather than returning `[]`: an empty
+     * result from a typo is indistinguishable from "already up to date", so the CLI would exit 0
+     * reporting "0 migrations applied" and the operator would believe the schema is current.
+     */
+    async up(name, options) {
+        const executed = [];
+        for (const [driver, units] of this.plan(name, options?.force ?? true, options?.connection)) {
+            const service = await this.service(driver);
+            executed.push(...(await service.up(units, { fake: options?.fake })));
+        }
+        return executed;
+    }
+    /**
+     * Rolls the last applied batch back on every configured connection, or every batch with
+     * `{ all: true }`. `name` narrows the run to a single migration and - exactly like `up` - throws
+     * when the registry carries nothing by that name.
+     *
+     * KNOWN SHARP EDGE, `down(name)`: the service is handed a one-element unit list, and it treats
+     * every applied row in the target batch that has no matching unit as an orphan. So a named
+     * rollback warns that perfectly healthy, merely-unrequested migrations are "recorded as applied
+     * but no registered migration matches them (file deleted or renamed)" and advises restoring the
+     * file or removing the row by hand - guidance that is destructive if followed here, because
+     * nothing is actually wrong with those rows. The rollback itself is correct; only the warning
+     * lies. Fixing it means giving `IMigrationDownOptions` an "only these" notion, i.e. reshaping the
+     * service contract, so it is deliberately not done inside this facade.
+     */
+    async down(name, options) {
+        const executed = [];
+        for (const [driver, units] of this.plan(name, options?.force ?? true, options?.connection)) {
+            const service = await this.service(driver);
+            executed.push(...(await service.down(units, { fake: options?.fake, all: options?.all })));
+        }
+        return executed;
+    }
+    async status() {
+        const entries = [];
+        // force: a status report that hid the connections with OnStartup off would answer "nothing
+        // to see" for exactly the connections somebody is most likely asking about
+        for (const [driver, units] of this.plan(undefined, true)) {
+            const service = await this.service(driver);
+            entries.push(...(await service.status(units)));
+        }
+        return entries;
+    }
+    /**
+     * Forces a migration's recorded state on whichever connection owns it - the escape hatch for a
+     * run that died halfway. The unit is handed down as well: the service cannot fingerprint a
+     * migration it was only given the name of, and a resolution without it leaves `Checksum` NULL
+     * forever, so drift is never detectable for that row again.
+     */
+    async resolve(name, action) {
+        for (const [driver, units] of this.plan(name, true)) {
+            const unit = units.find((u) => u.name === name);
+            if (unit) {
+                return await (await this.service(driver)).resolve(name, action, unit);
+            }
+        }
+        // `plan()` already refused an unknown name, so reaching here means the class IS registered and
+        // `plan()` dropped it: the connection it declared is missing from this deployment's
+        // configuration, or it carries no `@Migration()` at all. Both left a warn naming it. Silently
+        // doing nothing would look like a successful resolve and leave the connection blocked
+        throw new exceptions_js_1.OrmException(`Migration ${name} is registered, but its connection is not configured ( or the class carries no @Migration('connection') decorator ) - nothing to resolve`);
+    }
+    /**
+     * The connection's configured `OrmMigrationService`, or the built-in one.
+     */
+    async service(driver) {
+        const token = driver.Options.Migration?.Service;
+        return await driver.Container.resolve((token ?? migration_service_js_1.DefaultMigrationService), [driver]);
+    }
+    /**
+     * Validates every registered migration's name, orders the set, and groups it by the connection
+     * it declared - returning one ordered unit list per connection that is actually going to run.
+     *
+     * Keyed by driver rather than by connection name so aliases ( two names bound to the same
+     * `OrmDriver` ) collapse into one group instead of running the same migration twice.
+     *
+     * `name` narrows the set to one migration, and is the single place all three public entry
+     * points get their "that name is not registered" refusal from. `connection` narrows it to one
+     * connection - the two compose, and a `name` on a connection the filter excludes runs nothing.
+     */
+    plan(name, force, connection) {
+        // `ClassInfo.name` is the migration's identity everywhere else in the system - it is what the
+        // filter below matches, what becomes `IMigrationUnit.name`, and what lands in the `Migration`
+        // column the service compares its rows against. So `m.name` ( never `m.type.name`, which
+        // `Orm.registerMigration` copies it from and which is therefore only *usually* the same ) is
+        // what gets validated, reported and recorded here - one value, so the three cannot disagree.
+        const source = name ? this.orm.Migrations.filter((m) => m.name === name) : this.orm.Migrations;
+        // an explicitly named migration that matches nothing is a typo, not an empty run. Returning
+        // [] would let `migrate-up --name Ceate_2021_01_01_00_00_00` exit 0 reporting "0 migrations
+        // applied", leaving the operator believing the schema is current - the same reason `resolve()`
+        // refuses to no-op below
+        if (name && source.length === 0) {
+            throw new exceptions_js_1.OrmException(`Migration ${name} is not registered - check the name for typos`);
+        }
+        const units = source
+            .map((m) => {
+            const match = m.name.match(symbols_js_1.MIGRATION_FILE_REGEXP);
+            const created = match && match.length === 3 ? luxon_1.DateTime.fromFormat(match[2], 'yyyy_MM_dd_HH_mm_ss') : null;
+            // a migration whose name carries no timestamp cannot be placed in the order, and a
+            // half-ordered run applies schema changes in an order nobody described - so the whole
+            // set is refused rather than the one entry skipped
+            if (!created || !created.isValid) {
+                throw new exceptions_js_1.OrmException(`Migration ${m.name} has invalid name format - expected some_name_yyyy_MM_dd_HH_mm_ss`);
+            }
+            return { name: m.name, created, type: m.type };
+        })
+            // timestamp first, then name: two migrations generated in the same second are otherwise
+            // ordered by whatever the registry happened to hold, which differs between a file-scan
+            // boot and a programmatic registration. Equal on both = 0, so the sort stays stable
+            .sort((a, b) => (a.created < b.created ? -1 : a.created > b.created ? 1 : a.name.localeCompare(b.name)));
+        // Resolved to a DRIVER rather than compared as a string, because that is what the groups
+        // below are keyed by: `db.Aliases` binds several names to one `OrmDriver`, so
+        // `--connection <alias>` and `--connection <the name it points at>` have to select the same
+        // group. Comparing the migration's declared `@Migration('...')` name instead would make those
+        // two filters disagree about a connection that is one connection.
+        let only;
+        if (connection !== undefined) {
+            only = this.orm.Connections.get(connection);
+            // refused for the same reason an unregistered migration name is: a filter that matches
+            // nothing would let `migrate-up --connection typo` exit 0 reporting "0 migrations applied",
+            // and the operator would believe the schema is current
+            if (!only) {
+                throw new exceptions_js_1.OrmException(`Connection ${connection} is not configured - check the name for typos ( configured: ${[...this.orm.Connections.keys()].join(', ') || 'none'} )`);
+            }
+        }
+        const groups = new Map();
+        const gated = new Set();
+        for (const u of units) {
+            // chain-walking, deliberately: a subclass is still the same migration on the same
+            // connection whether or not it re-declares @Migration() - unlike Env ( own-only, see
+            // Orm.discoverMigrations() ), Connection is meant to be inherited.
+            const md = (0, descriptor_js_1.extractMigrationDescriptor)(u.type);
+            // none of the three skips below throws: a connection missing from this deployment's
+            // configuration, or switched off for startup, is a normal state - taking the whole boot
+            // down over it would be worse than running what can be run
+            if (!md?.Connection) {
+                this.Log.warn(`Migration ${u.name} has no connection assigned ( missing @Migration('connection') decorator ) and is skipped`);
+                continue;
+            }
+            const driver = this.orm.Connections.get(md.Connection);
+            if (!driver) {
+                this.Log.warn(`Connection ${md.Connection} not exists for migration ${u.name} - migration is skipped`);
+                continue;
+            }
+            // silently, and before the OnStartup gate below: the operator asked for one connection, so
+            // a line per migration on every OTHER connection is noise, and the gate warning in
+            // particular would name connections this run was never going to touch
+            if (only && driver !== only) {
+                continue;
+            }
+            if (!driver.Options.Migration?.OnStartup && !force) {
+                // the gate belongs to the connection, not to the migration, so it is reported once -
+                // repeating it per migration turns a boot log into noise nobody reads
+                if (!gated.has(driver)) {
+                    gated.add(driver);
+                    this.Log.warn(`Migration for connection ${md.Connection} is disabled on startup, please check conf file for db.[connection].Migration.OnStartup property`);
+                }
+                continue;
+            }
+            const group = groups.get(driver);
+            if (group) {
+                group.push(u);
+            }
+            else {
+                groups.set(driver, [u]);
+            }
+        }
+        return [...groups.entries()];
+    }
+}
+exports.MigrationRunner = MigrationRunner;
+__decorate([
+    (0, log_common_1.Logger)('ORM'),
+    __metadata("design:type", log_common_1.Log)
+], MigrationRunner.prototype, "Log", void 0);
+//# sourceMappingURL=migration-runner.js.map

package/lib/cjs/migration-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-runner.js","sourceRoot":"","sources":["../../src/migration-runner.ts"],"names":[],"mappings":"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"}

package/lib/cjs/migration-service.d.ts

@@ -0,0 +1,300 @@
+import { Class } from '@spinajs/di';
+import { Log } from '@spinajs/log-common';
+import { DateTime } from 'luxon';
+import type { TableQueryBuilder } from './builders.js';
+import { OrmDriver } from './driver.js';
+import { MigrationTransactionMode, OrmMigration } from './interfaces.js';
+export declare const MIGRATION_TABLE_NAME = "spinajs_migration";
+export declare const MIGRATION_LOCK_POLL_INTERVAL = 500;
+export declare const MIGRATION_LOCK_TIMEOUT = 30000;
+export declare const MIGRATION_LOCK_STALE_AFTER = 600000;
+/**
+ * How many times one `acquireLock()` call may remove a lock row it judged stale. A steal is
+ * not proof the row is gone - a DELETE can succeed and remove nothing - so without a cap the
+ * stale branch is free to warn and retry forever.
+ */
+export declare const MIGRATION_LOCK_MAX_STEALS = 3;
+export type MigrationResolveAction = 'applied' | 'rolled-back';
+/**
+ * One row of the migration tracking table.
+ */
+export interface IMigrationRecord {
+    Migration: string;
+    CreatedAt: Date;
+    StartedAt: Date;
+    FinishedAt: Date | null;
+    RolledBackAt: Date | null;
+    Logs: string | null;
+    Checksum: string | null;
+    Batch: number;
+}
+/**
+ * A migration class paired with the timestamp parsed out of its name.
+ */
+export interface IMigrationUnit {
+    name: string;
+    created: DateTime;
+    type: Class<OrmMigration>;
+}
+export interface IMigrationRunOptions {
+    /**
+     * Record the migration as applied without running its `up()`.
+     */
+    fake?: boolean;
+}
+export interface IMigrationDownOptions extends IMigrationRunOptions {
+    /**
+     * Roll every applied migration back instead of only the last batch.
+     */
+    all?: boolean;
+}
+export interface IMigrationStatusEntry {
+    name: string;
+    connection: string;
+    applied: boolean;
+    failed: boolean;
+    rolledBack: boolean;
+    pending: boolean;
+    /**
+     * The row was opened by a run that never reached either outcome: `StartedAt` is set while both
+     * `FinishedAt` and `Logs` are NULL, and no run is currently holding the migration lock. A
+     * process killed between the start and the outcome ( OOM, SIGKILL, a lost connection that took
+     * the failure write down with it ) leaves exactly this.
+     *
+     * Orthogonal to `pending`, like `rolledBack`: such a migration IS pending and the next `up()`
+     * WILL re-run it from the top. What the flag adds is that nobody knows how much of it already
+     * reached the database. It never blocks a run - see `warnOnInterrupted` for why.
+     */
+    interrupted: boolean;
+    batch: number | null;
+    startedAt: Date | null;
+    finishedAt: Date | null;
+    checksumMismatch: boolean;
+}
+/**
+ * Fingerprint of a migration's source, used to detect a migration that was edited
+ * after it had already been applied.
+ */
+export declare function migrationChecksum(type: Class<OrmMigration>): string;
+/**
+ * Per-connection migration execution contract. Configure an alternative
+ * implementation with db.Connections[n].Migration.Service (DI token).
+ */
+export declare abstract class OrmMigrationService {
+    protected driver: OrmDriver;
+    constructor(driver: OrmDriver);
+    /**
+     * Creates or upgrades the tracking tables this connection needs.
+     *
+     * NOTE on what is NOT here: `applied()`. It was part of this contract and had no production
+     * caller - `status()` answers "what is applied", per unit and per connection, and is what the
+     * runner, the CLI and every deploy gate go through. An abstract method that every custom
+     * implementation must write and nothing ever calls is a tax with no payer, so it is a concrete
+     * helper on `DefaultMigrationService` instead.
+     */
+    abstract ensureStorage(): Promise<void>;
+    abstract up(units: IMigrationUnit[], options?: IMigrationRunOptions): Promise<OrmMigration[]>;
+    abstract down(units: IMigrationUnit[], options?: IMigrationDownOptions): Promise<OrmMigration[]>;
+    abstract status(units: IMigrationUnit[]): Promise<IMigrationStatusEntry[]>;
+    /**
+     * Forces a migration's recorded state without running it - the escape hatch for a
+     * run that died halfway and left the table lying.
+     *
+     * `unit` is optional so callers that only know a name (the CLI, the runner facade) keep
+     * working; passing it lets an `'applied'` resolution stamp the checksum as a real run would.
+     */
+    abstract resolve(name: string, action: MigrationResolveAction, unit?: IMigrationUnit): Promise<void>;
+}
+export declare class DefaultMigrationService extends OrmMigrationService {
+    protected Log: Log;
+    protected get table(): string;
+    protected get lockTable(): string;
+    /**
+     * Creates `name` unless it is already there, tolerating a second process that creates it in
+     * the window between the probe and the CREATE.
+     *
+     * That window cannot be closed with a lock: the lock table is one of the tables being created
+     * here, so it cannot guard its own creation. Two processes booting together therefore both see
+     * "absent" and both issue a CREATE, and the loser must not take the whole boot down with it.
+     * Only a table that really is present afterwards excuses the failure - anything else ( no
+     * permission, bad DDL, dead connection ) is a genuine error and is rethrown.
+     *
+     * Returns true when the table was *absent at probe time* - which is not the same as "this
+     * process created it", since the lost-race path returns true too. Callers use it to skip the
+     * legacy upgrade path: a table that appeared inside the race window was created by a peer
+     * running this same DDL, so it already carries the current shape.
+     */
+    protected createTableIfAbsent(name: string, columns: (t: TableQueryBuilder) => void): Promise<boolean>;
+    ensureStorage(): Promise<void>;
+    protected records(): Promise<IMigrationRecord[]>;
+    /**
+     * Fills the columns the upgrade above has just added. A row written before they existed carries
+     * nothing but `CreatedAt`, and a NULL `FinishedAt` reads as "never applied" - so without this
+     * every migration the deployment ran years ago would run again over a schema that already has
+     * it. `CreatedAt` is the only timestamp such a row has, so it is treated as both start and
+     * finish.
+     *
+     * Row by row through the update builder rather than as three set-based `UPDATE`s, and that is
+     * the point of the method: a set-based statement has to name the table itself, and the only
+     * way to do that here is raw SQL. `Migration.Table` is configuration - a name that needs
+     * quoting ( a reserved word, a dot, a space ) would then break this path alone, and only on a
+     * deployment that already has rows, which is the least reachable corner in the file. The
+     * builder quotes it exactly as every other statement in this class does. The cost is one UPDATE
+     * per legacy row, on the single boot that performs the upgrade and never again.
+     */
+    protected backfillLegacyRows(): Promise<void>;
+    /**
+     * Migrations that finished successfully and were not rolled back - the raw rows, unmerged with
+     * the registry.
+     *
+     * A convenience on this class rather than part of `OrmMigrationService`: nothing in the ORM,
+     * the runner or the CLI calls it, because they all need the registry merged in and go through
+     * `status()`. It is kept because a subclass, a script or a health check reaching for "what does
+     * this connection think it has applied?" should not have to reimplement the applied-gate, and
+     * getting that gate subtly wrong ( "a row exists" rather than the FinishedAt NOT NULL and
+     * RolledBackAt NULL pair ) is the classic way to re-run a migration.
+     */
+    applied(): Promise<IMigrationRecord[]>;
+    /**
+     * Opens a migration's row: a fresh one, or a reset of whatever a previous failed or
+     * rolled-back attempt left behind.
+     */
+    protected upsertStart(name: string, existing: IMigrationRecord | undefined): Promise<void>;
+    /**
+     * Closes a migration's row as applied. The batch number is stamped here rather than at
+     * insert time, so a row that never finishes carries no batch to be rolled back later.
+     */
+    protected markFinished(name: string, batch: number, checksum: string): Promise<void>;
+    /**
+     * Records why a migration died. Failed state is `FinishedAt` NULL *and* `Logs` set - the pair
+     * `assertNoFailed` matches on - so this write establishes both rather than assuming the row
+     * already carries a NULL `FinishedAt`.
+     *
+     * It cannot assume it: a migration that was applied and later rolled back is pending again
+     * while still holding the old `FinishedAt`/`RolledBackAt` timestamps, and the reset
+     * `upsertStart` issued for the retry is inside the transaction that just unwound. Writing only
+     * `Logs` would leave `FinishedAt` set, and a half-applied migration would slip past the block.
+     */
+    protected markFailed(name: string, err: Error): Promise<void>;
+    /**
+     * A half-applied migration means the database is in a state nobody described. Refuse to
+     * pile more schema changes on top of it.
+     */
+    protected assertNoFailed(records: IMigrationRecord[]): void;
+    /**
+     * The shape of a row whose run never reached an outcome: `StartedAt`, written by `upsertStart`,
+     * and neither of the two writes that close it - `markFinished`'s `FinishedAt` or `markFailed`'s
+     * `Logs`. Nothing in this class produces it deliberately; a process killed between the start and
+     * the outcome does.
+     *
+     * `RolledBackAt` is excluded on purpose. `resolve('rolled-back')` also leaves `FinishedAt` and
+     * `Logs` NULL with `StartedAt` set, and that row is pending because somebody said so - not
+     * abandoned.
+     *
+     * The predicate says nothing about how much of the migration reached the database. It says only
+     * that nobody recorded the answer, which is exactly why it is worth surfacing.
+     */
+    protected isInterrupted(rec: IMigrationRecord): boolean;
+    /**
+     * Is a migration run in flight on this connection right now? Read, never acquired: the caller is
+     * `status()`, which must not block behind the run it is reporting on.
+     *
+     * The lock row is the only honest signal available, and it is judged exactly as `acquireLock`
+     * judges it - a row younger than `StaleAfter` means somebody is inside a run, an older one means
+     * the holder is presumed dead. Freshness rather than mere presence is what makes this usable
+     * here: a process killed mid-migration leaves BOTH its open tracking row and its lock row
+     * behind, so "a lock row exists" would hide every crash this is meant to surface, permanently.
+     *
+     * Two deliberate consequences. For `StaleAfter` after a crash the answer is "running" and the
+     * open row is not yet reported as interrupted - the same window in which `acquireLock` still
+     * waits for the holder, and with the same client-clock caveat documented there. And
+     * `Lock.Enabled: false` removes the signal altogether, so the answer is "not running": an open
+     * row then always reads as interrupted, which is right for the crash and wrong only for a report
+     * taken while a run is genuinely in progress.
+     */
+    protected runInProgress(): Promise<boolean>;
+    /**
+     * Warns about every migration this run is about to re-run whose row says a previous attempt was
+     * started and never closed. No lock check is needed here, unlike in `status()`: this runs inside
+     * `withLock`, so the only run in flight on this connection is this one.
+     *
+     * It warns rather than blocks, and that is a judgement call worth stating. The row records that
+     * a run STARTED, not that anything reached the database, so blocking would escalate "unknown" to
+     * "refuse to migrate" - and it would do so for the common, harmless shapes too: an idempotent
+     * `CREATE TABLE` that had not run yet, or any migration on a `PerMigration` / `PerRun`
+     * connection, whose transaction unwound the partial work when the process died. In those cases
+     * re-running from the top is exactly right, and a block would turn every OOM kill during a long
+     * migration into an operator ticket.
+     *
+     * The case that is genuinely dangerous is `Transaction.Mode: None` ( the default ) plus
+     * non-idempotent DML: half the INSERTs are already in, nothing recorded which half, and the
+     * re-run applies them again. Non-idempotent DDL is the recoverable version of the same thing -
+     * it fails, and the failed row then blocks properly. Neither is detectable from here, so the
+     * warning describes them and leaves the decision with the operator, who is also the only party
+     * that can look at the data.
+     */
+    protected warnOnInterrupted(records: IMigrationRecord[], pending: IMigrationUnit[]): void;
+    protected transactionMode(): MigrationTransactionMode;
+    /**
+     * True when this migration must run outside any wrapping transaction ( TypeORM parity:
+     * `public transaction = false` on the migration class - needed for DDL that cannot be
+     * transacted, such as MySQL index rebuilds ).
+     *
+     * That declaration is an *instance* field, assigned in the constructor, so it never reaches
+     * the prototype - the resolved instance is the only place it can be read from. A prototype
+     * getter or a static property is honoured too, so a migration may also opt out without
+     * being constructed.
+     */
+    protected optedOutOfTransaction(u: IMigrationUnit, instance?: OrmMigration): boolean;
+    /**
+     * Advisory only: transpilation differences move the checksum as readily as an edit does,
+     * so this warns and never blocks.
+     */
+    protected warnOnChecksumDrift(u: IMigrationUnit, records: IMigrationRecord[]): void;
+    protected lockOptions(): {
+        enabled: boolean;
+        timeout: number;
+        staleAfter: number;
+    };
+    /**
+     * Identity written into the lock row. It exists to answer "who is holding this?" when a run
+     * blocks, so it has to survive being read on another machine.
+     */
+    protected lockOwner(): string;
+    /**
+     * Takes the single row of the lock table, waiting for whoever has it.
+     *
+     * The row is claimed by INSERT rather than by "SELECT then INSERT": `Id` is unique, so the
+     * database decides the winner in one statement and two processes racing here cannot both
+     * succeed. A refused insert is therefore read as "somebody else holds it" - which is also why
+     * the holder is re-read afterwards rather than guessed at.
+     *
+     * Staleness is judged against the *client* clock: `AcquiredAt` is written here as
+     * `new Date()` and compared to this host's `Date.now()`. That is sound for the case this
+     * lock is built for - one process migrating, crashing, and restarting to find its own
+     * abandoned row - but on hosts whose clocks disagree the window is off by the skew, which
+     * shows up as stealing too early or waiting too long. Stamping `AcquiredAt` from the
+     * database ( a driver-level `CURRENT_TIMESTAMP` default and a server-side comparison ) would
+     * remove the assumption; it needs dialect support that does not exist here yet.
+     */
+    protected acquireLock(): Promise<void>;
+    /**
+     * Drops the lock row unconditionally rather than only the row this process wrote. A run whose
+     * lock was stolen as stale would otherwise have nothing to release, and the alternative -
+     * deleting only `Owner = ours` - leaves the table holding a row nobody will clear if the owner
+     * string ever changes underneath a run. Losing a stolen lock is the lesser harm: the thief
+     * already assumed the run was dead.
+     */
+    protected releaseLock(): Promise<void>;
+    /**
+     * Concurrency guard around a whole run: one migration run per connection at a time, across
+     * processes. Note the release is `finally` - a run that throws must not leave the connection
+     * locked until the staleness window expires.
+     */
+    protected withLock<R>(fn: () => Promise<R>): Promise<R>;
+    up(units: IMigrationUnit[], options?: IMigrationRunOptions): Promise<OrmMigration[]>;
+    down(units: IMigrationUnit[], options?: IMigrationDownOptions): Promise<OrmMigration[]>;
+    status(units: IMigrationUnit[]): Promise<IMigrationStatusEntry[]>;
+    resolve(name: string, action: MigrationResolveAction, unit?: IMigrationUnit): Promise<void>;
+}
+//# sourceMappingURL=migration-service.d.ts.map

package/lib/cjs/migration-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-service.d.ts","sourceRoot":"","sources":["../../src/migration-service.ts"],"names":[],"mappings":"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"}