@lenne.tech/nest-server 12.0.0 → 12.1.0

package/src/core/common/interfaces/server-options.interface.ts

@@ -3,12 +3,12 @@ import { Type } from '@nestjs/common';
 import { GqlModuleAsyncOptions } from '@nestjs/graphql';
 import { JwtModuleOptions } from '@nestjs/jwt';
 import type { JwtSignOptions } from '@nestjs/jwt';
-import { MongooseModuleOptions } from '@nestjs/mongoose';
+import type { MongooseModuleOptions } from '@nestjs/mongoose';
 import { ServeStaticOptions } from '@nestjs/platform-express/interfaces/serve-static-options.interface';
 import { CronExpression } from '@nestjs/schedule';
 import type { DiskHealthIndicatorOptions, MongoosePingCheckSettings } from '@nestjs/terminus';
 import compression from 'compression';
-import { CollationOptions } from 'mongodb';
+import type { CollationOptions } from 'mongodb';
 import type { Connection } from 'mongoose';
 import type * as JSONTransport from 'nodemailer/lib/json-transport';
 import type * as SendmailTransport from 'nodemailer/lib/sendmail-transport';
@@ -17,6 +17,7 @@ import type * as SMTPPool from 'nodemailer/lib/smtp-pool';
 import * as SMTPTransport from 'nodemailer/lib/smtp-transport';
 import type * as StreamTransport from 'nodemailer/lib/stream-transport';
 
+import type { DataStore } from '../persistence/data-store.interface.js';
 import { Falsy } from '../types/falsy.type.js';
 import { IHubConfig } from '../../modules/hub/interfaces/hub-config.interface.js';
 import { IPermissions } from '../../modules/permissions/interfaces/permissions.interface.js';
