@lenne.tech/nest-server 11.43.3 → 12.1.0

package/src/core/modules/migrate/migration-state-store.interface.ts

@@ -0,0 +1,24 @@
+/**
+ * Where `MigrationRunner` and the `migrate` CLI keep the applied migrations: `MongoStateStore` on MongoDB,
+ * `SqlStateStore` on PostgreSQL, MySQL and MariaDB. Types only.
+ */
+export interface MigrationSet {
+  down?: (done?: (err?: Error) => void) => void;
+  lastRun?: string;
+  migrations: Array<{ timestamp?: number; title: string }>;
+  up: (done?: (err?: Error) => void) => void;
+}
+
+export interface MigrationStateStore {
+  /** Callback API of the `migrate` package */
+  load(fn: (err?: Error, set?: MigrationSet) => void): void;
+  loadAsync(): Promise<MigrationSet>;
+  /** Callback API of the `migrate` package */
+  save(set: MigrationSet, fn: (err?: Error) => void): void;
+  saveAsync(set: MigrationSet): Promise<void>;
+  /**
+   * Run `fn` while holding the store's migration lock, so concurrent runs of several replicas apply each migration
+   * once. A store without a lock runs `fn` unsynchronized.
+   */
+  withLock?<T>(fn: () => Promise<T>): Promise<T>;
+}

package/src/core/modules/migrate/migration.helper.ts

