@lenne.tech/nest-server 11.43.3 → 12.1.0

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

@@ -1,16 +1,19 @@
 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 { Connection } from 'mongoose';
+import type { Connection } from 'mongoose';
 import { resolve } from 'path';
 
-import { ConfigService } from '../../../common/services/config.service';
-import { DEFAULT_MIGRATION_FILE_PATTERN, MigrationRunner } from '../../migrate/migration-runner';
-import { MongoStateStore } from '../../migrate/mongo-state-store';
-import { HubActionMessage } from '../hub-action-messages';
-import { HUB_CONFIG } from '../hub.constants';
-import { HubMigrationsData, HubUnavailable } from '../interfaces/hub-panels.interface';
-import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+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';
+import type { ResolvedHubConfig } from '../interfaces/hub-config.interface.js';
 
 /**
  * Reads migration status for the Migrations panel.
@@ -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

@@ -2,11 +2,23 @@ import { Injectable, Logger, Optional } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
 import { SchedulerRegistry } from '@nestjs/schedule';
 
-import { CoreAiInteractionService } from '../../ai/services/core-ai-interaction.service';
-import { CoreBetterAuthUserMapper } from '../../better-auth/core-better-auth-user.mapper';
-import { CoreErrorCodeService } from '../../error-code/core-error-code.service';
-import { CorePermissionsService } from '../../permissions/core-permissions.service';
-import { HubCronData, HubErrorCodesData, HubUnavailable } from '../interfaces/hub-panels.interface';
+import { CoreAiInteractionService } from '../../ai/services/core-ai-interaction.service.js';
+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 { 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);
@@ -124,7 +170,13 @@ export class CoreHubSourcesService {
     if (action === 'start') {
       job.start();
     } else if (action === 'stop') {
-      job.stop();
+      // With `waitForCompletion`, cron's stop() returns a promise that waits for the running tick and `onComplete`;
+      // a rejection from either must not become an unhandled one.
+      job.stop()?.catch((error: unknown) => {
+        this.logger.warn(
+          `Cron job "${name}" failed while stopping: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      });
     } else {
       // Fire the job's callback once now.
       const fire = (job as unknown as { fireOnTick?: () => void }).fireOnTick;

package/src/core/modules/hub/services/hub-log-buffer.service.ts

@@ -11,12 +11,12 @@ import {
 } from '@nestjs/common';
 import { inspect } from 'util';
 
-import { redactSensitiveText } from '../../../common/helpers/logging.helper';
-import { CoreRedisService } from '../../../common/services/core-redis.service';
-import { HUB_CONFIG } from '../hub.constants';
-import { HubBuffer } from '../hub-buffer';
-import { HubLogRecord, HubLogsData } from '../interfaces/hub-panels.interface';
-import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+import { redactSensitiveText } from '../../../common/helpers/logging.helper.js';
+import { CoreRedisService } from '../../../common/services/core-redis.service.js';
+import { HUB_CONFIG } from '../hub.constants.js';
+import { HubBuffer } from '../hub-buffer.js';
+import { HubLogRecord, HubLogsData } from '../interfaces/hub-panels.interface.js';
+import type { ResolvedHubConfig } from '../interfaces/hub-config.interface.js';
 
 interface BufferedLog extends HubLogRecord {
   timestamp: number;

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

@@ -1,14 +1,14 @@
 import { Inject, Injectable, Logger, OnModuleDestroy, OnModuleInit, Optional } from '@nestjs/common';
-import { InjectConnection } from '@nestjs/mongoose';
-import { Connection } from 'mongoose';
+import { InjectConnection } from '../../../common/persistence/mongo/mongoose-compat.js';
+import type { Connection } from 'mongoose';
 
-import { redactSensitiveText } from '../../../common/helpers/logging.helper';
-import { CoreRedisService } from '../../../common/services/core-redis.service';
-import { HUB_CONFIG, HUB_QUERY_PENDING_LIMIT } from '../hub.constants';
-import { HubBuffer } from '../hub-buffer';
-import { normalizeCommandShape } from '../helpers/hub-command-shape.helper';
-import { HubQueriesData, HubQueryRecord, HubQueryTemplate } from '../interfaces/hub-panels.interface';
-import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+import { redactSensitiveText } from '../../../common/helpers/logging.helper.js';
+import { CoreRedisService } from '../../../common/services/core-redis.service.js';
+import { HUB_CONFIG, HUB_QUERY_PENDING_LIMIT } from '../hub.constants.js';
+import { HubBuffer } from '../hub-buffer.js';
+import { normalizeCommandShape } from '../helpers/hub-command-shape.helper.js';
+import { HubQueriesData, HubQueryRecord, HubQueryTemplate } from '../interfaces/hub-panels.interface.js';
+import type { ResolvedHubConfig } from '../interfaces/hub-config.interface.js';
 
 interface ProfilerRecord extends HubQueryRecord {
   timestamp: number;

package/src/core/modules/hub/services/hub-trace-buffer.service.ts

@@ -1,11 +1,11 @@
 import { Inject, Injectable, Optional } from '@nestjs/common';
 import { Request, Response } from 'express';
 
-import { CoreRedisService } from '../../../common/services/core-redis.service';
-import { HUB_CONFIG } from '../hub.constants';
-import { HubBuffer } from '../hub-buffer';
-import { HubTraceRecord, HubTracesData } from '../interfaces/hub-panels.interface';
-import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+import { CoreRedisService } from '../../../common/services/core-redis.service.js';
+import { HUB_CONFIG } from '../hub.constants.js';
+import { HubBuffer } from '../hub-buffer.js';
+import { HubTraceRecord, HubTracesData } from '../interfaces/hub-panels.interface.js';
+import type { ResolvedHubConfig } from '../interfaces/hub-config.interface.js';
 
 interface TraceRecord extends HubTraceRecord {
   timestamp: number;

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

@@ -266,7 +266,7 @@ export const down = async () => {
 If issues occur during migration:
 
 - Check that `@lenne.tech/nest-server` is at version 11.3.0 or higher
-- Verify `ts-node` is installed as devDependency
+- Verify `@swc/core` is installed as devDependency (the `--compiler ts:…` loader needs it since 12.0.0)
 - Ensure `migrations-utils/migrate.js` exports the state store correctly
 - Test with `migrate --help` to verify CLI is available
 - Remember: Command must come FIRST in CLI syntax

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
@@ -417,8 +471,10 @@ const fileId = await uploadFileToGridFS('mongodb://localhost/mydb', '../assets/i
 });
 ```
 
-`relativePath` is resolved against the **helper module's** directory, not the migration file's — the
-paths in this example and in the migration template are written accordingly.
+Since 12.0.0 a relative `relativePath` is resolved against the directory of the **migration** that calls the
+helper (`../assets/image.png` above: an `assets` folder next to `migrations/`). Until then it was resolved against the
+helper module's own directory — inside `node_modules/@lenne.tech/nest-server/dist` in npm mode; that location is still
+tried when the file does not exist next to the migration, so paths written for it keep working.
 
 The returned promise settles only after three guarantees hold:
 
@@ -460,14 +516,34 @@ Ready-to-use template for nest-server projects:
 
 This template automatically imports `getDb()` and `uploadFileToGridFS()` from nest-server, along with your project's config. It's ready to use with zero configuration.
 
-### TypeScript Compiler
+**Vendor mode (12.0.0+):** a project with the core vendored into `src/core/` has no `@lenne.tech/nest-server` package, so
+`migrate create` rewrites the template's `'@lenne.tech/nest-server'` import to the relative path from the migrations
+directory to the vendored core (e.g. `'../src/core'`). It does so only when the package does not resolve from the
+project and the core it runs from has its own `index`; in npm mode the template is written unchanged.
+
+### TypeScript Loader
 
-Pre-configured TypeScript compiler for migrate CLI:
+`helpers/ts-compiler.js` lets the migrate CLI load TypeScript migrations and `config.env.ts`:
 
 ```bash
-migrate --compiler="ts:./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/helpers/ts-compiler.js"
+migrate up --compiler="ts:./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/helpers/ts-compiler.js"
 ```
 
+Since 12.0.0 it compiles `.ts` / `.cts` / `.mts` with **SWC** (`@swc/core`) instead of ts-node. It strips types and
+lowers decorators with the options of the `tsc` build (target `es2022`, legacy decorators with metadata, define
+semantics for class fields), and type-checks nothing — `tsc` and the IDE do that. It needs `@swc/core` in the project
+(`pnpm add -D @swc/core`; starter-based projects have it), resolved from the working directory. The same file runs
+the dev server from source: `node -r <path>/ts-compiler.js src/main.ts`.
+
+It covers both module systems: a `require` hook for CommonJS, and Node module hooks (`ts-compiler-hooks.mjs`,
+registered on load) for ES modules — an ESM project's entry and everything it imports. Both map a `./x.js` specifier to
+`./x.ts` when only the source exists. The implementation is `ts-compiler.cjs`; `ts-compiler.js` is the established
+entry path and forwards to it. `helpers/package.json` declares `"type": "commonjs"`, so that path works in CommonJS and
+ESM projects, in npm and vendor mode.
+
+Production images do not use it: migrations are compiled with the build and run as `.js` (see
+[Extension-agnostic identity](#extension-agnostic-identity-safe-source--compiled-js-transition)).
+
 ## Complete Setup Guide
 
 For a complete step-by-step guide on migrating from @nodepit/migrate-state-store-mongodb, see [MIGRATION_FROM_NODEPIT.md](./MIGRATION_FROM_NODEPIT.md).
@@ -476,7 +552,9 @@ For a complete step-by-step guide on migrating from @nodepit/migrate-state-store
 
 **No need to install the `migrate` package!** nest-server now includes a built-in migration CLI.
 
-1. Install ts-node (dev dependency): `npm install --save-dev ts-node`
+1. Make sure `@swc/core` is a dev dependency (`pnpm add -D @swc/core`) — the `--compiler ts:…` loader
+   below compiles TypeScript migrations with it (since 12.0.0; ts-node before, see
+   [TypeScript Loader](#typescript-loader))
 2. Create `migrations-utils/migrate.js` using `createMigrationStore()`
 3. Add migration scripts to your `package.json`
 4. Run migrations using the built-in CLI
@@ -499,14 +577,14 @@ See the [Migration Guide](./MIGRATION_FROM_NODEPIT.md) for detailed migration in
 
 ## Migration Identity & Strict Mode
 
-### Extension-agnostic identity (safe ts-node → compiled-JS transition)
+### Extension-agnostic identity (safe source → compiled-JS transition)
 
 A migration's identity is its timestamped file stem **without** the `.ts`/`.js` extension
 (`migrationId('1699-foo.ts') === migrationId('1699-foo.js') === '1699-foo'`). `up`, `down`,
 and `list`/`status` all compare identities, not raw filenames.
 
 This makes the recommended production setup — running compiled `.js` migrations in the image
-while the state was recorded under `.ts` names via ts-node — safe: already-applied migrations
+while the state was recorded under `.ts` names by source runs — safe: already-applied migrations
 are **not** re-run after the switch, and no state rewrite is needed. If both `foo.ts` and
 `foo.js` are present in the migrations directory (e.g. an overlapping `outDir`), they count
 as ONE migration: only the `.js` file is loaded and executed, and a warning is emitted.

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.
  */
