@lenne.tech/nest-server 12.0.0 → 12.1.0

package/src/core/modules/hub/services/core-hub-db.service.ts

@@ -1,7 +1,6 @@
 import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
-import { InjectConnection } from '@nestjs/mongoose';
-import * as mongo from 'mongodb';
-import { type Connection, Types } from 'mongoose';
+import type * as mongo from 'mongodb';
+import type { Connection } from 'mongoose';
 
 import { ConfigService } from '../../../common/services/config.service.js';
 import { CoreS3Service } from '../../../common/services/core-s3.service.js';
@@ -11,6 +10,7 @@ import {
   FILESYSTEM_FILES_COLLECTION,
   FilesystemFileHelper,
 } from '../../file/filesystem-file.helper.js';
+import { fileMetadataCollection } from '../../file/file-metadata.store.js';
 import { S3_FILES_COLLECTION, S3FileHelper } from '../../file/s3-file.helper.js';
 import { HubActionMessage } from '../hub-action-messages.js';
 import { HUB_CONFIG } from '../hub.constants.js';
@@ -24,6 +24,12 @@ import {
   HubUnavailable,
 } from '../interfaces/hub-panels.interface.js';
 import type { ResolvedHubConfig } from '../interfaces/hub-config.interface.js';
+import {
+  createGridFsBucket,
+  InjectConnection,
+  isValidObjectId,
+  newObjectId,
+} from '../../../common/persistence/mongo/mongoose-compat.js';
 
 /**
  * Read-only MongoDB introspection for the DB, Models/ERD and Files panels.
@@ -123,10 +129,10 @@ export class CoreHubDbService {
     if (!db) {
       throw new Error(HubActionMessage.mongoUnavailable);
     }
-    if (!Types.ObjectId.isValid(id)) {
+    if (!isValidObjectId(id)) {
       throw new Error(HubActionMessage.invalidFileId);
     }
-    const objectId = new Types.ObjectId(id);
+    const objectId = newObjectId(id);
 
     // Same probe order as `CoreFileService.deleteFile()`: S3, then filesystem, then GridFS as the
     // fallthrough. Keeping the two in step matters — a Hub that resolved a file differently from the
@@ -134,7 +140,7 @@ export class CoreHubDbService {
     let store: HubFileStore | undefined;
     let doc: any;
     for (const candidate of this.fileStores(bucket)) {
-      const [found] = await db.collection(candidate.collection).find({ _id: objectId }, { limit: 1 }).toArray();
+      const [found] = await this.fileCollection(candidate).find({ _id: objectId }, { limit: 1 }).toArray();
       if (found) {
         doc = found;
         store = candidate.store;
@@ -150,7 +156,11 @@ export class CoreHubDbService {
 
     switch (store) {
       case 'filesystem': {
-        await FilesystemFileHelper.deleteFile(this.filesystemDir, db.collection(FILESYSTEM_FILES_COLLECTION), objectId);
+        await FilesystemFileHelper.deleteFile(
+          this.filesystemDir,
+          fileMetadataCollection(this.connection, 'filesystem'),
+          objectId,
+        );
         break;
       }
       case 's3': {
@@ -158,11 +168,11 @@ export class CoreHubDbService {
         if (!this.s3Service?.enabled) {
           throw new Error(HubActionMessage.s3Unavailable);
         }
-        await S3FileHelper.deleteFile(this.s3Service, db.collection(S3_FILES_COLLECTION), objectId);
+        await S3FileHelper.deleteFile(this.s3Service, fileMetadataCollection(this.connection, 's3'), objectId);
         break;
       }
       default: {
-        const gridFs = new mongo.GridFSBucket(db as unknown as mongo.Db, { bucketName: bucket });
+        const gridFs = createGridFsBucket(db as unknown as mongo.Db, { bucketName: bucket });
         await gridFs.delete(objectId as unknown as mongo.ObjectId);
       }
     }
@@ -173,9 +183,9 @@ export class CoreHubDbService {
   /**
    * File inventory across ALL THREE metadata stores.
    *
-   * Metadata always lives in MongoDB whichever store holds the bytes (`fs.files` / `s3-files` /
-   * `filesystem-files`), so one connection can see everything — which is exactly what
-   * `CoreFileService.findFileInfo()` does, and what this panel now mirrors.
+   * Metadata is queryable whichever store holds the bytes (`fs.files` / `s3-files` /
+   * `filesystem-files`, the latter two as tables when `database` routes them to a SQL source), so the
+   * panel reads all three the way `CoreFileService.findFileInfo()` does (`fileCollection()`).
    *
    * It used to read `fs.files` alone. Under `file.storage: 's3'` or `'filesystem'` that made the
    * panel report **0 files** — not "this panel does not cover your driver", but a confident wrong
@@ -209,11 +219,9 @@ export class CoreHubDbService {
 
     for (const source of this.fileStores(bucket)) {
       try {
-        const docs = await db
-          .collection(source.collection)
-          .find({}, { limit: window, sort: { uploadDate: -1 } })
-          .toArray();
-        const count = await db.collection(source.collection).countDocuments();
+        const collection = this.fileCollection(source);
+        const docs = await collection.find({}, { limit: window, sort: { uploadDate: -1 } }).toArray();
+        const count = await collection.countDocuments();
         stores.push({ collection: source.collection, count, store: source.store });
         for (const doc of docs) {
           rows.push({
@@ -255,6 +263,16 @@ export class CoreHubDbService {
    * GridFS is last because it is the fallthrough: its collection name depends on the bucket, and a
    * document there carries no `storage` marker to identify it by.
    */