@@ -0,0 +1,335 @@
+import * as fs from 'fs';
+import type { Db, MongoClient, ObjectId } from 'mongodb';
+import * as path from 'path';
+
+import { callerDirectory } from '../../common/helpers/module-location.helper.js';
+import type { MigrationStateStore } from './migration-state-store.interface.js';
+import { MongoStateStore } from './mongo-state-store.js';
+import { SqlStateStore } from './sql-state-store.js';
+import { requireMongoPackages } from '../../common/persistence/mongo/mongo-packages.js';
+
+/**
+ * Migration helper functions for database operations
+ */
+
+// Store active connections for auto-cleanup
+const activeConnections = new Set<MongoClient>();
+
+// Track if we're in a migration context
+let inMigrationContext = false;
+
+/**
+ * Mark the start of a migration
+ * @internal Used by migration runner
+ */
+export const _startMigration = () => {
+  inMigrationContext = true;
+};
+
+/**
+ * Mark the end of a migration and close all connections
+ * @internal Used by migration runner
+ */
+export const _endMigration = async () => {
+  inMigrationContext = false;
+  // Close all active connections
+  const promises = Array.from(activeConnections).map((client) => client.close());
+  activeConnections.clear();
+  await Promise.all(promises);
+};
+
+/**
+ * Get database connection
+ *
+ * When used in migrations, connections are automatically closed after the migration completes.
+ * For manual usage outside migrations, you must close the connection manually.
+ *
+ * @param mongoUrl - MongoDB connection URI
+ * @returns Promise with database instance
+ *
+ * @example
+ * ```typescript
+ * // In migrations - connection auto-closes after migration
+ * const db = await getDb('mongodb://localhost/mydb');
+ * await db.collection('users').updateMany(...);
+ *
+ * // Outside migrations - must close manually
+ * const db = await getDb('mongodb://localhost/mydb');
+ * try {
+ *   await db.collection('users').updateMany(...);
+ * } finally {
+ *   await db.client.close();
+ * }
+ * ```
+ */
+export const getDb = async (mongoUrl: string): Promise<Db> => {
+  const client: MongoClient = await mongoDriver().MongoClient.connect(mongoUrl);
+
+  // Track connection for auto-cleanup in migrations
+  if (inMigrationContext) {
+    activeConnections.add(client);
+  }
+
+  return client.db();
+};
+
+/**
+ * Throw unless every chunk of a stored GridFS file is present.
+ *
+ * A GridFS upload is not one write but many: N chunk documents plus the files
+ * document that describes them. The write stream's `'finish'` event says the
+ * stream ended — it does not prove every chunk is durably there, and a
+ * connection that goes away at the wrong moment can leave a files document
+ * behind that promises more bytes than exist. The upload then "succeeds", the
+ * caller stores the id, and the defect only surfaces much later as a broken
+ * download from a record that looks perfectly healthy.
+ *
+ * Counts documents rather than reading bytes, so a chunk that was written but
+ * truncated still passes. Catching that would mean streaming the whole file
+ * back on every upload; the cheap count catches the failure that actually
+ * occurs (a missing chunk) and is index-only via the GridFS default index.
+ *
+ * @param db - Database holding the bucket
+ * @param bucketName - GridFS bucket name, i.e. the prefix of `<bucket>.files` / `<bucket>.chunks`
+ * @param id - `_id` of the files document
+ * @param label - Optional human-readable name for the error message; defaults to the id
+ * @throws Error if the files document is missing or fewer chunks are stored than its length implies
+ *
+ * @example
+ * ```typescript
+ * await assertGridFsFileComplete(db, 'images', fileId, 'logo.png');
+ * ```
+ */
+export const assertGridFsFileComplete = async (
+  db: Db,
+  bucketName: string,
+  id: ObjectId,
+  label?: string,
+): Promise<void> => {
+  const name = label || String(id);
+  const fileDoc = await db.collection(`${bucketName}.files`).findOne({ _id: id });
+  if (!fileDoc) {
+    throw new Error(`GridFS file '${name}' has no file document (id ${String(id)})`);
+  }
+
+  const chunkSize: number = fileDoc.chunkSize || 255 * 1024;
+  // NO `Math.max(1, …)` floor here: GridFS stores ZERO chunk documents for a
+  // zero-byte file — the driver's `writeRemnant()` returns early on `pos === 0`
+  // rather than inserting an empty chunk. A floor of 1 would reject every
+  // legitimately empty asset, and because the container entrypoint defaults to
+  // `MIGRATE_FAILURE_POLICY=abort`, that failure would keep the server from
+  // starting at all.
+  const expected = Math.ceil((fileDoc.length || 0) / chunkSize);
+  const actual = await db
+    .collection(`${bucketName}.chunks`)
+    // Read from the primary: this is a read-your-own-write, and a URI carrying
+    // `readPreference=secondaryPreferred` would otherwise fail a healthy upload
+    // against a secondary that has not caught up yet.
+    .countDocuments({ files_id: id }, { readPreference: 'primary' });
+  if (actual < expected) {
+    throw new Error(`GridFS file '${name}' is incomplete: ${actual} of ${expected} chunks stored (id ${String(id)})`);
+  }
+};
+
+/**
+ * The file `uploadFileToGridFS()` reads: an absolute path as given; a relative one against the calling migration's
+ * directory, or — when nothing exists there — against this helper's own directory, which is where it was resolved
+ * until 12.0.0 (a vendored project may have adapted its paths to that).
+ */
+function resolveMigrationFilePath(relativePath: string, callerDir: string): string {
+  if (!relativePath || path.isAbsolute(relativePath)) {
+    return relativePath;
+  }
+  const fromCaller = path.resolve(callerDir, relativePath);
+  if (fs.existsSync(fromCaller)) {
+    return fromCaller;
+  }
+  // Until 12.0.0 this file lived in `helpers/`, and relative paths were anchored there — keep that anchor exact.
+  const legacy = path.resolve(callerDirectory(), 'helpers', relativePath);
+  return fs.existsSync(legacy) ? legacy : fromCaller;
+}
+
+/**
+ * Upload file to GridFS
+ *
+ * Resolves only once the upload is verified complete (see
+ * {@link assertGridFsFileComplete}); rejects — rather than hanging — when the
+ * source file cannot be read. Closes its own connection either way.
+ *
+ * @param mongoUrl - MongoDB connection URI
+ * @param relativePath - Path to the file: absolute, or relative to the directory of the file that calls this
+ *   function (the migration). Until 12.0.0 a relative path was resolved against THIS helper's directory — inside
+ *   `node_modules/@lenne.tech/nest-server/…` in npm mode; that location is still tried second.
+ * @param options - Optional bucket name and filename
+ * @returns Promise with ObjectId of uploaded file
+ * @throws Error if the source cannot be read, or if the stored file is incomplete
+ *
+ * @example
+ * ```typescript
+ * const fileId = await uploadFileToGridFS(
+ *   'mongodb://localhost/mydb',
+ *   '../assets/image.png',
+ *   { bucketName: 'images', filename: 'logo.png' }
+ * );
+ * ```
+ */
+export const uploadFileToGridFS = async (
+  mongoUrl: string,
+  relativePath: string,
+  options?: { bucketName?: string; filename?: string },
+): Promise<ObjectId> => {
+  // Before the first `await`: the calling migration's frame is gone after it.
+  const sourcePath = resolveMigrationFilePath(relativePath, relativePath ? callerDirectory(1) : '');
+  if (!relativePath) {
+    throw new Error('relativePath is required');
+  }
+
+  const { bucketName, filename } = {
+    bucketName: 'fs',
+    filename: relativePath.split('/')[relativePath.split('/').length - 1],
+    ...options,
+  };
+
+  const client = await mongoDriver().MongoClient.connect(mongoUrl);
+  // Registered unconditionally — unlike `getDb()`, which only registers inside a
+  // migration context. This client is always ours to close, so `_endMigration()`
+  // stays a backstop for the case where the upload throws before `settle()` runs.
+  activeConnections.add(client);
+
+  const db = client.db();
+  const bucket = new (mongoDriver().GridFSBucket)(db, { bucketName });
+  const writeStream = bucket.openUploadStream(filename);
+
+  const readStream = fs.createReadStream(sourcePath);
+  const rs = readStream.pipe(writeStream);
+
+  /**
+   * Read errors need their own handler — `pipe()` does not forward them.
+   *
+   * An unreadable source (missing file, wrong path inside a container image)
+   * emits on the READ stream, where nothing was listening: the write stream
+   * never finished, the promise below never settled, and the migration hung
+   * until something else timed out. Destroying the write stream routes it into
+   * the rejection path so the caller sees the actual cause.
+   */
+  readStream.on('error', (err) => {
+    writeStream.destroy(err);
+  });
+
+  /**
+   * Close the connection before settling.
+   *
+   * This client used to be opened and never closed, and it was not registered
+   * either — so `_endMigration()` could not reach it. Every uploaded file left a
+   * live connection behind, and a live connection keeps an SDAM monitor timer
+   * alive, which keeps the Node event loop busy: `migrate up` finished its work,
+   * printed "All migrations completed successfully" and then never exited. That
+   * is invisible on a developer machine and blocks a CI job until its timeout.
+   *
+   * A failing `close()` must never become the error the caller sees: the reason
+   * the upload ended is what matters, and the settle path is also reached while
+   * rejecting. So the close error is logged and swallowed, and `settled` keeps a
+   * second call (success path falling into `.catch`) from closing twice.
+   */
+  let settled = false;
+  const settle = async <T>(action: () => T): Promise<T> => {
+    if (!settled) {
+      settled = true;
+      try {
+        await client.close();
+      } catch (closeErr) {
+        console.warn('Failed to close migration connection:', closeErr);
+      } finally {
+        activeConnections.delete(client);
+      }
+    }
+    return action();
+  };
+
+  return new Promise<ObjectId>((resolve, reject) => {
+    rs.on('finish', () => {
+      const id = writeStream.id as ObjectId;
+      // Verify BEFORE closing: the check needs the same open client, and a
+      // failure has to reject rather than hand back an id that points at nothing.
+      assertGridFsFileComplete(db, bucketName, id, filename)
+        .then(() => settle(() => id))
+        .then(resolve)
+        .catch((err: unknown) => {
+          // Drop the incomplete file, otherwise every re-run of the migration
+          // leaves another orphaned files document (plus its partial chunks)
+          // behind, since a retry uploads under a fresh ObjectId.
+          void bucket
+            .delete(id)
+            .catch(() => undefined)
+            .then(() => settle(() => undefined))
+            .finally(() => reject(err));
+        });
+    });
+
+    rs.on('error', (err) => {
+      void settle(() => undefined).finally(() => reject(err));
+    });
+  });
+};
+
+/**
+ * Create a migration state store factory
+ *
+ * The lock collection is set by DEFAULT, so `migrate up` from N replicas booting at
+ * the same time serializes instead of applying the same migration twice (the container
+ * entrypoint runs migrations on every boot). Pass an empty string to opt out.
+ *
+ * @param databaseUrl - MongoDB connection URI, or the PostgreSQL / MySQL / MariaDB URL of the table owner (`database.ownerUrl`)
+ * @param collectionName - Optional collection name (default: 'migrations'; on SQL the table `lt_migrations`)
+ * @param lockCollectionName - Lock collection name (default: 'migrations_lock'); `''` disables locking
+ * @returns A state store class (MongoStateStore or SqlStateStore) that can be used with the migrate CLI
+ *
+ * @example
+ * ```typescript
+ * // In migrations-utils/migrate.js:
+ * const { createMigrationStore } = require('@lenne.tech/nest-server');
+ * const config = require('../src/config.env');
+ *
+ * module.exports = createMigrationStore(config.default.mongoose.uri);
+ * // A project whose default source is PostgreSQL:
+ * // module.exports = createMigrationStore(process.env.NSC__DATABASE__OWNER_URL);
+ * ```
+ */
+export const createMigrationStore = (
+  databaseUrl: string,
+  collectionName: string = 'migrations',
+  lockCollectionName: string = 'migrations_lock',
+  // Explicit return type: the returned class is anonymous to the declaration emitter, and
+  // MongoStateStore has private members, so an inferred type cannot be written to the .d.ts
+  // (TS4094).
+  // MongoStateStore's own fields stay in the type (optional: a SQL store has none), so code reading them keeps compiling
+): new () => MigrationStateStore & Partial<Pick<MongoStateStore, 'lockCollectionName' | 'mongodbHost'>> => {
+  // A SQL URL (the OWNER's, `database.ownerUrl`) keeps the state in a table and serialises runs with a database lock;
+  // `lockCollectionName` set to '' disables that lock there too. The names default to the framework's own
+  // `lt_migrations` table, a custom `collectionName` is used as the table name
+  if (/^(postgres(ql)?|mysql|mariadb):/i.test(databaseUrl ?? '')) {
+    return class SqlMigrationStateStore extends SqlStateStore {
+      constructor() {
+        super({
+          lock: !!lockCollectionName,
+          tableName: collectionName === 'migrations' ? 'lt_migrations' : collectionName,
+          url: databaseUrl,
+        });
+      }
+    };
+  }
+  return class MigrationStateStore extends MongoStateStore {
+    constructor() {
+      super({
+        collectionName,
+        lockCollectionName: lockCollectionName || undefined,
+        uri: databaseUrl,
+      });
+    }
+  };
+};
+
+/** The MongoDB driver — a MongoDB migration needs it, a project without MongoDB never reaches this */
+function mongoDriver() {
+  return requireMongoPackages('A MongoDB migration (store or helper)').mongodb;
+}