@@ -799,8 +800,9 @@ export interface IBetterAuthPasskeyConfig {
   userVerification?: 'discouraged' | 'preferred' | 'required';
 
   /**
-   * Custom cookie name for WebAuthn challenge storage.
-   * Only used when challengeStorage is 'cookie'.
+   * Key of Better-Auth's WebAuthn challenge cookie. Better-Auth puts its cookie prefix in front of it
+   * (`iam.better-auth-passkey` by default); with database challenge storage the server reads the token from that
+   * cookie and maps it to the `challengeId` it returns instead.
    * @default 'better-auth-passkey'
    */
   webAuthnChallengeCookie?: string;
@@ -1262,8 +1264,10 @@ export interface IFileConfig {
    *
    * **Left unset, it is derived**, most capable first:
    * 1. `'s3'` when `s3.bucket` is configured
-   * 2. `'gridfs'` when a database is configured
-   * 3. `'filesystem'` when neither is
+   * 2. `'filesystem'` when `database` routes the file metadata to a SQL source — GridFS would put bytes and
+   *    metadata into MongoDB. Pod-local: mount `storageDir` as a volume, or configure `s3`
+   * 3. `'gridfs'` when a database is configured
+   * 4. `'filesystem'` when none is
    *
    * A configured-but-unreachable database is an error in its own right (Mongoose
    * fails the boot), never a reason to fall through to the disk.
@@ -1545,7 +1549,10 @@ export interface IMultiTenancy {
    *
    * Return `false` for an inactive tenant; any other value (including `undefined`) counts as active.
    * `context.connection` is the main database connection, for a lookup in the project's own tenant
-   * collection. Answers are cached for {@link cacheTtlMs}; after switching a tenant on or off, call
+   * collection; `context.store(modelName)` is the database-neutral alternative for a tenant model registered with
+   * `CorePersistenceModule.forFeature()`, and the one that works when that model is stored in a SQL database. It
+   * throws for a model not registered that way, so a misnamed or missing tenant model refuses the request rather than
+   * counting every tenant as active. Answers are cached for {@link cacheTtlMs}; after switching a tenant on or off, call
    * `CoreTenantGuard.invalidateTenant(tenantId)` (broadcast to every replica when Redis is
    * configured). A function cannot arrive through `NSC__*` / `NEST_SERVER_CONFIG` — set it in
    * `config.env.ts`.
@@ -1553,15 +1560,30 @@ export interface IMultiTenancy {
    * @example
    * ```typescript
    * multiTenancy: {
-   *   isTenantActive: async (tenantId, { connection }) =>
-   *     (await connection.collection('tenants').findOne({ _id: new Types.ObjectId(tenantId) }))?.active !== false,
+   *   // Any database: the tenant model registered with CorePersistenceModule.forFeature()
+   *   isTenantActive: async (tenantId, { store }) => (await store('Tenant').findById(tenantId))?.active !== false,
+   *   // MongoDB only
+   *   // isTenantActive: async (tenantId, { connection }) =>
+   *   //   (await connection.collection('tenants').findOne({ _id: new Types.ObjectId(tenantId) }))?.active !== false,
    * }
    * ```
    *
    * @default undefined (every tenant is active)
    * @since 11.42.0
    */
-  isTenantActive?: (tenantId: string, context: { connection: Connection }) => boolean | Promise<boolean>;
+  isTenantActive?: (
+    tenantId: string,
+    context: {
+      connection: Connection;
+      /**
+       * The data store of a model registered with `CorePersistenceModule.forFeature()` — the database-neutral lookup,
+       * also when the tenant model lives in a SQL database (`connection` reaches MongoDB only). Throws a
+       * `DataSourceConfigError` for a model that is not registered that way: an `undefined` here would read as
+       * "active" in a hook written with `?.`, and open every deactivated tenant.
+       */
+      store: (modelName: string) => DataStore<any>;
+    },
+  ) => boolean | Promise<boolean>;
 }
 
 /**
@@ -2151,6 +2173,73 @@ export interface IAi {
   systemPrompt?: string;
 }
 
+/**
+ * Library that executes the framework's SQL on a SQL data source. The framework compiles every query,
+ * policy and schema change itself, so the engine decides only what projects use for native queries —
+ * switching it on the same database is a configuration change.
+ */
+export type DatabaseSqlEngine = 'drizzle' | 'kysely' | 'typeorm';
+
+/**
+ * One data source: a connection URL plus, for SQL databases, the engine.
+ */
+export interface IDatabaseSourceConfig {
+  /**
+   * Connection URL of the role that OWNS the tables — used only to bring the schema up to date at boot, never for
+   * requests. Only valid on SQL URLs. Without it the application role only verifies the schema and the boot stops
+   * while changes are pending (plan §3.9: the application role owns nothing, so row-level security binds it).
+   */
+  ownerUrl?: string;
+
+  /**
+   * SQL engine for this source. Only valid on SQL URLs.
+   * @default the top-level `sqlEngine`, else 'typeorm'
+   */
+  sqlEngine?: DatabaseSqlEngine;
+
+  /**
+   * Connection URL. The scheme selects the database: `mongodb://`, `mongodb+srv://`, `postgres://`,
+   * `postgresql://`, `mysql://`, `mariadb://`.
+   */
+  url: string;
+}
+
+/**
+ * Data sources and which model is stored where.
+ *
+ * One default source serves every model; `sources` adds further ones and `models` lists the exceptions.
+ * A model may also name its source in code with `@PersistedModel({ dataSource })`; the configuration
+ * wins, so operations can move a model without a code change.
+ */
+export interface IDatabaseConfig {
+  /**
+   * Model name → source name, for the models that do not use the default source.
+   */
+  models?: Record<string, string>;
+
+  /**
+   * Owner connection of the default source (see `IDatabaseSourceConfig.ownerUrl`). Needs `url` beside it: an
+   * `NSC__DATABASE__OWNER_URL` replaces a `database` given as a URL string, so the boot refuses `ownerUrl` alone.
+   */
+  ownerUrl?: string;
+
+  /**
+   * Further sources by name, each a URL or a source configuration. The name `default` is reserved.
+   */
+  sources?: Record<string, IDatabaseSourceConfig | string>;
+
+  /**
+   * SQL engine for every SQL source that does not set its own.
+   * @default 'typeorm'
+   */
+  sqlEngine?: DatabaseSqlEngine;
+
+  /**
+   * URL of the default source. Without it, the `mongoose` configuration stays the default source.
+   */
+  url?: string;
+}
+
 /**
  * Options for the server
  */
@@ -2497,6 +2586,25 @@ export interface IServerOptions {
     CronExpression | CronJobConfigWithTimeZone | CronJobConfigWithUtcOffset | Date | Falsy | string
   >;
 
+  /**
+   * Data sources: where models are stored.
+   *
+   * - absent: the `mongoose` configuration is the only data source — exactly as before
+   * - a URL (`'postgres://…'`): that database is the default source for every model
+   * - an object: a default source plus further `sources` and per-model exceptions (`models`)
+   * - `false`: no database at all
+   *
+   * When this sets a default source and the project ALSO configures `mongoose` explicitly, that
+   * MongoDB becomes the additional source named `mongoose`. Connection URLs are never logged with
+   * their credentials.
+   *
+   * Which databases this version can actually wire is checked at boot; anything it cannot is refused
+   * with a named error before any connection is attempted.
+   *
+   * @default undefined (the `mongoose` configuration)
+   */
+  database?: false | IDatabaseConfig | string;
+
   /**
    * When true, logs a debug message when prepareInput() changes the input type during process().
    * Enable only for debugging — has performance cost due to JSON.stringify on every process() call.

package/src/core/common/interfaces/service-options.interface.ts

@@ -1,5 +1,5 @@
-import { CollationOptions } from 'mongodb';
-import { Model, PopulateOptions } from 'mongoose';
+import type { CollationOptions } from 'mongodb';
+import type { Model, PopulateOptions } from 'mongoose';
 
 import { FieldSelection } from '../types/field-selection.type.js';
 import { PrepareInputOptions } from './prepare-input-options.interface.js';

package/src/core/common/models/core-persistence.model.ts

@@ -1,12 +1,12 @@
 import { ObjectType } from '@nestjs/graphql';
-import { Schema } from '@nestjs/mongoose';
-import { Types } from 'mongoose';
+import { Schema } from '../persistence/mongo/mongoose-compat.js';
 
 import { Restricted } from '../decorators/restricted.decorator.js';
 import { UnifiedField } from '../decorators/unified-field.decorator.js';
 import { RoleEnum } from '../enums/role.enum.js';
 import { getStringIds } from '../helpers/db.helper.js';
 import { CoreModel } from './core-model.model.js';
+import { newObjectId } from '../persistence/mongo/mongoose-compat.js';
 
 /**
  * Metadata for persistent objects
@@ -33,7 +33,7 @@ export abstract class CorePersistenceModel extends CoreModel {
 
   @Restricted(RoleEnum.S_EVERYONE)
   get _id() {
-    return new Types.ObjectId(this.id);
+    return newObjectId(this.id);
   }
 
   /**

package/src/core/common/persistence/core-persistence.lifecycle.ts

@@ -0,0 +1,47 @@
+import { Injectable, Logger, OnApplicationBootstrap, OnApplicationShutdown, OnModuleInit } from '@nestjs/common';
+
+import { type ExpirySweep, scheduleExpirySweep } from './expiry-sweep.js';
+import { getPersistenceRuntime } from './persistence-runtime.registry.js';
+
+/**
+ * Opens the framework's lease store, releases the owner connections once the application is up, removes expired rows
+ * from SQL tables, and closes the connections of every SQL data source on shutdown. Registered by `CoreModule` only
+ * when a SQL source is configured; the sources themselves are opened while Nest creates the stores, so a misconfigured
+ * one stops the boot.
+ */
+@Injectable()
+export class CorePersistenceLifecycle implements OnApplicationBootstrap, OnApplicationShutdown, OnModuleInit {
+  protected readonly logger = new Logger('DataSources');
+  protected expirySweep?: ExpirySweep;
+
+  async onModuleInit(): Promise<void> {
+    // The lease table of the default source, while the boot's owner connection is still open — and an unsafe
+    // application role stops the boot here even when no model of the default source is registered
+    await getPersistenceRuntime()?.defaultLockStore();
+  }
+
+  async onApplicationBootstrap(): Promise<void> {
+    const runtime = getPersistenceRuntime();
+    // Every store exists by now: providers are created before any bootstrap hook runs
+    await runtime?.releaseBootConnections();
+    if (runtime) {
+      // A model's TTL (`expires`, `index: { expireAfterSeconds }`) is a plain index on SQL — this does the deleting
+      this.expirySweep = scheduleExpirySweep(
+        'models',
+        async () => {
+          for (const { deleted, model } of await runtime.sweepExpired()) {
+            if (deleted) {
+              this.logger.debug(`Removed ${deleted} expired ${model} record(s)`);
+            }
+          }
+        },
+        { logger: this.logger },
+      );
+    }
+  }
+
+  async onApplicationShutdown(): Promise<void> {
+    await this.expirySweep?.stop();
+    await getPersistenceRuntime()?.close();
+  }
+}

package/src/core/common/persistence/core-persistence.module.ts

@@ -0,0 +1,109 @@
+import { DynamicModule, Module, Provider } from '@nestjs/common';
+import type { ModelDefinition } from '@nestjs/mongoose';
+import { getConnectionToken, getModelToken } from './mongo/mongoose-compat.js';
+import type { Model } from 'mongoose';
+
+import { registerModelSchema } from './model-metadata.registry.js';
+import { MongooseDataStore } from './mongoose-data-store.js';
+import { getPersistedModelOptions, getPersistedModelOptionsByName } from './persisted-model.decorator.js';
+import {
+  bindStoreToModel,
+  getPersistenceRuntime,
+  registerDataStore,
+  registerPersistedModel,
+} from './persistence-runtime.registry.js';
+import { getStoreToken } from './persistence.tokens.js';
+import { guardRoutedModel, isStandInModel, standInModel } from './routed-model.guard.js';
+import { unavailableStore } from './unavailable-store.js';
+
+/**
+ * Database-neutral model registration — the counterpart of `MongooseModule.forFeature()`.
+ *
+ * Registers the models exactly as `MongooseModule.forFeature()` does (so `@InjectModel()` keeps working),
+ * records each model's descriptor, and provides a data store per model for `@InjectStore()`.
+ *
+ * @example
+ * ```typescript
+ * @Module({
+ *   imports: [CorePersistenceModule.forFeature([{ name: Project.name, schema: ProjectSchema }])],
+ *   providers: [ProjectService],
+ * })
+ * export class ProjectModule {}
+ * ```
+ */
+/** A model definition, plus where it is stored when the configuration does not say */
+export interface PersistenceModelDefinition extends ModelDefinition {
+  /** Source name (a key of `database.sources`); the configuration's `database.models` wins */
+  dataSource?: string;
+  /**
+   * The model class — its `@PersistedModel({ dataSource })` is read when `dataSource` is not given. Without it, the
+   * `@PersistedModel` class named like the model (`name`) is read
+   */
+  model?: abstract new (...args: any[]) => any;
+}
+
+@Module({})
+export class CorePersistenceModule {
+  static forFeature(models: PersistenceModelDefinition[]): DynamicModule {
+    for (const model of models) {
+      registerModelSchema(model.name, model.schema);
+      registerPersistedModel({
+        declaredSource:
+          model.dataSource ??
+          (model.model ? getPersistedModelOptions(model.model) : getPersistedModelOptionsByName(model.name))
+            ?.dataSource,
+        name: model.name,
+        schema: model.schema,
+      });
+    }
+    // The Mongoose models, as `MongooseModule.forFeature()` registers them (`createMongooseProviders()` of
+    // @nestjs/mongoose) — but without requiring a connection: where no MongoDB is configured (`NoMongoConnectionModule`,
+    // or none at all) the token gets a stand-in that refuses data access, and the model runs on its routed store.
+    const mongooseModels: Provider[] = models.flatMap((model) => [
+      {
+        inject: [{ optional: true, token: getConnectionToken() }],
+        provide: getModelToken(model.name),
+        useFactory: (connection?: null | { model: Function; models: Record<string, unknown> }) =>
+          connection
+            ? (connection.models[model.name] ?? connection.model(model.name, model.schema, model.collection))
+            : standInModel(model.name, model.schema),
+      },
+      ...(model.discriminators ?? []).map((discriminator) => ({
+        inject: [getModelToken(model.name)],
+        provide: getModelToken(discriminator.name),
+        useFactory: (parent: { discriminator: Function }) =>
+          parent.discriminator(discriminator.name, discriminator.schema, discriminator.value),
+      })),
+    ]);
+    const stores: Provider[] = models.map((model) => ({
+      inject: [getModelToken(model.name)],
+      provide: getStoreToken(model.name),
+      // Routed when the store is created, not when the module is declared: feature modules are usually evaluated
+      // before `CoreModule.forRoot()` has read the configuration
+      useFactory: async (mongooseModel: Model<any>) => {
+        const runtime = getPersistenceRuntime();
+        const store = runtime
+          ? await runtime.resolveStore(model.name, mongooseModel)
+          : isStandInModel(mongooseModel)
+            ? // No SQL source and no MongoDB connection: the project runs without a database (`database: false`)
+              unavailableStore(model.name, 'the project runs without a database (`database: false`)')
+            : new MongooseDataStore(mongooseModel);
+        registerDataStore(model.name, store);
+        bindStoreToModel(mongooseModel, store);
+        // A stand-in already refuses, naming the cause; a real Mongoose model of a model routed elsewhere is made to
+        if (!store.capabilities.mongoosePopulate && !isStandInModel(mongooseModel)) {
+          guardRoutedModel(mongooseModel, store);
+        }
+        return store;
+      },
+    }));
+    return {
+      exports: [
+        ...mongooseModels.map((provider) => (provider as { provide: string }).provide),
+        ...stores.map((store) => (store as { provide: string }).provide),
+      ],
+      module: CorePersistenceModule,
+      providers: [...mongooseModels, ...stores],
+    };
+  }
+}

package/src/core/common/persistence/data-source.config.ts

@@ -0,0 +1,271 @@
+import type {
+  DatabaseSqlEngine,
+  IDatabaseConfig,
+  IDatabaseSourceConfig,
+} from '../interfaces/server-options.interface.js';
+
+/**
+ * Resolution of the `database` configuration into named data sources, and of a model to its source.
+ *
+ * Pure functions: no connection is opened here. `CoreModule.forRoot()` resolves once at boot and refuses,
+ * before anything connects, what the running version cannot wire (`assertDataSourcesSupported`).
+ */
+
+export type DatabaseDriver = 'mariadb' | 'mongodb' | 'mysql' | 'postgres';
+
+export interface ResolvedDataSource {
+  driver: DatabaseDriver;
+  name: string;
+  /** Present on SQL sources that configure the owner connection */
+  ownerUrl?: string;
+  /** Present on SQL sources only */
+  sqlEngine?: DatabaseSqlEngine;
+  url: string;
+}
+
+export interface ResolvedDataSources {
+  /** Name of the default source; `undefined` when no database is configured */
+  defaultSource: string | undefined;
+  /** `database: false` — the project runs without any database */
+  disabled: boolean;
+  /** Configured exceptions: model name → source name */
+  modelSources: Record<string, string>;
+  sources: Record<string, ResolvedDataSource>;
+}
+
+export interface ResolveDataSourcesInput {
+  database?: false | IDatabaseConfig | string;
+  /** Whether the PROJECT configured `mongoose` — the framework's own fallback URI does not count */
+  explicitMongoose?: boolean;
+  /** The effective mongoose URI (project value or framework fallback) */
+  mongooseUri?: string;
+}
+
+/** A configuration this version cannot resolve or cannot wire. Thrown at boot, never at request time. */
+export class DataSourceConfigError extends Error {
+  constructor(message: string) {
+    super(`[database] ${message}`);
+    this.name = 'DataSourceConfigError';
+  }
+}
+
+export const DEFAULT_SOURCE = 'default';
+/** Source name an explicitly configured `mongoose` gets when `database` sets the default */
+export const MONGOOSE_SOURCE = 'mongoose';
+export const DEFAULT_SQL_ENGINE: DatabaseSqlEngine = 'typeorm';
+
+const SQL_ENGINES: readonly DatabaseSqlEngine[] = ['drizzle', 'kysely', 'typeorm'];
+const SOURCE_NAME = /^[A-Za-z][\w-]*$/;
+const DRIVERS: Record<string, DatabaseDriver> = {
+  'mariadb:': 'mariadb',
+  'mongodb+srv:': 'mongodb',
+  'mongodb:': 'mongodb',
+  'mysql:': 'mysql',
+  'postgres:': 'postgres',
+  'postgresql:': 'postgres',
+};
+
+/**
+ * The database a URL points at, taken from its scheme.
+ */
+export function driverFromUrl(url: string): DatabaseDriver {
+  const scheme = /^[a-z][a-z0-9+.-]*:/i.exec(url)?.[0]?.toLowerCase();
+  const driver = scheme ? DRIVERS[scheme] : undefined;
+  if (!driver) {
+    throw new DataSourceConfigError(
+      `Unsupported connection URL ${redactUrl(url)} — use mongodb://, mongodb+srv://, postgres://, postgresql://, mysql:// or mariadb://`,
+    );
+  }
+  return driver;
+}
+
+/**
+ * A connection URL reduced to scheme and host, so an error message or a log line never carries
+ * credentials, a path or query options (which may hold a password too).
+ */
+export function redactUrl(url: unknown): string {
+  if (typeof url !== 'string') {
+    return `<${typeof url}>`;
+  }
+  const scheme = /^([a-z][a-z0-9+.-]*:)\/\//i.exec(url);
+  if (!scheme) {
+    return '<unparsable URL>';
+  }
+  // The authority ends at the first `/`, `?` or `#`, and the credentials at the LAST `@` inside it — the WHATWG
+  // rule node-postgres parses by, so a password with an unencoded `@` (which it accepts) never reaches the result
+  const authority = url.slice(scheme[0].length).split(/[/?#]/, 1)[0];
+  return `${scheme[1]}//${authority.slice(authority.lastIndexOf('@') + 1)}`;
+}
+
+/**
+ * Resolve the `database` configuration (plus the mongoose configuration it extends) into named sources.
+ */
+export function resolveDataSources(input: ResolveDataSourcesInput): ResolvedDataSources {
+  const { database, explicitMongoose, mongooseUri } = input;
+
+  if (database === false) {
+    return { defaultSource: undefined, disabled: true, modelSources: {}, sources: {} };
+  }
+
+  const config: IDatabaseConfig = typeof database === 'string' ? { url: database } : (database ?? {});
+  if (typeof config !== 'object' || Array.isArray(config)) {
+    throw new DataSourceConfigError('`database` must be a URL, an object or false');
+  }
+  if (config.ownerUrl !== undefined && config.url === undefined) {
+    // The usual cause: `database` was a URL string and an NSC__DATABASE__* variable (e.g. NSC__DATABASE__OWNER_URL)
+    // was merged over it — the environment merge REPLACES a string with an object, so the URL is gone and every
+    // model would fall back to MongoDB without a word
+    throw new DataSourceConfigError(
+      'database.ownerUrl is set but database.url is not. A NSC__DATABASE__* variable replaces a `database` given as a ' +
+        'URL string; write `database: { url: … }` in the configuration (or set NSC__DATABASE__URL as well)',
+    );
+  }
+  const topEngine = config.sqlEngine === undefined ? undefined : checkEngine(config.sqlEngine, 'database.sqlEngine');
+
+  const sources: Record<string, ResolvedDataSource> = {};
+  if (config.url !== undefined) {
+    sources[DEFAULT_SOURCE] = buildSource(
+      DEFAULT_SOURCE,
+      { ownerUrl: config.ownerUrl, url: config.url },
+      topEngine,
+      'database.url',
+    );
+    // A project that keeps its MongoDB next to a new default reaches it as a named source
+    if (explicitMongoose && mongooseUri) {
+      sources[MONGOOSE_SOURCE] = buildSource(MONGOOSE_SOURCE, { url: mongooseUri }, undefined, 'mongoose.uri');
+    }
+  } else if (mongooseUri) {
+    sources[DEFAULT_SOURCE] = buildSource(DEFAULT_SOURCE, { url: mongooseUri }, undefined, 'mongoose.uri');
+  }
+
+  for (const [name, value] of Object.entries(config.sources ?? {})) {
+    if (name === DEFAULT_SOURCE || name === MONGOOSE_SOURCE) {
+      throw new DataSourceConfigError(`database.sources: the source name "${name}" is reserved`);
+    }
+    if (!SOURCE_NAME.test(name)) {
+      throw new DataSourceConfigError(
+        `database.sources: invalid source name "${name}" — use letters, digits, "_" and "-", starting with a letter`,
+      );
+    }
+    const source: IDatabaseSourceConfig = typeof value === 'string' ? { url: value } : value;
+    sources[name] = buildSource(name, source, topEngine, `database.sources.${name}`);
+  }
+
+  const modelSources: Record<string, string> = {};
+  for (const [model, source] of Object.entries(config.models ?? {})) {
+    if (typeof source !== 'string' || !sources[source]) {
+      throw new DataSourceConfigError(
+        `database.models.${model} names the source "${String(source)}", which is not configured (known: ${knownSources(sources)})`,
+      );
+    }
+    modelSources[model] = source;
+  }
+
+  return {
+    defaultSource: sources[DEFAULT_SOURCE] ? DEFAULT_SOURCE : undefined,
+    disabled: false,
+    modelSources,
+    sources,
+  };
+}
+
+/**
+ * The source a model is stored in: the configuration first, then the class's `@PersistedModel`
+ * declaration, then the default source. `undefined` when the project runs without a database.
+ */
+export function resolveModelSource(
+  resolved: ResolvedDataSources,
+  modelName: string,
+  declaredSource?: string,
+): string | undefined {
+  if (resolved.disabled) {
+    return undefined;
+  }
+  const configured = resolved.modelSources[modelName];
+  if (configured) {
+    return configured;
+  }
+  if (declaredSource !== undefined) {
+    if (!resolved.sources[declaredSource]) {
+      throw new DataSourceConfigError(
+        `@PersistedModel on ${modelName} names the source "${declaredSource}", which is not configured (known: ${knownSources(resolved.sources)})`,
+      );
+    }
+    return declaredSource;
+  }
+  return resolved.defaultSource;
+}
+
+/**
+ * Refuse what the running version cannot wire, with a message naming the setting.
+ *
+ * PostgreSQL, MySQL and MariaDB sources (default or additional) are wired next to the MongoDB connection, and since
+ * 12.1.0 a project runs without any database (`database: false`); a second MongoDB connection is refused. Refusing at
+ * boot is the point: a configuration that is accepted and then silently served by the wrong database is the outcome to
+ * avoid.
+ */
+export function assertDataSourcesSupported(resolved: ResolvedDataSources): void {
+  for (const source of Object.values(resolved.sources)) {
+    if (source.driver === 'mongodb' && source.name !== DEFAULT_SOURCE && source.name !== MONGOOSE_SOURCE) {
+      throw new DataSourceConfigError(
+        `The additional MongoDB source "${source.name}" (${redactUrl(source.url)}) is not supported by this version yet — one MongoDB connection only`,
+      );
+    }
+  }
+}
+
+/** Whether any configured source is a MongoDB — the connection CoreModule opens, and the libraries it needs */
+export function usesMongoDb(resolved: ResolvedDataSources): boolean {
+  return Object.values(resolved.sources).some((source) => source.driver === 'mongodb');
+}
+
+/** Whether any configured source is a SQL database */
+export function hasSqlSource(resolved: ResolvedDataSources): boolean {
+  return Object.values(resolved.sources).some((source) => source.driver !== 'mongodb');
+}
+
+function buildSource(
+  name: string,
+  source: IDatabaseSourceConfig,
+  fallbackEngine: DatabaseSqlEngine | undefined,
+  path: string,
+): ResolvedDataSource {
+  if (!source || typeof source !== 'object' || typeof source.url !== 'string' || !source.url) {
+    throw new DataSourceConfigError(`${path}: the url must be a non-empty string`);
+  }
+  const driver = driverFromUrl(source.url);
+  if (driver === 'mongodb') {
+    if (source.ownerUrl !== undefined) {
+      throw new DataSourceConfigError(`${path}: ownerUrl applies to SQL sources only, not to ${redactUrl(source.url)}`);
+    }
+    if (source.sqlEngine !== undefined) {
+      throw new DataSourceConfigError(
+        `${path}: sqlEngine applies to SQL sources only, not to ${redactUrl(source.url)}`,
+      );
+    }
+    return { driver, name, url: source.url };
+  }
+  const engine =
+    source.sqlEngine === undefined
+      ? (fallbackEngine ?? DEFAULT_SQL_ENGINE)
+      : checkEngine(source.sqlEngine, `${path}.sqlEngine`);
+  if (source.ownerUrl !== undefined) {
+    if (typeof source.ownerUrl !== 'string' || !source.ownerUrl || driverFromUrl(source.ownerUrl) !== driver) {
+      throw new DataSourceConfigError(`${path}: ownerUrl must be a ${driver} URL of the same database`);
+    }
+    return { driver, name, ownerUrl: source.ownerUrl, sqlEngine: engine, url: source.url };
+  }
+  return { driver, name, sqlEngine: engine, url: source.url };
+}
+
+function checkEngine(value: unknown, path: string): DatabaseSqlEngine {
+  if (!SQL_ENGINES.includes(value as DatabaseSqlEngine)) {
+    throw new DataSourceConfigError(`${path}: "${String(value)}" is not a known sqlEngine (${SQL_ENGINES.join(', ')})`);
+  }
+  return value as DatabaseSqlEngine;
+}
+
+function knownSources(sources: Record<string, ResolvedDataSource>): string {
+  const names = Object.keys(sources);
+  return names.length ? names.join(', ') : 'none';
+}