@lenne.tech/nest-server 12.0.0 → 12.1.0

package/src/core/modules/tus/core-tus.service.ts

@@ -3,7 +3,8 @@ import { ModuleRef } from '@nestjs/core';
 import { FileStore } from '@tus/file-store';
 import { Server, Upload } from '@tus/server';
 import * as fs from 'fs';
-import { type Connection, mongo } from 'mongoose';
+import type { Connection } from 'mongoose';
+import type { mongo } from 'mongoose';
 import * as path from 'path';
 import { Readable } from 'stream';
 
@@ -14,13 +15,10 @@ import { ConfigService } from '../../common/services/config.service.js';
 import { CoreRedisService } from '../../common/services/core-redis.service.js';
 import { CoreS3Service } from '../../common/services/core-s3.service.js';
 import { getTenantContextResolver } from '../../common/services/core-tenant-context.registry.js';
+import { fileMetadataCollection } from '../file/file-metadata.store.js';
 import { resolveFileStorage } from '../file/file-storage.helper.js';
-import {
-  DEFAULT_FILESYSTEM_DIR,
-  FILESYSTEM_FILES_COLLECTION,
-  FilesystemFileHelper,
-} from '../file/filesystem-file.helper.js';
-import { S3_FILES_COLLECTION, S3FileHelper } from '../file/s3-file.helper.js';
+import { DEFAULT_FILESYSTEM_DIR, FilesystemFileHelper } from '../file/filesystem-file.helper.js';
+import { S3FileHelper } from '../file/s3-file.helper.js';
 import { TUS_FILE_ID_HEADER, TUS_OWNER_METADATA_KEY, TUS_TENANT_METADATA_KEY } from './tus.constants.js';
 import { TusRedisLocker } from './tus-redis-locker.js';
 import {
@@ -29,6 +27,7 @@ import {
   normalizeTusConfig,
   parseExpirationTime,
 } from './interfaces/tus-config.interface.js';
+import { createGridFsBucket } from '../../common/persistence/mongo/mongoose-compat.js';
 
 /**
  * Optional dependencies of CoreTusService.
@@ -141,8 +140,8 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
       return;
     }
 
-    // Initialize GridFS bucket
-    this.files = new mongo.GridFSBucket(this.connection.db, { bucketName: 'fs' });
+    // Initialize GridFS bucket — where MongoDB is connected; finished uploads go to GridFS only on that driver
+    this.files = this.connection?.db ? createGridFsBucket(this.connection.db, { bucketName: 'fs' }) : undefined;
 
     // Ensure upload directory exists
     const uploadDir = this.config.uploadDir || DEFAULT_TUS_CONFIG.uploadDir;
@@ -233,7 +232,7 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
       if (this.canCopyWithinS3(upload)) {
         const fileInfo = await S3FileHelper.copyFile(
           this.options.s3Service,
-          this.connection.db.collection(S3_FILES_COLLECTION),
+          fileMetadataCollection(this.connection, 's3'),
           {
             contentLength: upload.size,
             contentType,
@@ -260,14 +259,14 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
       if (this.fileStorageDriver === 'filesystem') {
         fileInfo = await FilesystemFileHelper.writeFile(
           this.fileStorageDir,
-          this.connection.db.collection(FILESYSTEM_FILES_COLLECTION),
+          fileMetadataCollection(this.connection, 'filesystem'),
           { body: readStream, contentType, filename, metadata: fileMetadata },
         );
         this.logger.debug(`Upload ${upload.id} migrated to the filesystem as ${fileInfo._id} (filename: ${filename})`);
       } else if (this.s3FileStorage) {
         fileInfo = await S3FileHelper.writeFile(
           this.options.s3Service,
-          this.connection.db.collection(S3_FILES_COLLECTION),
+          fileMetadataCollection(this.connection, 's3'),
           // Streamed with the length TUS already knows, so a multi-GB resumable upload is never
           // materialised in memory.
           { body: readStream, contentLength: upload.size, contentType, filename, metadata: fileMetadata },

package/src/core/modules/tus/tus.module.ts

@@ -1,7 +1,7 @@
 import { DynamicModule, Global, Logger, Module, OnModuleInit, Type } from '@nestjs/common';
 import { PATH_METADATA } from '@nestjs/common/constants';
 import { ModuleRef } from '@nestjs/core';
-import { getConnectionToken } from '@nestjs/mongoose';
+import { getConnectionToken } from '../../common/persistence/mongo/mongoose-compat.js';
 import type { Connection } from 'mongoose';
 
 import { ITusConfig } from '../../common/interfaces/server-options.interface.js';

package/src/core/modules/user/core-user.model.ts

@@ -1,7 +1,7 @@
 import { ObjectType } from '@nestjs/graphql';
-import { Schema as MongooseSchema, Prop, raw } from '@nestjs/mongoose';
+import { Prop, raw, Schema as MongooseSchema } from '../../common/persistence/mongo/mongoose-compat.js';
 import { ApiExtraModels, ApiProperty } from '@nestjs/swagger';
-import { Document } from 'mongoose';
+import type { Document } from 'mongoose';
 
 import { Restricted } from '../../common/decorators/restricted.decorator.js';
 import { UnifiedField } from '../../common/decorators/unified-field.decorator.js';

package/src/core/modules/user/core-user.service.ts

@@ -2,7 +2,7 @@ import { BadRequestException, Logger, NotFoundException, UnprocessableEntityExce
 import bcrypt from 'bcrypt';
 import * as crypto from 'crypto';
 import { sha256 } from 'js-sha256';
-import { Document, Model } from 'mongoose';
+import type { Document, Model } from 'mongoose';
 
 import { looksLikeSystemRole, SYSTEM_ROLE_PREFIX } from '../../common/enums/role.enum.js';
 import { accessDeniedException } from '../../common/exceptions/access-denied.exception.js';
@@ -11,6 +11,7 @@ import { revalidateWsConnectionsOf } from '../../common/helpers/graphql-ws-conne
 import { maskEmail } from '../../common/helpers/logging.helper.js';
 import { assignPlain, isQueryableString, prepareServiceOptionsForCreate } from '../../common/helpers/input.helper.js';
 import { ServiceOptions } from '../../common/interfaces/service-options.interface.js';
+import { isWellFormedId } from '../../common/persistence/id-format.js';
 import { ConfigService } from '../../common/services/config.service.js';
 import { CrudService } from '../../common/services/crud.service.js';
 import { ErrorCode } from '../error-code/error-codes.js';
@@ -125,7 +126,9 @@ export abstract class CoreUserService<
         // window exists on a freshly deployed production database. The index
         // remains the backstop for truly concurrent duplicate requests.
         if (data.input?.email) {
-          const existing = await this.mainDbModel.findOne({ email: data.input.email }).lean().exec();
+          const existing = this.usesNeutralStore
+            ? await this.dataStore.findOne({ email: data.input.email })
+            : await this.mainDbModel.findOne({ email: data.input.email }).lean().exec();
           if (existing) {
             throw new BadRequestException('Email address already in use');
           }
@@ -133,15 +136,19 @@ export abstract class CoreUserService<
 
         // Create user with verification token
         const currentUserId = serviceOptions?.currentUser?._id;
-        const createdUser = new this.mainDbModel({
+        const fields = {
           ...data.input,
           createdBy: currentUserId,
           updatedBy: currentUserId,
           verificationToken: crypto.randomBytes(32).toString('hex'),
-        });
+        };
+        const createdUser = this.usesNeutralStore ? undefined : new this.mainDbModel(fields);
 
         // Distinguish between different error messages when saving
         try {
+          if (!createdUser) {
+            return await this.dataStore.insert(fields);
+          }
           await createdUser.save();
         } catch (error) {
           if (error?.errors?.email?.kind === 'unique' || error?.code === 11000) {
@@ -158,11 +165,27 @@ export abstract class CoreUserService<
     );
   }
 
+  /**
+   * The stored user matching `where`: the Mongoose document on MongoDB — what this service always worked with — and
+   * the plain record when the user model is routed to a SQL store
+   */
+  protected async findStoredUser(where: Record<string, unknown>): Promise<any> {
+    return this.usesNeutralStore ? this.dataStore.findOne(where) : this.mainDbModel.findOne(where).exec();
+  }
+
+  /** Write `changes` to a stored user (as `findStoredUser()` returned it) and return it as stored afterwards */
+  protected async saveStoredUser(stored: any, changes: Record<string, unknown>): Promise<any> {
+    if (this.usesNeutralStore) {
+      return this.dataStore.updateById(stored.id, changes as any);
+    }
+    return assignPlain(stored, changes).save();
+  }
+
   /**
    * Get user via email
    */
   async getViaEmail(email: string, serviceOptions?: ServiceOptions): Promise<TUser> {
-    const dbObject = await this.mainDbModel.findOne({ email }).exec();
+    const dbObject = await this.findStoredUser({ email });
     if (!dbObject) {
       throw new NotFoundException(`No user found with email: ${email}`);
     }
@@ -181,6 +204,10 @@ export abstract class CoreUserService<
    * @returns User object or null if not found
    */
   async getByIdOrIamId(idOrIamId: string): Promise<null | TUser> {
+    if (this.usesNeutralStore) {
+      const byId = isWellFormedId(String(idOrIamId)) ? await this.dataStore.findById(String(idOrIamId)) : null;
+      return (byId ?? (await this.dataStore.findOne({ iamId: idOrIamId }))) as null | TUser;
+    }
     try {
       // First, try to find by MongoDB _id
       const byId = await this.mainDbModel.findById(idOrIamId).exec();
@@ -204,7 +231,7 @@ export abstract class CoreUserService<
       return false;
     }
 
-    const user = await this.mainDbModel.findOne({ verificationToken: token }).exec();
+    const user = await this.findStoredUser({ verificationToken: token });
 
     if (!user) {
       throw new NotFoundException(`No user found with verify token: ${token}`);
@@ -222,7 +249,7 @@ export abstract class CoreUserService<
       throw new NotFoundException(ErrorCode.INVALID_TOKEN);
     }
 
-    const dbObject = await this.mainDbModel.findOne({ verificationToken: token }).exec();
+    const dbObject = await this.findStoredUser({ verificationToken: token });
     if (!dbObject) {
       throw new NotFoundException(`No user found with verify token: ${token}`);
     }
@@ -238,6 +265,9 @@ export abstract class CoreUserService<
     return this.process(
       async () => {
         // Update and return user
+        if (this.usesNeutralStore) {
+          return this.dataStore.updateById(dbObject.id, { verified: true, verifiedAt: new Date() } as any);
+        }
         await this.mainDbModel.updateOne({ _id: dbObject.id }, { verified: true, verifiedAt: new Date() }).exec();
         // Return the updated user
         return await this.mainDbModel.findById(dbObject.id).exec();
@@ -262,7 +292,7 @@ export abstract class CoreUserService<
       throw new NotFoundException(ErrorCode.LINK_INVALID_OR_EXPIRED);
     }
 
-    const dbObject = await this.mainDbModel.findOne({ passwordResetToken: token }).exec();
+    const dbObject = await this.findStoredUser({ passwordResetToken: token });
 
     // An EXPIRED token is answered exactly like an unknown one — same exception, same 404. The
     // distinction would tell a caller holding a stale token that it was once real and belongs to a
@@ -270,12 +300,15 @@ export abstract class CoreUserService<
     if (dbObject && this.isPasswordResetTokenExpired(dbObject.passwordResetTokenExpiresAt)) {
       // Burn it on sight rather than leaving it to be retried. It is worthless now, and a value
       // that stays in the row is one a later change could start honouring again.
-      await this.mainDbModel
-        // `$unset`, not `$set: null` — a null still counts as present, so it would keep an entry
-        // in the partial index the token field carries and grow it by one per user who ever
-        // requested a reset.
-        .updateOne({ _id: dbObject._id }, { $unset: { passwordResetToken: 1, passwordResetTokenExpiresAt: 1 } })
-        .exec();
+      // `$unset`, not `$set: null` — a null still counts as present, so it would keep an entry
+      // in the partial index the token field carries and grow it by one per user who ever
+      // requested a reset.
+      const burn = { $unset: { passwordResetToken: 1 as const, passwordResetTokenExpiresAt: 1 as const } };
+      if (this.usesNeutralStore) {
+        await this.dataStore.updateById(dbObject.id, burn);
+      } else {
+        await this.mainDbModel.updateOne({ _id: dbObject._id }, burn).exec();
+      }
       this.userServiceLogger.debug(`Rejected an expired password-reset token for ${maskEmail(dbObject.email)}`);
     }
 
@@ -325,7 +358,7 @@ export abstract class CoreUserService<
         }
 
         // Update Legacy Auth password
-        const updatedUser = await assignPlain(dbObject, {
+        const updatedUser = await this.saveStoredUser(dbObject, {
           password: await bcrypt.hash(newPassword, 10),
           passwordResetToken: null,
           passwordResetTokenExpiresAt: null,
@@ -338,7 +371,7 @@ export abstract class CoreUserService<
           // Without this, "the reset now lands in both stores" would still leave the account
           // reachable with the credential the reset was meant to retire.
           refreshTokens: {},
-        }).save();
+        });
 
         // Sync password to Better-Auth (IAM) if mapper is available
         // This ensures users can sign in via IAM after password reset
@@ -455,7 +488,7 @@ export abstract class CoreUserService<
     }
 
     // Get user
-    const dbObject = await this.mainDbModel.findOne({ email }).exec();
+    const dbObject = await this.findStoredUser({ email });
     if (!dbObject) {
       const preventEnumeration =
         this.configService.getFastButReadOnly('auth')?.passwordReset?.preventUserEnumeration !== false;
@@ -478,6 +511,12 @@ export abstract class CoreUserService<
     const user = await this.process(
       async () => {
         // Set reset token and return
+        if (this.usesNeutralStore) {
+          return this.dataStore.updateById(dbObject.id, {
+            passwordResetToken: token,
+            passwordResetTokenExpiresAt: expiresAt,
+          } as any);
+        }
         dbObject.passwordResetToken = token;
         dbObject.passwordResetTokenExpiresAt = expiresAt;
 
@@ -646,7 +685,9 @@ export abstract class CoreUserService<
     // Update and return user
     return this.process(
       async () => {
-        const user = await this.mainDbModel.findByIdAndUpdate(userId, { roles }).exec();
+        const user = this.usesNeutralStore
+          ? await this.dataStore.updateById(String(userId), { roles } as any)
+          : await this.mainDbModel.findByIdAndUpdate(userId, { roles }).exec();
 
         // Invalidate BetterAuth user cache so changed roles take effect immediately
         if (this.options?.betterAuthUserMapper && (user as any)?.iamId) {
@@ -680,7 +721,9 @@ export abstract class CoreUserService<
    */
   override async update(id: string, input: TUserInput, serviceOptions?: ServiceOptions): Promise<TUser> {
     // Get the current user before update to detect email changes
-    const oldUser = (await this.mainDbModel.findById(id).lean().exec()) as null | TUser;
+    const oldUser = (
+      this.usesNeutralStore ? await this.dataStore.findById(id) : await this.mainDbModel.findById(id).lean().exec()
+    ) as null | TUser;
     const oldEmail = oldUser?.email;
 
     this.assertCredentialChangeAllowed(oldUser, input, serviceOptions);
@@ -710,6 +753,37 @@ export abstract class CoreUserService<
       }
     }
 
+    // Sync name change to IAM if firstName/lastName was changed and mapper is available.
+    // Without this, the next sign-in reverse-syncs the STALE Better-Auth `name` back into
+    // firstName/lastName (linkOrCreateUser), silently discarding the user's edit.
+    if (this.options?.betterAuthUserMapper && (input.firstName !== undefined || input.lastName !== undefined)) {
+      // The names come from the STORED record, not from `updatedUser`: that one went through the
+      // output pipeline, which strips every field the caller may not read. A caller allowed to
+      // edit one name field but not to read the other would otherwise sync a truncated name.
+      const stored = (
+        this.usesNeutralStore
+          ? await this.dataStore.findById(id, { select: ['email', 'firstName', 'lastName'] })
+          : await this.mainDbModel.findById(id).select('email firstName lastName').lean().exec()
+      ) as null | TUser;
+      // An emptied name is synced as well. Skipping it left the old Better-Auth `name` in place,
+      // and the next IAM sign-in wrote it back into the fields the user had just cleared.
+      const fullName = [stored?.firstName, stored?.lastName].filter(Boolean).join(' ');
+      const currentEmail = stored?.email ?? oldEmail;
+      if (currentEmail) {
+        try {
+          const synced = await this.options.betterAuthUserMapper.syncNameChangeFromLegacy(currentEmail, fullName);
+          if (synced) {
+            this.userServiceLogger.debug(`Synced name change from Legacy to IAM for user ${maskEmail(currentEmail)}`);
+          }
+        } catch (error) {
+          this.userServiceLogger.warn(
+            `Failed to sync name change to IAM for ${maskEmail(currentEmail)}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+          );
+          // Don't throw - name sync failure shouldn't block the update
+        }
+      }
+    }
+
     // Sync password change to IAM if password was changed and mapper is available
     if (this.options?.betterAuthUserMapper && passwordForIamSync && oldUser?.email) {
       try {
@@ -815,7 +889,11 @@ export abstract class CoreUserService<
    */
   override async delete(id: string, serviceOptions?: ServiceOptions): Promise<TUser> {
     // Get the user before deletion to cleanup IAM data
-    const user = (await this.mainDbModel.findById(id).lean().exec()) as null | (TUser & { _id: any });
+    const user = (
+      this.usesNeutralStore
+        ? await this.dataStore.findById(id).then((record) => record && { ...record, _id: record.id })
+        : await this.mainDbModel.findById(id).lean().exec()
+    ) as null | (TUser & { _id: any });
 
     // Perform the deletion
     const deletedUser = await super.delete(id, serviceOptions);

package/src/core.module.ts

@@ -10,10 +10,8 @@ import {
 } from '@nestjs/common';
 import { APP_FILTER, APP_INTERCEPTOR, APP_PIPE, DiscoveryModule } from '@nestjs/core';
 import { GraphQLModule } from '@nestjs/graphql';
-import { MongooseModule } from '@nestjs/mongoose';
 import type { Context } from 'graphql-ws';
-import graphqlUploadExpress from 'graphql-upload/graphqlUploadExpress.js';
-import mongoose from 'mongoose';
+import graphqlUploadExpress from 'graphql-upload/graphqlUploadExpress.mjs';
 
 import { MongooseCastErrorFilter } from './core/common/filters/mongoose-cast-error.filter.js';
 import { merge } from './core/common/helpers/config.helper.js';
@@ -40,6 +38,19 @@ import {
 } from './core/common/interfaces/server-options.interface.js';
 import { RequestContextMiddleware } from './core/common/middleware/request-context.middleware.js';
 import { SecurityHeadersMiddleware } from './core/common/middlewares/security-headers.middleware.js';
+import { CorePersistenceLifecycle } from './core/common/persistence/core-persistence.lifecycle.js';
+import { CorePersistenceModule } from './core/common/persistence/core-persistence.module.js';
+import {
+  assertDataSourcesSupported,
+  DataSourceConfigError,
+  hasSqlSource,
+  usesMongoDb,
+  resolveDataSources,
+} from './core/common/persistence/data-source.config.js';
+import { DataSourceRuntime } from './core/common/persistence/data-source.runtime.js';
+import { requireMongoPackages } from './core/common/persistence/mongo/mongo-packages.js';
+import { NoMongoConnectionModule } from './core/common/persistence/mongo/no-mongo-connection.module.js';
+import { setPersistenceRuntime } from './core/common/persistence/persistence-runtime.registry.js';
 import { MapAndValidatePipe } from './core/common/pipes/map-and-validate.pipe.js';
 import { ComplexityPlugin } from './core/common/plugins/complexity.plugin.js';
 import { mongooseIdPlugin } from './core/common/plugins/mongoose-id.plugin.js';
@@ -65,6 +76,7 @@ import { CoreBetterAuthModule } from './core/modules/better-auth/core-better-aut
 import { CoreBetterAuthService } from './core/modules/better-auth/core-better-auth.service.js';
 import { ErrorCodeModule } from './core/modules/error-code/error-code.module.js';
 import { CoreFileAccessAuditInitializer } from './core/modules/file/core-file-access-audit.initializer.js';
+import { FILE_METADATA_MODELS } from './core/modules/file/file-metadata.models.js';
 import { applyFileRoles, warnOnPresignedDownloadsWithRestrictedRoles } from './core/modules/file/file-roles.helper.js';
 import { CoreHealthCheckModule } from './core/modules/health-check/core-health-check.module.js';
 import { CoreHubModule } from './core/modules/hub/core-hub.module.js';
@@ -267,6 +279,25 @@ export class CoreModule implements NestModule {
       options,
     );
 
+    // Resolve where models are stored, and refuse what this version cannot wire before anything connects.
+    // `explicitMongoose` separates a project's own mongoose config from the fallback URI merged in above.
+    const dataSources = resolveDataSources({
+      database: options?.database,
+      explicitMongoose: !!options?.mongoose,
+      mongooseUri: config.mongoose?.uri,
+    });
+    assertDataSourcesSupported(dataSources);
+    // A MongoDB default source set through `database` is the database Mongoose connects to. Without this the
+    // URL passed the guard and the connection still used the fallback URI — another database, silently.
+    const defaultSource = dataSources.defaultSource ? dataSources.sources[dataSources.defaultSource] : undefined;
+    if (defaultSource?.driver === 'mongodb') {
+      config.mongoose.uri = defaultSource.url;
+    }
+    // A SQL source routes the models registered with CorePersistenceModule.forFeature() to it; without one, nothing
+    // is installed and every model keeps its Mongoose store
+    const sqlSources = hasSqlSource(dataSources);
+    setPersistenceRuntime(sqlSources ? new DataSourceRuntime(dataSources) : undefined);
+
     // Wrap connectionFactory to add security plugins (password hashing, role guard)
     const originalConnectionFactory = config.mongoose?.options?.connectionFactory;
     config.mongoose.options = config.mongoose.options || {};
@@ -345,6 +376,9 @@ export class CoreModule implements NestModule {
       TemplateService,
       MailjetService,
     ];
+    if (sqlSources) {
+      providers.push(CorePersistenceLifecycle);
+    }
 
     // Add ComplexityPlugin only if not in Vitest (Vitest has dual GraphQL loading issue) and GraphQL is enabled
     if (!process.env.VITEST && isGraphQlEnabled) {
@@ -410,10 +444,17 @@ export class CoreModule implements NestModule {
       providers.push(ModelDocService);
     }
 
+    // MongoDB is connected only where a source uses it — the `mongoose` configuration, or `database` naming MongoDB (or
+    // absent, which keeps today's single MongoDB). A project on PostgreSQL alone connects to no MongoDB and needs none
+    // of its libraries (optional peers since 12.1.0); configured without them, the boot fails with what to install.
+    const mongoPackages = usesMongoDb(dataSources)
+      ? requireMongoPackages('The MongoDB data source (the `mongoose` configuration, or `database` naming MongoDB)')
+      : undefined;
+
     // Set strict query to false by default
     // See: https://github.com/Automattic/mongoose/issues/10763
     // and: https://mongoosejs.com/docs/guide.html#strictQuery
-    mongoose.set('strictQuery', config.mongoose.strictQuery || false);
+    mongoPackages?.mongoose.set('strictQuery', config.mongoose.strictQuery || false);
 
     // Opt the MongoDB driver into command monitoring only when the Hub query profiler is enabled
     // (zero cost otherwise). An explicit `monitorCommands: false` by the consumer wins — the profiler
@@ -427,7 +468,14 @@ export class CoreModule implements NestModule {
 
     // DiscoveryModule: CoreFileAccessAuditInitializer needs the registered controller/resolver
     // classes, which only exist once Nest has built its route table.
-    const imports: any[] = [DiscoveryModule, MongooseModule.forRoot(config.mongoose.uri, config.mongoose.options)];
+    const imports: any[] = [
+      DiscoveryModule,
+      mongoPackages
+        ? mongoPackages.nestMongoose.MongooseModule.forRoot(config.mongoose.uri, config.mongoose.options)
+        : NoMongoConnectionModule,
+      // The metadata of S3 and filesystem files, routed like every model: on a SQL default source it lives in tables
+      CorePersistenceModule.forFeature(FILE_METADATA_MODELS),
+    ];
 
     if (isGraphQlEnabled && config.graphQl) {
       imports.push(
@@ -518,6 +566,13 @@ export class CoreModule implements NestModule {
     // IAM-only mode: enabled unless explicitly disabled
     // Legacy mode: enabled only if explicitly enabled
     const isBetterAuthEnabled = isIamOnlyMode ? !isExplicitlyDisabled : isExplicitlyEnabled;
+    // Better-Auth keeps its users in a database; `database: false` has none to give it
+    if (dataSources.disabled && isBetterAuthEnabled) {
+      throw new DataSourceConfigError(
+        '`database: false` runs without a database, and Better-Auth keeps its users in one — set `betterAuth: false` ' +
+          'or configure a data source',
+      );
+    }
 
     const isAutoRegister = typeof betterAuthConfig === 'object' && betterAuthConfig?.autoRegister === true;
     // autoRegister: false means the project imports its own BetterAuthModule separately

package/src/index.ts

@@ -83,6 +83,29 @@ export * from './core/common/middlewares/security-headers.middleware.js';
 export * from './core/common/models/core-model.model.js';
 export * from './core/common/models/core-persistence.model.js';
 export * from './core/common/models/pagination-info.model.js';
+export * from './core/common/persistence/core-persistence.module.js';
+export * from './core/common/persistence/data-source.config.js';
+export * from './core/common/persistence/data-store.interface.js';
+export * from './core/common/persistence/id-format.js';
+export * from './core/common/persistence/inject-store.decorator.js';
+export * from './core/common/persistence/lock-store.interface.js';
+export * from './core/common/persistence/model-descriptor.interface.js';
+export * from './core/common/persistence/model-metadata.registry.js';
+export * from './core/common/persistence/mongo/mongo-packages.js';
+export * from './core/common/persistence/mongo/mongoose-compat.js';
+export * from './core/common/persistence/mongo-lock-store.js';
+export * from './core/common/persistence/mongoose-data-store.js';
+export * from './core/common/persistence/persisted-model.decorator.js';
+export * from './core/common/persistence/persistence.tokens.js';
+export * from './core/common/persistence/persistence-runtime.registry.js';
+export * from './core/common/persistence/unsupported-capability.error.js';
+export * from './core/common/persistence/sql/mysql/mysql-data-store.js';
+export * from './core/common/persistence/sql/mysql/mysql-lock-store.js';
+export * from './core/common/persistence/sql/postgres/postgres-lock-store.js';
+export * from './core/common/persistence/sql/sql-data-store.js';
+export * from './core/common/persistence/sql/sql-errors.js';
+export * from './core/common/persistence/sql/sql-executor.factory.js';
+export * from './core/common/persistence/sql/sql-executor.interface.js';
 export * from './core/common/pipes/check-input.pipe.js';
 export * from './core/common/pipes/map-and-validate.pipe.js';
 export * from './core/common/plugins/complexity.plugin.js';
@@ -122,6 +145,7 @@ export * from './core/common/types/id.type.js';
 export * from './core/common/types/ids.type.js';
 export * from './core/common/types/is-one-of.type.js';
 export * from './core/common/types/maybe-promise.type.js';
+export * from './core/common/types/object-id-like.type.js';
 export * from './core/common/types/plain-input.type.js';
 export * from './core/common/types/plain-object-deep.type.js';
 export * from './core/common/types/plain-object.type.js';
@@ -204,6 +228,8 @@ export * from './core/modules/file/core-file.controller.js';
 export * from './core/modules/file/core-file.resolver.js';
 export * from './core/modules/file/core-file.service.js';
 export * from './core/modules/file/file-access.helper.js';
+export * from './core/modules/file/file-metadata.models.js';
+export * from './core/modules/file/file-metadata.store.js';
 export * from './core/modules/file/file-roles.helper.js';
 export * from './core/modules/file/file-storage.helper.js';
 export * from './core/modules/file/filesystem-file.helper.js';

package/src/server/common/models/persistence.model.ts

@@ -1,12 +1,12 @@
 import { ObjectType } from '@nestjs/graphql';
 import { ApiExtraModels } from '@nestjs/swagger';
-import { Types } from 'mongoose';
-import mongoose from 'mongoose';
+import type { Types } from 'mongoose';
 
 import { Restricted } from '../../../core/common/decorators/restricted.decorator.js';
 import { UnifiedField } from '../../../core/common/decorators/unified-field.decorator.js';
 import { RoleEnum } from '../../../core/common/enums/role.enum.js';
 import { CorePersistenceModel } from '../../../core/common/models/core-persistence.model.js';
+import { objectIdType } from '../../../core/common/persistence/mongo/mongoose-compat.js';
 import { User } from '../../modules/user/user.model.js';
 
 /**
@@ -33,7 +33,7 @@ export abstract class PersistenceModel extends CorePersistenceModel {
   @UnifiedField({
     description: 'ID of the user who created the object',
     isOptional: true,
-    mongoose: { ref: 'User', type: mongoose.Schema.Types.ObjectId },
+    mongoose: { ref: 'User', type: objectIdType() },
     roles: RoleEnum.ADMIN,
     swaggerApiOptions: { type: String },
     type: () => User,
@@ -48,7 +48,7 @@ export abstract class PersistenceModel extends CorePersistenceModel {
   @UnifiedField({
     description: 'ID of the user who updated the object',
     isOptional: true,
-    mongoose: { ref: 'User', type: mongoose.Schema.Types.ObjectId },
+    mongoose: { ref: 'User', type: objectIdType() },
     roles: RoleEnum.ADMIN,
     swaggerApiOptions: { type: User },
     type: () => User,

package/src/server/modules/file/file-info.model.ts

@@ -1,5 +1,5 @@
 import { ObjectType } from '@nestjs/graphql';
-import { Schema as MongooseSchema, SchemaFactory } from '@nestjs/mongoose';
+import { Schema as MongooseSchema, SchemaFactory } from '../../../core/common/persistence/mongo/mongoose-compat.js';
 
 import { Restricted } from '../../../core/common/decorators/restricted.decorator.js';
 import { RoleEnum } from '../../../core/common/enums/role.enum.js';

package/src/server/modules/file/file.service.ts

@@ -1,5 +1,5 @@
 import { Injectable, Optional } from '@nestjs/common';
-import { InjectConnection } from '@nestjs/mongoose';
+import { InjectConnection } from '../../../core/common/persistence/mongo/mongoose-compat.js';
 import type { Connection } from 'mongoose';
 
 import { RoleEnum } from '../../../core/common/enums/role.enum.js';

package/src/server/modules/user/user.model.ts

@@ -1,7 +1,12 @@
 import { ObjectType } from '@nestjs/graphql';
-import { Schema as MongooseSchema, Prop, SchemaFactory } from '@nestjs/mongoose';
+import {
+  objectIdType,
+  Prop,
+  Schema as MongooseSchema,
+  SchemaFactory,
+} from '../../../core/common/persistence/mongo/mongoose-compat.js';
 import { IsEmail } from 'class-validator';
-import { Document, Schema } from 'mongoose';
+import type { Document } from 'mongoose';
 
 import { Restricted } from '../../../core/common/decorators/restricted.decorator.js';
 import { Translatable } from '../../../core/common/decorators/translatable.decorator.js';
@@ -48,7 +53,7 @@ export class User extends CoreUserModel implements PersistenceModel {
   @UnifiedField({
     description: 'ID of the user who created the object',
     isOptional: true,
-    mongoose: { ref: 'User', type: Schema.Types.ObjectId },
+    mongoose: { ref: 'User', type: objectIdType() },
     roles: RoleEnum.S_EVERYONE,
     type: () => String,
   })
@@ -96,13 +101,13 @@ export class User extends CoreUserModel implements PersistenceModel {
   @UnifiedField({
     description: 'ID of the user who last updated the object',
     isOptional: true,
-    mongoose: { ref: 'User', type: Schema.Types.ObjectId },
+    mongoose: { ref: 'User', type: objectIdType() },
     roles: RoleEnum.S_USER,
     type: () => String,
   })
   updatedBy: string = undefined;
 
-  @Prop({ default: {}, type: Schema.Types.Mixed })
+  @Prop({ default: {}, type: Object })
   @Restricted(RoleEnum.S_EVERYONE)
   _translations?: Record<string, Partial<User>> = undefined;
 

package/src/server/modules/user/user.module.ts

@@ -1,7 +1,7 @@
 import { forwardRef, Module } from '@nestjs/common';
-import { MongooseModule } from '@nestjs/mongoose';
 import { PubSub } from 'graphql-subscriptions';
 
+import { CorePersistenceModule } from '../../../core/common/persistence/core-persistence.module.js';
 import { ConfigService } from '../../../core/common/services/config.service.js';
 import { CoreRedisPubSub } from '../../../core/common/services/core-redis-pubsub.js';
 import { CoreRedisService } from '../../../core/common/services/core-redis.service.js';
@@ -12,15 +12,21 @@ import { User, UserSchema } from './user.model.js';
 import { UserResolver } from './user.resolver.js';
 import { UserService } from './user.service.js';
 
+/**
+ * The user model, registered database-neutrally: `@InjectModel()` keeps working, and `database` in the configuration
+ * decides whether users are stored in MongoDB or a SQL database (`CorePersistenceModule`)
+ */
+const UserPersistence = CorePersistenceModule.forFeature([{ model: User, name: User.name, schema: UserSchema }]);
+
 /**
  * User module
  */
 @Module({
   controllers: [AvatarController, UserController],
-  exports: [MongooseModule, UserResolver, UserService, 'USER_CLASS'],
+  exports: [UserPersistence, UserResolver, UserService, 'USER_CLASS'],
   // forwardRef: FileModule already imports UserModule, and the avatar upload now
   // needs FileService to reach the central storage — so the two reference each other.
-  imports: [MongooseModule.forFeature([{ name: User.name, schema: UserSchema }]), forwardRef(() => FileModule)],
+  imports: [UserPersistence, forwardRef(() => FileModule)],
   providers: [
     UserResolver,
     ConfigService,