package/src/core/modules/migrate/mongo-state-store.ts

@@ -1,25 +1,25 @@
 import { randomUUID } from 'crypto';
-import { Db, MongoClient } from 'mongodb';
+import type { Db, MongoClient } from 'mongodb';
 import { hostname } from 'os';
 import { promisify } from 'util';
 
+import type { MigrationSet, MigrationStateStore } from './migration-state-store.interface.js';
+import {
+  MIGRATION_LOCK_KEY,
+  MIGRATION_LOCK_STALE_AFTER_MS,
+  migrationMongoLocks,
+} from '../../common/persistence/infrastructure-locks.js';
+import { requireMongoPackages } from '../../common/persistence/mongo/mongo-packages.js';
+
 /**
  * Migration options interface (compatible with migrate package)
  */
 export interface MigrationOptions {
   [key: string]: unknown;
-  stateStore: MongoStateStore;
+  stateStore: MigrationStateStore;
 }
 
-/**
- * Migration set interface (compatible with migrate package)
- */
-export interface MigrationSet {
-  down?: (done?: (err?: Error) => void) => void;
-  lastRun?: string;
-  migrations: Array<{ timestamp?: number; title: string }>;
-  up: (done?: (err?: Error) => void) => void;
-}
+export type { MigrationSet, MigrationStateStore };
 
 /**
  * Options for MongoStateStore configuration
@@ -58,7 +58,7 @@ export interface MongoStateStoreOptions {
  * });
  * ```
  */