@@ -24,21 +25,116 @@
 import * as fs from 'fs';
 import * as path from 'path';
 
-import { MigrationRunner, parseStrictEnv } from '../migration-runner';
-import { MongoStateStore } from '../mongo-state-store';
+import { MigrationRunner, parseStrictEnv } from '../migration-runner.js';
+import type { MigrationStateStore } from '../migration-state-store.interface.js';
+import { createRequire } from 'node:module';
+import { callerDirectory } from '../../../common/helpers/module-location.helper.js';
+
+/**
+ * Loads a file the CLI was pointed at (store, `--compiler`) by absolute path. `createRequire` instead of `require`:
+ * the core's source is valid as CommonJS and as ESM, and only the former has a `require` in scope.
+ */
+function requireFromProject(absolutePath: string): any {
+  return createRequire(path.join(process.cwd(), 'package.json'))(absolutePath);
+}
 
 interface CliOptions {
   compiler?: string;
   migrationsDir: string;
   store?: string;
   strict?: boolean;
+  /** `create`: a SQL migration instead of the default template */
+  sql?: boolean;
   templateFile?: string;
 }
 
+const FRAMEWORK_PACKAGE = '@lenne.tech/nest-server';
+
+/**
+ * The import specifier a migration created in `migrationsDir` must use for the framework's helpers.
+ *
+ * The shipped template imports `getDb` / `uploadFileToGridFS` from `@lenne.tech/nest-server`. A
+ * vendor-mode project has no such package — its core lives in `src/core/` — so a migration created
+ * from the unchanged template fails with TS2307 in the IDE and `tsc`, and with MODULE_NOT_FOUND at run time.
+ * Returns the relative path from the migrations directory to the vendored core when the package does
+ * not resolve from `cwd` AND this CLI runs from a vendored core (one with its own `index` next to
+ * `modules/`, as the vendor flatten-fix leaves it); otherwise `undefined`, i.e. keep the package name.
+ * In npm mode the package resolves, and in this framework repo `src/core/` has no `index`, so neither
+ * is rewritten.
+ *
+ * @param migrationsDir - Directory the migration is written to, absolute or relative to `cwd`
+ * @param cwd - Project directory the package is resolved from
+ * @param coreRoot - Root of the core this CLI belongs to
+ */
+export function vendoredFrameworkSpecifier(
+  migrationsDir: string,
+  cwd: string = process.cwd(),
+  coreRoot: string = path.resolve(callerDirectory(), '..', '..', '..'),
+): string | undefined {
+  try {
+    createRequire(path.join(cwd, 'package.json')).resolve(FRAMEWORK_PACKAGE);
+    return undefined;
+  } catch {
+    // Not installed — the vendor-mode case, if the core below has an entry point of its own.
+  }
+  if (!['index.ts', 'index.js'].some((entry) => fs.existsSync(path.join(coreRoot, entry)))) {
+    return undefined;
+  }
+  const relativePath = path.relative(path.resolve(cwd, migrationsDir), coreRoot).split(path.sep).join('/');
+  return relativePath.startsWith('.') ? relativePath : `./${relativePath}`;
+}
+
+/**
+ * Replaces the exact `@lenne.tech/nest-server` specifier (`from '…'`, `require('…')`, single or double
+ * quotes) in a migration template. Subpaths of the package are left alone.
+ */
+export function rewriteFrameworkSpecifier(template: string, specifier: string): string {
+  return template.replace(
+    /(['"])@lenne\.tech\/nest-server\1/g,
+    (_match, quote: string) => `${quote}${specifier}${quote}`,
+  );
+}
+
 /**
  * Create a new migration file
+ *
+ * @param coreRoot - Root of the core this CLI belongs to; defaults to the one it runs from (tests only)
  */
-async function createMigration(name: string, options: CliOptions) {
+/**
+ * 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');
     console.log('Usage: migrate create <name> [options]');
@@ -57,9 +153,15 @@ async function createMigration(name: string, options: CliOptions) {
   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);
+    if (specifier) {
+      template = rewriteFrameworkSpecifier(template, specifier);
+    }
   } else {
     // Default template
     template = `/**
@@ -134,14 +236,14 @@ 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');
   }
 
   const absolutePath = path.resolve(process.cwd(), storePath);
 
-  const StoreClass = require(absolutePath);
+  const StoreClass = requireFromProject(absolutePath);
 
   // Handle different export patterns
   if (StoreClass.default) {
@@ -235,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;
     }
   }
 
@@ -255,7 +359,7 @@ function registerCompiler(compiler: string | undefined) {
   if (type === 'ts' && compilerPath) {
     const absolutePath = path.resolve(process.cwd(), compilerPath);
 
-    const register = require(absolutePath);
+    const register = requireFromProject(absolutePath);
     if (typeof register === 'function') {
       register();
     }
@@ -395,9 +499,10 @@ const runCli = async (): Promise<void> => {
 
 // Run CLI if executed directly (`node migrate-cli.js`). The bin shim calls
 // runCli() itself, so this only covers a direct invocation of the compiled file.
-if (require.main === module) {
+// `typeof` first: as ESM neither `require` nor `module` exists, and reading them would throw at load time.
+if (typeof require !== 'undefined' && typeof module !== 'undefined' && require.main === module) {
   void runCli();
 }
 
 // parseArgs is exported for unit testing only (same pattern as resolveCliPath in bin/migrate.js)
-export { flushAndExit, main, parseArgs, runCli };
+export { createMigration, flushAndExit, main, parseArgs, runCli };