+  /**
+   * The metadata of one store as `CoreFileService` reads it: S3 and filesystem metadata follow `database` to a SQL
+   * table when their model is routed there; GridFS keeps `<bucket>.files` in MongoDB
+   */
+  protected fileCollection(source: { collection: string; store: HubFileStore }): mongo.Collection<any> {
+    return source.store === 'gridfs'
+      ? this.connection.db.collection(source.collection)
+      : fileMetadataCollection(this.connection, source.store);
+  }
+
   protected fileStores(bucket: string): { collection: string; store: HubFileStore }[] {
     return [
       { collection: S3_FILES_COLLECTION, store: 's3' },

package/src/core/modules/hub/services/core-hub-migrations.service.ts

@@ -1,12 +1,15 @@
 import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
-import { InjectConnection } from '@nestjs/mongoose';
+import { InjectConnection } from '../../../common/persistence/mongo/mongoose-compat.js';
 import { readdir } from 'fs/promises';
 import type { Connection } from 'mongoose';
 import { resolve } from 'path';
 
 import { ConfigService } from '../../../common/services/config.service.js';
 import { DEFAULT_MIGRATION_FILE_PATTERN, MigrationRunner } from '../../migrate/migration-runner.js';
+import type { DatabaseSqlEngine } from '../../../common/interfaces/server-options.interface.js';
+import { getPersistenceRuntime } from '../../../common/persistence/persistence-runtime.registry.js';
 import { MongoStateStore } from '../../migrate/mongo-state-store.js';
+import { SqlStateStore } from '../../migrate/sql-state-store.js';
 import { HubActionMessage } from '../hub-action-messages.js';
 import { HUB_CONFIG } from '../hub.constants.js';
 import { HubMigrationsData, HubUnavailable } from '../interfaces/hub-panels.interface.js';
@@ -31,6 +34,7 @@ export class CoreHubMigrationsService {
 
   /** Run all pending migrations. Returns the titles that were applied. */
   async runPending(): Promise<{ ran: string[] }> {
+    await this.assertSingleMigrationState();
     const runner = this.buildRunner();
     const before = new Set(((await this.getStatus()) as HubMigrationsData).completed ?? []);
     await runner.up();
@@ -40,6 +44,7 @@ export class CoreHubMigrationsService {
 
   /** Roll back the most recently applied migration. Returns the title that was reverted. */
   async rollbackLast(): Promise<{ rolledBack?: string }> {
+    await this.assertSingleMigrationState();
     const before = ((await this.getStatus()) as HubMigrationsData).completed ?? [];
     const runner = this.buildRunner();
     await runner.down();
@@ -47,11 +52,18 @@ export class CoreHubMigrationsService {
     return { rolledBack: before.find((title) => !after.has(title)) };
   }
 
-  /** Build a MigrationRunner from the hub config + the configured Mongo URI. */
+  /** Build a MigrationRunner from the hub config + the configured Mongo URI (or the SQL default source's owner). */
   protected buildRunner(): MigrationRunner {
     if (this.config.migrations === false) {
       throw new Error(HubActionMessage.migrationsDisabled);
     }
+    const sqlStore = this.sqlStateStore();
+    if (sqlStore) {
+      return new MigrationRunner({
+        migrationsDirectory: resolve(process.cwd(), this.config.migrations.dir),
+        stateStore: sqlStore,
+      });
+    }
     const uri = this.configService.getFastButReadOnly<string>('mongoose.uri');
     if (!uri) {
       throw new Error(HubActionMessage.mongoUriMissing);
@@ -66,11 +78,93 @@ export class CoreHubMigrationsService {
     });
   }
 
+  /**
+   * The migration state store when the default source is a SQL database: the framework keeps the state there
+   * (`lt_migrations`), readable and writable by the table owner only. Throws without `database.ownerUrl`.
+   */
+  protected sqlStateStore(): SqlStateStore | undefined {
+    const source = getPersistenceRuntime()?.defaultSqlSource();
+    if (!source) {
+      return undefined;
+    }
+    if (!source.ownerUrl) {
+      throw new Error(HubActionMessage.sqlOwnerMissing);
+    }
+    return new SqlStateStore({ engine: source.engine as DatabaseSqlEngine, url: source.ownerUrl });
+  }
+
+  /**
+   * Refuse to run or roll back while {@link migrationStateLeftInMongo} — the Hub would apply, against live data, every
+   * migration the project's own runs recorded in MongoDB.
+   */
+  protected async assertSingleMigrationState(): Promise<void> {
+    const sqlStore = this.sqlStateStore();
+    if (!sqlStore) {
+      return;
+    }
+    const completed = ((await sqlStore.loadAsync()).migrations ?? []).map((migration) => migration.title);
+    if (await this.migrationStateLeftInMongo(completed)) {
+      throw new Error(this.migrationStateInMongoMessage());
+    }
+  }
+
+  /**
+   * Whether the project still records its migrations in MongoDB although the default source is a SQL database.
+   *
+   * The state of a SQL default source belongs in `lt_migrations`, but only `migrations-utils/migrate.js` decides where
+   * it actually goes: one that still passes the MongoDB URI to `createMigrationStore()` writes the MongoDB collection,
+   * and the empty table would show every applied migration as pending. Answered from the data, never guessed: an empty
+   * table next to a MongoDB collection that lists applied migrations. A MongoDB read that fails throws, so the panel
+   * never offers a run it could not rule out.
+   */
+  protected async migrationStateLeftInMongo(sqlCompleted: string[]): Promise<boolean> {
+    if (sqlCompleted.length || this.config.migrations === false) {
+      return false;
+    }
+    const db = this.connection?.db;
+    if (!db) {
+      return false;
+    }
+    const [stateDoc] = await db.collection(this.config.migrations.collectionName).find({}).limit(1).toArray();
+    return (stateDoc?.migrations ?? []).length > 0;
+  }
+
+  protected migrationStateInMongoMessage(): string {
+    return HubActionMessage.migrationStateInMongo(
+      this.config.migrations === false ? 'migrations' : this.config.migrations.collectionName,
+    );
+  }
+
   /** Completed + pending migrations. */
   async getStatus(): Promise<HubMigrationsData | HubUnavailable> {
     if (this.config.migrations === false) {
       return { available: false, hint: 'The migrations panel is disabled.' };
     }
+    let sqlStore: SqlStateStore | undefined;
+    try {
+      sqlStore = this.sqlStateStore();
+    } catch (error) {
+      return { available: false, hint: error instanceof Error ? error.message : String(error) };
+    }
+    if (sqlStore) {
+      let state: { lastRun?: string; migrations?: { title: string }[] } = {};
+      try {
+        state = await sqlStore.loadAsync();
+      } catch (error) {
+        this.logger.warn(`Failed to read migration state: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      const completed = (state.migrations ?? []).map((migration) => migration.title);
+      try {
+        if (await this.migrationStateLeftInMongo(completed)) {
+          return { available: false, hint: this.migrationStateInMongoMessage() };
+        }
+      } catch (error) {
+        return { available: false, hint: error instanceof Error ? error.message : String(error) };
+      }
+      const { dirAvailable, files } = await this.listMigrationFiles();
+      const pending = dirAvailable ? files.filter((file) => !completed.includes(file)) : [];
+      return { completed, dirAvailable, lastRun: state.lastRun, pending, source: 'table' };
+    }
     const db = this.connection?.db;
     if (!db) {
       return { available: false, hint: 'No MongoDB connection is available.' };

package/src/core/modules/hub/services/core-hub-sources.service.ts

@@ -6,7 +6,19 @@ import { CoreAiInteractionService } from '../../ai/services/core-ai-interaction.
 import { CoreBetterAuthUserMapper } from '../../better-auth/core-better-auth-user.mapper.js';
 import { CoreErrorCodeService } from '../../error-code/core-error-code.service.js';
 import { CorePermissionsService } from '../../permissions/core-permissions.service.js';
-import { HubCronData, HubErrorCodesData, HubUnavailable } from '../interfaces/hub-panels.interface.js';
+import { redactUrl } from '../../../common/persistence/data-source.config.js';
+import {
+  getPersistedModels,
+  getPersistenceRuntime,
+  getRegisteredDataStore,
+} from '../../../common/persistence/persistence-runtime.registry.js';
+import { ConfigService } from '../../../common/services/config.service.js';
+import {
+  HubCronData,
+  HubErrorCodesData,
+  HubPersistenceData,
+  HubUnavailable,
+} from '../interfaces/hub-panels.interface.js';
 
 /**
  * Single choke point for the Hub's OPTIONAL data sources.
@@ -28,6 +40,40 @@ export class CoreHubSourcesService {
     @Optional() protected readonly schedulerRegistry?: SchedulerRegistry,
   ) {}
 
+  /**
+   * Where every model registered with `CorePersistenceModule.forFeature()` is stored: its source, the database and
+   * engine behind it, and what that store can do. Without a SQL source everything is on the MongoDB connection.
+   */
+  getPersistence(): HubPersistenceData {
+    const overview = getPersistenceRuntime()?.describe() ?? {
+      defaultSource: 'default',
+      models: getPersistedModels().map((model) => ({ name: model.name, source: 'default' })),
+      sources: [
+        {
+          driver: 'mongodb',
+          host: redactUrl(ConfigService.configFastButReadOnly?.mongoose?.uri ?? ''),
+          name: 'default',
+          ownerConfigured: false,
+        },
+      ],
+    };
+    return {
+      ...overview,
+      models: overview.models
+        .map((model) => {
+          const store = getRegisteredDataStore(model.name);
+          const capabilities = store
+            ? Object.entries(store.capabilities)
+                .filter(([, value]) => value === true)
+                .map(([key]) => key)
+                .sort()
+            : [];
+          return { ...model, capabilities, driver: store?.driver };
+        })
+        .sort((a, b) => a.name.localeCompare(b.name)),
+    };
+  }
+
   /** AI availability + a light interaction/usage summary. */
   async getAi(): Promise<HubUnavailable | { available: true; totalInteractions: number }> {
     const interactionService = this.resolve<CoreAiInteractionService>(CoreAiInteractionService);

package/src/core/modules/hub/services/hub-query-profiler.service.ts

@@ -1,5 +1,5 @@
 import { Inject, Injectable, Logger, OnModuleDestroy, OnModuleInit, Optional } from '@nestjs/common';
-import { InjectConnection } from '@nestjs/mongoose';
+import { InjectConnection } from '../../../common/persistence/mongo/mongoose-compat.js';
 import type { Connection } from 'mongoose';
 
 import { redactSensitiveText } from '../../../common/helpers/logging.helper.js';

package/src/core/modules/migrate/README.md

@@ -137,6 +137,60 @@ await synchronizedMigration(migrationOptions, async (migrationSet) => {
 await synchronizedUp(migrationOptions);
 ```
 
+### SQL migrations (PostgreSQL data sources)
+
+On a PostgreSQL source the framework migrates the schema itself at boot (new tables, columns, declared renames,
+non-unique indexes, row-level security, grants). Changes that can reject or rewrite stored rows — a changed column
+type, a new unique index, a rename whose old and new column both exist — are never applied automatically: the boot
+stops with `SchemaMigrationRequiredError`, listing each change with a **suggested** statement.
+
+```bash
+migrate create widen-budget --sql
+```
+
+writes a migration whose `up` / `down` call `runSqlMigration(ownerUrl, statements)`. Paste the suggested statements,
+review them, add the reverse to `down`. They run as the table owner (`NSC__DATABASE__OWNER_URL`, i.e.
+`database.ownerUrl`), in one transaction, under the advisory lock the boot's schema migration takes — so a replica
+booting meanwhile waits and then finds nothing left to do. In a vendor-mode project the import points at the vendored
+core automatically.
+
+`NSC__DATABASE__OWNER_URL` in the server's environment needs the URL beside it: a `database` written as a URL string
+is REPLACED by the variable (the environment merge turns it into `{ ownerUrl }`), so the boot refuses that
+combination. Write `database: { url: … }` in the configuration, or set `NSC__DATABASE__URL` as well.
+
+### Migration state on PostgreSQL (`SqlStateStore`)
+
+A project whose default source is PostgreSQL keeps its migration state there instead of in MongoDB. Pass the OWNER's
+URL to `createMigrationStore()` — it picks the store by the URL's scheme:
+
+```javascript
+// migrations-utils/migrate.js
+const { createMigrationStore } = require('@lenne.tech/nest-server');
+
+module.exports = createMigrationStore(process.env.NSC__DATABASE__OWNER_URL);
+```
+
+|                     | MongoDB (`MongoStateStore`)                                                            | PostgreSQL (`SqlStateStore`)                                                                                                                 |
+| ------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| State               | one document in `migrations`                                                           | one row in `lt_migrations` (created on first use)                                                                                            |
+| Run lock            | a document in `migrations_lock`, renewed every 15 s, broken after 60 s without renewal | a transaction-scoped advisory lock held for the whole run — it ends with the connection, so a replica killed mid-run leaves nothing to break |
+| Opt out of the lock | `lockCollectionName: ''`                                                               | `lockCollectionName: ''` (or `new SqlStateStore({ url, lock: false })`)                                                                      |
+| Connection          | the MongoDB URI                                                                        | the table owner (`database.ownerUrl`): migrations change the schema and every tenant's data                                                  |
+
+The connection uses the first SQL engine the project has installed (`typeorm`, `kysely`, `drizzle`): the CLI runs
+outside the application and cannot read `database.sqlEngine`. To pin one, export your own class:
+`class Store extends SqlStateStore { constructor() { super({ engine: 'kysely', url: process.env.NSC__DATABASE__OWNER_URL }) } }`.
+
+**Move the state when you switch.** A project that had MongoDB as its default source has its applied migrations in the
+`migrations` collection. Pointed at the owner URL, `createMigrationStore()` starts from an empty `lt_migrations`, and the
+next `migrate up` applies every migration again. Copy the state document's `lastRun` and `migrations` into the table
+first (`await new SqlStateStore(ownerUrl).saveAsync(state)` with the document `MongoStateStore.loadAsync()` returns).
+The Hub's Migrations panel refuses to run while the table is empty and the collection is not.
+
+`MigrationRunner`, `synchronizedMigration()` and the `migrate` CLI accept either store. The advisory lock is held by an
+open transaction for the length of the run: a server-side `idle_in_transaction_session_timeout` shorter than your
+longest migration would end it early — leave that setting off (the default) for the owner role.
+
 ## API Reference
 
 ### MongoStateStore

package/src/core/modules/migrate/cli/migrate-cli.ts

@@ -17,6 +17,7 @@
  *   --store, -s            Path to state store module
  *   --compiler, -c         Compiler to use (e.g., ts:./path/to/ts-compiler.js)
  *   --template-file, -t    Template file for creating migrations
+ *   --sql                  Create a SQL migration (statements run as the table owner, see runSqlMigration)
  *   --strict               Fail if a recorded migration's file is missing (default: off / tolerate).
  *                          Applies to up/list; down always fails hard on a missing rollback file.
  */
@@ -25,7 +26,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 
 import { MigrationRunner, parseStrictEnv } from '../migration-runner.js';
-import { MongoStateStore } from '../mongo-state-store.js';
+import type { MigrationStateStore } from '../migration-state-store.interface.js';
 import { createRequire } from 'node:module';
 import { callerDirectory } from '../../../common/helpers/module-location.helper.js';
 
@@ -42,6 +43,8 @@ interface CliOptions {
   migrationsDir: string;
   store?: string;
   strict?: boolean;
+  /** `create`: a SQL migration instead of the default template */
+  sql?: boolean;
   templateFile?: string;
 }
 
@@ -97,6 +100,40 @@ export function rewriteFrameworkSpecifier(template: string, specifier: string):
  *
  * @param coreRoot - Root of the core this CLI belongs to; defaults to the one it runs from (tests only)
  */
+/**
+ * The template of `migrate create <name> --sql`: the statements a refused boot suggested go into `up` after review,
+ * their reverse into `down`. They run as the table owner (`NSC__DATABASE__OWNER_URL`, i.e. `database.ownerUrl`).
+ * `specifier`: the import path a vendor-mode project uses instead of the package name.
+ */
+export function sqlMigrationTemplate(name: string, specifier?: string): string {
+  const template = `/**
+ * Migration: ${name} (SQL)
+ * Created: ${new Date().toISOString()}
+ *
+ * Paste the statements the boot suggested (SchemaMigrationRequiredError) and REVIEW them: a narrowed type, a new
+ * unique index or a rename collision can reject or rewrite stored rows. They run as the table owner, under the lock
+ * the boot's schema migration takes — on PostgreSQL in one transaction; on MySQL / MariaDB every DDL statement commits
+ * on its own, so write the migration so it can run again.
+ */
+import { runSqlMigration } from '@lenne.tech/nest-server';
+
+const ownerUrl = process.env.NSC__DATABASE__OWNER_URL ?? '';
+
+export const up = async () => {
+  await runSqlMigration(ownerUrl, [
+    // PostgreSQL: 'ALTER TABLE "projects" ALTER COLUMN "budget" TYPE text COLLATE "C" USING "budget"::text',
+  ]);
+};
+
+export const down = async () => {
+  await runSqlMigration(ownerUrl, [
+    // the reverse of every statement in up
+  ]);
+};
+`;
+  return specifier ? rewriteFrameworkSpecifier(template, specifier) : template;
+}
+
 async function createMigration(name: string, options: CliOptions, coreRoot?: string) {
   if (!name) {
     console.error('Error: Migration name is required');
@@ -116,7 +153,9 @@ async function createMigration(name: string, options: CliOptions, coreRoot?: str
   let template: string;
 
   // Use custom template if provided
-  if (options.templateFile) {
+  if (options.sql) {
+    template = sqlMigrationTemplate(name, vendoredFrameworkSpecifier(options.migrationsDir, process.cwd(), coreRoot));
+  } else if (options.templateFile) {
     const templatePath = path.resolve(process.cwd(), options.templateFile);
     template = fs.readFileSync(templatePath, 'utf-8');
     const specifier = vendoredFrameworkSpecifier(options.migrationsDir, process.cwd(), coreRoot);
@@ -197,7 +236,7 @@ async function listMigrations(options: CliOptions) {
 /**
  * Load state store from module
  */
-function loadStateStore(storePath: string | undefined): MongoStateStore {
+function loadStateStore(storePath: string | undefined): MigrationStateStore {
   if (!storePath) {
     throw new Error('--store option is required for up/down/list commands');
   }
@@ -298,6 +337,8 @@ function parseArgs(): { command: string; name?: string; options: CliOptions } {
       options.templateFile = args[++i];
     } else if (arg === '--strict') {
       options.strict = true;
+    } else if (arg === '--sql') {
+      options.sql = true;
     }
   }
 

package/src/core/modules/migrate/index.ts

@@ -38,4 +38,7 @@
 export * from './cli/migrate-cli.js';
 export * from './migration.helper.js';
 export * from './migration-runner.js';
+export * from './migration-state-store.interface.js';
 export * from './mongo-state-store.js';
+export * from './sql-migration.helper.js';
+export * from './sql-state-store.js';

package/src/core/modules/migrate/migration-runner.ts

@@ -2,7 +2,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 
 import { _endMigration, _startMigration } from './migration.helper.js';
-import { MongoStateStore, withMigrationLock } from './mongo-state-store.js';
+import type { MigrationStateStore } from './migration-state-store.interface.js';
+import { withMigrationLock } from './mongo-state-store.js';
 import { createRequire } from 'node:module';
 
 /**
@@ -98,7 +99,7 @@ export interface MigrationRunnerOptions {
   /** Pattern to match migration files (default: {@link DEFAULT_MIGRATION_FILE_PATTERN}) */
   pattern?: RegExp;
   /** State store for tracking migrations */
-  stateStore: MongoStateStore;
+  stateStore: MigrationStateStore;
   /**
    * Fail hard when a migration recorded in the state has no file on disk.
    *

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

@@ -1,9 +1,12 @@
 import * as fs from 'fs';
-import { Db, GridFSBucket, MongoClient, ObjectId } from 'mongodb';
+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
@@ -60,7 +63,7 @@ export const _endMigration = async () => {
  * ```
  */
 export const getDb = async (mongoUrl: string): Promise<Db> => {
-  const client: MongoClient = await MongoClient.connect(mongoUrl);
+  const client: MongoClient = await mongoDriver().MongoClient.connect(mongoUrl);
 
   // Track connection for auto-cleanup in migrations
   if (inMigrationContext) {
@@ -187,14 +190,14 @@ export const uploadFileToGridFS = async (
     ...options,
   };
 
-  const client = await MongoClient.connect(mongoUrl);
+  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 GridFSBucket(db, { bucketName });
+  const bucket = new (mongoDriver().GridFSBucket)(db, { bucketName });
   const writeStream = bucket.openUploadStream(filename);
 
   const readStream = fs.createReadStream(sourcePath);
@@ -276,10 +279,10 @@ export const uploadFileToGridFS = async (
  * 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 mongoUrl - MongoDB connection URI
- * @param collectionName - Optional collection name (default: 'migrations')
+ * @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 MongoStateStore class that can be used with migrate CLI
+ * @returns A state store class (MongoStateStore or SqlStateStore) that can be used with the migrate CLI
  *
  * @example
  * ```typescript
@@ -288,23 +291,45 @@ export const uploadFileToGridFS = async (
  * 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 = (
-  mongoUrl: string,
+  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).
-): new () => MongoStateStore => {
+  // 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: mongoUrl,
+        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;
+}