-export class MongoStateStore {
+export class MongoStateStore implements MigrationStateStore {
   /** Collection name for storing migration state */
   private readonly collectionName: string;
 
@@ -173,6 +173,12 @@ export async function synchronizedMigration(
 
   const stateStore = opts.stateStore;
 
+  // A store with its own lock (SqlStateStore) serialises the run itself
+  if (!(stateStore instanceof MongoStateStore) && typeof stateStore?.withLock === 'function') {
+    await stateStore.withLock(async () => callback(await stateStore.loadAsync()));
+    return;
+  }
+
   if (!(stateStore instanceof MongoStateStore)) {
     throw new Error('Given `stateStore` is not `MongoStateStore`');
   }
@@ -238,7 +244,11 @@ export async function synchronizedUp(opts: MigrationOptions): Promise<void> {
  * @param fn - Work to execute under the lock
  * @returns Promise with the result of `fn`
  */
-export async function withMigrationLock<T>(stateStore: MongoStateStore, fn: () => Promise<T>): Promise<T> {
+export async function withMigrationLock<T>(stateStore: MigrationStateStore, fn: () => Promise<T>): Promise<T> {
+  if (!(stateStore instanceof MongoStateStore)) {
+    // Another database's store brings its own lock; without one, fn runs unsynchronized
+    return typeof stateStore.withLock === 'function' ? stateStore.withLock(fn) : fn();
+  }
   const lockCollectionName = stateStore.lockCollectionName;
 
   if (!lockCollectionName) {
@@ -262,7 +272,7 @@ export async function withMigrationLock<T>(stateStore: MongoStateStore, fn: () =
  * on migration runtime — a migration running for hours keeps its lock as long as the
  * process lives.
  */
-const LOCK_STALE_AFTER_MS = 60_000;
+const LOCK_STALE_AFTER_MS = MIGRATION_LOCK_STALE_AFTER_MS;
 
 /** Heartbeat interval — comfortably below {@link LOCK_STALE_AFTER_MS} */
 const LOCK_HEARTBEAT_INTERVAL_MS = 15_000;
@@ -271,11 +281,12 @@ const LOCK_HEARTBEAT_INTERVAL_MS = 15_000;
 const LOCK_WAIT_TIMEOUT_MS = 15 * 60_000;
 
 /**
- * Keep refreshing `acquiredAt` while the migration runs.
+ * Keep renewing the lease while the migration runs.
  *
  * This is what makes lock-breaking safe: a lock is only ever taken over when its holder
- * stopped refreshing it, which for a live process cannot happen. Without the heartbeat,
- * breaking a stale lock and a long-running migration would be indistinguishable.
+ * stopped renewing it, which for a live process cannot happen. Without the heartbeat,
+ * breaking a stale lock and a long-running migration would be indistinguishable. The renewal
+ * also refreshes `acquiredAt`, the heartbeat an older replica's waiter reads.
  */
 function startLockHeartbeat(url: string, lockCollectionName: string, token: string): { stop: () => void } {
   // ONE connection for the whole heartbeat, rather than `dbRequest()`'s connect-and-close per
@@ -284,13 +295,14 @@ function startLockHeartbeat(url: string, lockCollectionName: string, token: stri
   // on the first tick (so a heartbeat that never fires costs nothing) and closed by stop().
   let client: MongoClient | undefined;
   let stopped = false;
+  let lostReported = false;
 
   const beat = async (): Promise<void> => {
     if (stopped) {
       return;
     }
     if (!client) {
-      const connected = await MongoClient.connect(url);
+      const connected = await mongoDriver().MongoClient.connect(url);
       if (stopped) {
         // stop() ran while we were connecting — nothing would ever close this one.
         await connected.close();
@@ -298,12 +310,20 @@ function startLockHeartbeat(url: string, lockCollectionName: string, token: stri
       }
       client = connected;
     }
-    // Scoped: once our lock has been broken and re-taken, our heartbeat must not keep the NEW
-    // holder's lock alive on our behalf.
-    await client
-      .db()
-      .collection(lockCollectionName)
-      .updateOne({ lock: 'lock', owner: token }, { $set: { acquiredAt: new Date() } });
+    // Scoped to our token: once our lock has been broken and re-taken, our heartbeat must not
+    // keep the NEW holder's lock alive on our behalf.
+    const renewed = await migrationMongoLocks(client.db().collection(lockCollectionName)).renew(
+      MIGRATION_LOCK_KEY,
+      token,
+      LOCK_STALE_AFTER_MS / 1000,
+    );
+    if (!renewed && !lostReported) {
+      lostReported = true;
+      console.warn(
+        `Migration lock in "${lockCollectionName}" was taken over by another replica while this one was migrating ` +
+          '(missed heartbeats). The migration continues, but no longer exclusively.',
+      );
+    }
   };
 
   const timer = setInterval(() => {
@@ -333,62 +353,34 @@ function startLockHeartbeat(url: string, lockCollectionName: string, token: stri
 /**
  * Acquires a lock in MongoDB to ensure only one migration runs at a time
  *
+ * A lease (`LockStore`) on the 12.0.0 document `{ lock: 'lock', owner, acquiredAt }`, so a replica
+ * still running an older version waits for this one and vice versa (`infrastructure-locks.ts`).
+ *
  * @param url - MongoDB connection URI
  * @param lockCollectionName - Name of the collection to use for locking
  */
 async function acquireLock(url: string, lockCollectionName: string): Promise<string> {
   return dbRequest(url, async (db) => {
     const collection = db.collection(lockCollectionName);
-
-    // Create unique index for atomicity
-    // https://docs.mongodb.com/manual/reference/method/db.collection.update/#use-unique-indexes
-    // https://groups.google.com/forum/#!topic/mongodb-user/-fucdS-7kIU
-    // https://stackoverflow.com/questions/33346175/mongodb-upsert-operation-seems-not-atomic-which-throws-duplicatekeyexception/34784533
-    await collection.createIndex({ lock: 1 }, { unique: true });
-
+    const locks = migrationMongoLocks(collection);
     const token = lockOwnerId();
     const deadline = Date.now() + LOCK_WAIT_TIMEOUT_MS;
     let showMessage = true;
 
     for (;;) {
-      // Use updateOne with upsert for atomic lock acquisition (same as original package).
-      // `$setOnInsert` stamps the acquisition time only for the winner, so a loser's
-      // update never refreshes the holder's staleness clock.
-      const result = await collection.updateOne(
-        { lock: 'lock' },
-        { $set: { lock: 'lock' }, $setOnInsert: { acquiredAt: new Date(), owner: token } },
-        { upsert: true },
-      );
-
-      if (result.upsertedCount > 0) {
-        return token;
-      }
-
+      const holder = await collection.findOne({ lock: MIGRATION_LOCK_KEY });
       // The holder may be gone: migrations run on every container boot, so a replica
       // SIGKILLed mid-migration (OOM, node drain, failed deploy) would otherwise leave a
-      // lock nobody holds — and every future boot of every replica would wait on it
-      // forever. Only a lock that stopped heart-beating is broken; see LOCK_STALE_AFTER_MS.
-      const holder = await collection.findOne({ lock: 'lock' });
-      if (holder) {
-        const acquiredAt = holder.acquiredAt instanceof Date ? holder.acquiredAt : undefined;
-        if (!acquiredAt) {
-          // Written by a version that did not stamp the lock. Start its clock now rather
-          // than breaking it immediately — the holder may well be alive.
-          await collection.updateOne(
-            { _id: holder._id, acquiredAt: { $exists: false } },
-            { $set: { acquiredAt: new Date() } },
-          );
-        } else if (Date.now() - acquiredAt.getTime() > LOCK_STALE_AFTER_MS) {
+      // lock nobody holds. The lease breaks only a lock that stopped heart-beating.
+      if (await locks.tryAcquire(MIGRATION_LOCK_KEY, token, LOCK_STALE_AFTER_MS / 1000)) {
+        if (holder) {
+          const lastBeat = holder.acquiredAt instanceof Date ? holder.acquiredAt.toISOString() : 'never';
           console.warn(
-            `Breaking stale migration lock in "${lockCollectionName}" (last heartbeat ${acquiredAt.toISOString()}, ` +
+            `Broke stale migration lock in "${lockCollectionName}" (last heartbeat ${lastBeat}, ` +
               `owner ${holder.owner ?? 'unknown'}) — its holder is gone.`,
           );
-          // Matching on acquiredAt makes the break safe under concurrency: if another
-          // waiter already broke and re-acquired the lock, the timestamp differs and this
-          // deletes nothing.
-          await collection.deleteOne({ _id: holder._id, acquiredAt });
-          continue;
         }
+        return token;
       }
 
       if (Date.now() > deadline) {
@@ -429,7 +421,7 @@ function lockOwnerId(): string {
 async function dbRequest<T>(url: string, callback: (db: Db) => Promise<T> | T): Promise<T> {
   let client: MongoClient | undefined;
   try {
-    client = await MongoClient.connect(url);
+    client = await mongoDriver().MongoClient.connect(url);
     const db = client.db();
     return await callback(db);
   } finally {
@@ -447,5 +439,12 @@ async function releaseLock(url: string, lockCollectionName: string, token: strin
   // Scoped to OUR token. An unscoped delete removes whatever lock exists — so after a missed
   // heartbeat let another replica break and re-take the lock, the original holder's `finally`
   // would delete the NEW holder's lock and let a third replica start a concurrent migration.
-  await dbRequest(url, (db) => db.collection(lockCollectionName).deleteOne({ lock: 'lock', owner: token }));
+  await dbRequest(url, (db) =>
+    migrationMongoLocks(db.collection(lockCollectionName)).release(MIGRATION_LOCK_KEY, token),
+  );
+}
+
+/** The MongoDB driver — a MongoDB migration needs it, a project without MongoDB never reaches this */
+function mongoDriver() {
+  return requireMongoPackages('A MongoDB migration (store or helper)').mongodb;
 }

package/src/core/modules/migrate/sql-migration.helper.ts

@@ -0,0 +1,48 @@
+import type { DatabaseSqlEngine } from '../../common/interfaces/server-options.interface.js';
+import { withMysqlSchemaLock } from '../../common/persistence/sql/mysql/mysql-schema.migrator.js';
+import { SCHEMA_LOCK_SQL } from '../../common/persistence/sql/postgres/postgres-schema.migrator.js';
+import { createSqlExecutor } from '../../common/persistence/sql/sql-executor.factory.js';
+
+/**
+ * Run the reviewed statements of a SQL migration (`migrate create <name> --sql`) as the table OWNER, under the lock the
+ * boot's schema migration takes, so a replica booting meanwhile waits and then sees the result. On PostgreSQL in one
+ * transaction: either every statement applies or none does. MySQL and MariaDB commit every DDL statement on its own, so
+ * there a failure leaves the statements before it applied — write such a migration so it can run again.
+ *
+ * The statements are the ones a refused boot suggested (`SchemaMigrationRequiredError`) — after review: a narrowed
+ * type, a new unique index or a rename collision can reject or rewrite stored rows, which is why the framework never
+ * runs them on its own (plan §3.12).
+ */
+export async function runSqlMigration(
+  ownerUrl: string,
+  statements: readonly string[],
+  options: { engine?: DatabaseSqlEngine } = {},
+): Promise<void> {
+  if (!ownerUrl) {
+    throw new Error('runSqlMigration() needs the connection URL of the table owner (database.ownerUrl)');
+  }
+  const executor = await createSqlExecutor({
+    applicationName: 'nest-server-migration',
+    engine: options.engine ?? 'typeorm',
+    maxConnections: 1,
+    url: ownerUrl,
+  });
+  try {
+    if (/^(mysql|mariadb):/i.test(ownerUrl)) {
+      await withMysqlSchemaLock(executor, async (run) => {
+        for (const text of statements) {
+          await run({ params: [], text });
+        }
+      });
+      return;
+    }
+    await executor.transaction(async (tx) => {
+      await tx.run({ params: [], text: SCHEMA_LOCK_SQL }, { kind: 'system' });
+      for (const text of statements) {
+        await tx.run({ params: [], text }, { kind: 'system' });
+      }
+    });
+  } finally {
+    await executor.close();
+  }
+}