@lenne.tech/nest-server 12.0.0 → 12.1.0

package/docs/choosing-a-database.md

@@ -0,0 +1,107 @@
+# Choosing a database
+
+Since 12.1.0 a `@lenne.tech/nest-server` project stores its data in **MongoDB** (the default), in **PostgreSQL**, in
+**MySQL 8.4 / MariaDB 11.8**, or in several of them, model by model. The framework's own modules (users, tenants, API
+tokens, AI, file metadata, locks, migrations) run on each, behind one `CrudService` and one security pipeline;
+Better-Auth runs on MongoDB and PostgreSQL. This document is the decision
+procedure — for a developer starting a project and for an AI agent asked to set one up. Configuration details are in
+`.claude/rules/configurable-features.md` (row "Data Sources"); the code rules in `.claude/rules/persistence.md`.
+
+## The procedure
+
+Work through the steps in order; the first one that decides, decides.
+
+1. **An external requirement wins.** The customer's operations team runs one database, a hosting contract names one,
+   an existing system the project must read is one: take that database. Nothing below outweighs it.
+2. **PostgreSQL** when the data is relational or reported on — accounting, invoices, bookings, inventory,
+   anything with joins, sums across records or reports a finance team reads — or when **tenant isolation must be
+   enforced by the database itself**. On PostgreSQL every tenant-scoped table carries forced row-level security, so
+   a query that forgets its tenant returns nothing instead of every tenant's rows; MongoDB has the framework's two
+   application layers only.
+3. **MongoDB** (the default) for document-shaped data — nested content, free-form attributes, structures that change
+   per customer — and whenever the signals above are absent. An existing MongoDB project stays on MongoDB: moving
+   databases is a data migration, not a configuration change.
+4. **Both (hybrid)** only with a concrete reason, written down: e.g. the finance models in PostgreSQL while the
+   content stays in MongoDB. The cost is real — two databases to run, back up and monitor, no transaction across
+   them, references across them resolved in the application. Route per model with `database.models`.
+5. **MySQL / MariaDB** only when required by step 1. What a project gives up there, and has to write into its own
+   documentation:
+   - **Tenant isolation lives in the application only.** Neither database has row-level security: the store's
+     policies keep tenants apart, and a query through `store.native()`, `store.raw()` or a connection of the project's
+     own reaches every tenant's rows unless it filters by `tenantId` itself. The boot says so once per source. A
+     trigger-based write guard was measured and not built: it cost up to half of MariaDB's write throughput and left
+     the native read open.
+   - **Better-Auth does not run there yet:** keep the user model (`users`) on PostgreSQL or MongoDB
+     (`database.models`), or sign in through the legacy endpoints only. The boot refuses the combination.
+   - **An indexed text field holds at most 255 characters** (a longer value is refused with 400); every other text is
+     unbounded. Indexing an existing text field later is a type change, i.e. a reviewed migration.
+   - **Schema changes are not transactional:** MySQL commits every DDL statement on its own, so a failed change leaves
+     the statements before it applied; the next boot completes the rest.
+6. **No database** (`database: false`) for a stateless service: a gateway, a renderer, a worker that only talks to
+   other APIs.
+
+When the signals are ambiguous, **ask** — and record the decision (database, SQL engine, date, reason) in the
+project's `CLAUDE.md`, so the next developer or agent does not re-decide it.
+
+## The SQL engine
+
+On every SQL database the framework compiles every query itself; the engine only carries the statements, so the
+choice does not change behaviour, tables or security — switching later is configuration only (`database.sqlEngine`).
+All three engines run on PostgreSQL, MySQL and MariaDB.
+
+| Engine | When |
+|---|---|
+| **TypeORM** (default) | unless the team asks for another — the widest ecosystem |
+| **Kysely** | the team writes typed SQL by hand in its own code and wants the builder it knows |
+| **Drizzle** | the team already uses Drizzle elsewhere (pinned to an exact release candidate until 1.0 GA) |
+
+Each engine is an optional peer dependency installed together with the database's driver (`pg`, or `mysql2` for MySQL
+and MariaDB). Project code that uses an engine's native API (`store.native()`) is the one part that does not move with a
+switch.
+
+## What a project installs
+
+| Database | Packages |
+|---|---|
+| MongoDB | `mongoose`, `@nestjs/mongoose`, `mongodb` (optional peers since 12.1.0 — the starter declares them) |
+| PostgreSQL | `pg` plus the engine (`typeorm`, `kysely` or `drizzle-orm`) — and **none** of MongoDB's packages (npm mode; a vendor-mode project keeps the three as `devDependencies`, because the vendored core imports their types) |
+| MySQL / MariaDB | `mysql2` plus the engine — the same rule for MongoDB's packages as on PostgreSQL |
+
+In **vendor mode** the core is the project's own source, and TypeScript resolves every package it names in an
+`import()` — whatever database the project uses. A vendor project therefore declares `pg` (with `@types/pg`), `mysql2`,
+`typeorm`, `kysely` and `drizzle-orm` (at least as `devDependencies`), or its build fails with TS2307. At runtime it loads only
+what its configuration uses.
+| Several | the sets combined |
+
+A project on PostgreSQL alone declares its models with the framework's own decorators, imported from
+`@lenne.tech/nest-server` rather than `@nestjs/mongoose` (`Schema`, `Prop`, `SchemaFactory`, `InjectModel`), and
+registers them with `CorePersistenceModule.forFeature()`. The same file works on MongoDB unchanged.
+
+## Configuration in one line each
+
+```typescript
+// MongoDB (default) — nothing to configure beyond `mongoose`
+mongoose: { uri: 'mongodb://127.0.0.1/project' }
+
+// PostgreSQL: the application role, and the owner role that migrates the schema
+database: { url: 'postgres://app@db/project', ownerUrl: 'postgres://owner@db/project', sqlEngine: 'typeorm' }
+
+// MySQL 8.4 or MariaDB 11.8: the scheme names the server (mysql:// or mariadb://)
+database: { url: 'mysql://app@db/project', ownerUrl: 'mysql://owner@db/project' }
+
+// Hybrid: PostgreSQL by default, these models in the project's MongoDB
+database: { url: 'postgres://app@db/project', ownerUrl: '…', models: { Article: 'mongoose' } },
+mongoose: { uri: 'mongodb://127.0.0.1/project' }
+
+// No database
+database: false
+```
+
+PostgreSQL always runs with **two roles**: the owner creates and migrates the schema, the application role owns
+nothing and has neither superuser nor `BYPASSRLS` — the boot refuses an application role that could bypass row-level
+security. PostgreSQL 15 or newer.
+
+MySQL and MariaDB run with **two accounts** too: the owner creates and migrates the schema and grants the application
+account `SELECT, INSERT, UPDATE, DELETE` on the database once; the boot refuses an application account that may alter,
+drop, index, trigger or grant — without row-level security, the tables and their constraints are what the store's
+policies rely on. MySQL 8.4 / MariaDB 11.8 or newer, and the URL's scheme must name the server it reaches.

package/docs/native-driver-security.md

@@ -135,6 +135,31 @@ this.getNativeConnection('');          // throws Error
 
 ---
 
+## Native access on PostgreSQL (12.1.0+)
+
+On a model routed to PostgreSQL there is no Mongoose model and no native collection: `getNativeCollection()` /
+`getNativeConnection()` refuse, and so does every Mongoose data method of the model (`routed-model.guard.ts`). The data
+store has the two native tiers instead, with the same mandatory, logged reason:
+
+| Tier | API | What still protects the data |
+|---|---|---|
+| 2 | `this.dataStore.native(reason)` — the engine's own API (TypeORM `EntityManager`, Kysely, Drizzle), bound to the store's transaction | row-level security (same connection, tenant scope set), HTTP interceptors |
+| 3 | `this.dataStore.raw(reason)` — raw SQL on that connection | row-level security, HTTP interceptors |
+
+The framework's before-layer policies (tenant stamping, audit fields, password hashing, role guard, system roles) do
+**not** run on tiers 2 and 3 — exactly as the Mongoose plugins do not run on the native MongoDB driver. Row-level
+security does: a query without a tenant scope on a tenant-scoped table fails (42501 → 403) instead of reading every
+tenant. Parameters only; a table or column name never comes from user input.
+
+**On MySQL and MariaDB there is no row-level security** — tiers 2 and 3 have nothing below them but the HTTP
+interceptors. A native or raw query on a tenant-scoped table reaches every tenant's rows unless it filters by
+`tenantId` itself, and a native write is not stamped with a tenant. The boot warns once per source; the persistence
+matrix asserts the difference (`native-api-tenant-refused`, DIFFERENT-BY-DESIGN for those columns).
+
+Rules for all of it: `.claude/rules/persistence.md` → "Native access in three tiers".
+
+---
+
 ## Review Checklist
 
 When reviewing code (manual or AI), check for `.collection.` and `.db.collection(`:
@@ -150,4 +175,8 @@ When reviewing code (manual or AI), check for `.collection.` and `.db.collection
    → Are data being written?
      YES → Verify tenantId/audit is set manually.
      NO  → Allowed (read-only).
+
+3. Is it store.native() / store.raw() on a MySQL or MariaDB source, on a tenant-scoped table?
+   → Every statement filters by tenantId (read) or sets it (write) itself — the database does not.
+     MISSING → Security violation: the query reaches every tenant. Use the store (tier 1).
 ```

package/docs/security-overrides.md

@@ -18,8 +18,16 @@ used to **exact-pin**, to a vulnerable version:
 |---------|----------|------------------------------------------|
 | `ws` | [GHSA-96hv-2xvq-fx4p](https://github.com/advisories/GHSA-96hv-2xvq-fx4p) — high: memory-exhaustion DoS + uninitialized memory disclosure. Patched `>=8.21.0` | Older `@nestjs/graphql` releases declare `"ws": "8.20.1"` — an **exact pin**, not a caret. 13.4.5 pins `8.21.3`; 14.0.3, the version this framework declares since 12.0.0, pins `8.22.0` |
 | `js-yaml` | [GHSA-pm4m-ph32-ghv5](https://github.com/advisories/GHSA-pm4m-ph32-ghv5) — high: exponential parsing time in flow collections (DoS), patched `>=5.2.2`; [GHSA-r3ph-w7gj-g6xm](https://github.com/advisories/GHSA-r3ph-w7gj-g6xm) — moderate: `maxTotalMergeKeys` does not bound CPU use for empty merge sources, covers `<=5.4.0`, patched `>=5.4.1` (published 2026-09-29) | `@nestjs/swagger` declares js-yaml as an **exact pin**, the same shape as the `ws` case: older releases `5.2.1`, 11.4.7 — the newest 11.x — `5.3.0`, which no 11.x update moves, so the entry is **load-bearing on @nestjs/swagger 11**. 12.0.3, the version this framework declares since 12.0.0, pins `5.5.0`, which clears both advisories: on @nestjs/swagger 12 the entry is inert |
-| `@graphql-tools/utils` | [GHSA-7mx3-vvmw-hjmv](https://github.com/advisories/GHSA-7mx3-vvmw-hjmv) — high: prototype pollution in `mergeDeep`, which runs while the GraphQL schema is assembled. Covers `<=12.0.0`, patched `>=12.0.1` (added 2026-10-06); [GHSA-c4qx-w738-7hr3](https://github.com/advisories/GHSA-c4qx-w738-7hr3) — high: prototype pollution in `mergeIncrementalResult` via non-primitive path segments. Covers `>=10.10.1 <=12.0.1`, patched `>=12.0.2` (published 2026-10-22) | `@nestjs/graphql` declares utils as an **exact pin**: 13.4.5 — the newest 13.x — `12.0.0`, and 14.0.3, the version this framework declares since 12.0.0, `12.0.1`. 12.0.1 clears the first advisory and is covered by the second, so **this entry is load-bearing on both majors**. `@apollo/server` reaches utils too, through `@graphql-tools/schema` / `merge` — and in a lockfile that still holds schema 10.0.x (resolved before 2026-08-12), as **utils 11.x**: vulnerable too, with no 11.x fix, and outside the override key. Lift it with `pnpm update --depth Infinity @graphql-tools/schema @graphql-tools/merge`; the current releases request utils `^12.1.0`, which needs Node >=22.15 — the framework's own floor since 11.42.10 |
-| `multer` | [GHSA-wc9g-mqfw-jrwm](https://github.com/advisories/GHSA-wc9g-mqfw-jrwm), [GHSA-535w-7cp7-47q4](https://github.com/advisories/GHSA-535w-7cp7-47q4), [GHSA-qfvm-cv95-jqjf](https://github.com/advisories/GHSA-qfvm-cv95-jqjf) — high: DoS via crafted multipart input; [GHSA-qvfw-j98x-7q72](https://github.com/advisories/GHSA-qvfw-j98x-7q72) — low: file size limit bypass. Patched `>=2.3.0`; [GHSA-q7qp-rjg7-q26m](https://github.com/advisories/GHSA-q7qp-rjg7-q26m) — high: DoS via a pending asynchronous `fileFilter` after request teardown. Covers `>=2.0.0 <2.5.0`, patched `>=2.5.0` (published 2026-10-22) | `@nestjs/platform-express` declares multer as an **exact pin**: up to 11.2.5 `2.2.0`, 11.2.6 / 11.2.7 `2.4.0`, and so does 12.2.0 — the version this framework declares since 12.0.0, and the newest 12.x. 2.4.0 is covered by GHSA-q7qp-rjg7-q26m, so **this entry is load-bearing again**. A direct `multer` dependency does not move the pin: you get both copies, and FileInterceptor uses the vulnerable one |
+| `@graphql-tools/utils` | [GHSA-7mx3-vvmw-hjmv](https://github.com/advisories/GHSA-7mx3-vvmw-hjmv) — high: prototype pollution in `mergeDeep`, which runs while the GraphQL schema is assembled. Covers `<=12.0.0`, patched `>=12.0.1` (added 2026-10-06); [GHSA-c4qx-w738-7hr3](https://github.com/advisories/GHSA-c4qx-w738-7hr3) — high: prototype pollution in `mergeIncrementalResult` via non-primitive path segments. Covers `>=10.10.1 <=12.0.1`, patched `>=12.0.2` (published 2026-10-22) | `@nestjs/graphql` declares utils as an **exact pin**: 13.4.5 — the newest 13.x — `12.0.0`, and 14.0.3, the version this framework declares since 12.0.0, `12.0.1`. 12.0.1 clears the first advisory and is covered by the second, so **this entry is load-bearing on 13.x and on 14.0.x**. 14.1.0, the version this framework declares since 12.1.0, pins `12.1.0`, which clears both: there the entry is inert. `@apollo/server` reaches utils too, through `@graphql-tools/schema` / `merge` — and in a lockfile that still holds schema 10.0.x (resolved before 2026-08-12), as **utils 11.x**: vulnerable too, with no 11.x fix, and outside the override key. Lift it with `pnpm update --depth Infinity @graphql-tools/schema @graphql-tools/merge`; the current releases request utils `^12.1.0`, which needs Node >=22.15 — the framework's own floor since 11.42.10 |
+| `multer` | [GHSA-wc9g-mqfw-jrwm](https://github.com/advisories/GHSA-wc9g-mqfw-jrwm), [GHSA-535w-7cp7-47q4](https://github.com/advisories/GHSA-535w-7cp7-47q4), [GHSA-qfvm-cv95-jqjf](https://github.com/advisories/GHSA-qfvm-cv95-jqjf) — high: DoS via crafted multipart input; [GHSA-qvfw-j98x-7q72](https://github.com/advisories/GHSA-qvfw-j98x-7q72) — low: file size limit bypass. Patched `>=2.3.0`; [GHSA-q7qp-rjg7-q26m](https://github.com/advisories/GHSA-q7qp-rjg7-q26m) — high: DoS via a pending asynchronous `fileFilter` after request teardown. Covers `>=2.0.0 <2.5.0`, patched `>=2.5.0` (published 2026-10-22) | `@nestjs/platform-express` declares multer as an **exact pin**: up to 11.2.5 `2.2.0`, 11.2.6 / 11.2.7 `2.4.0`, and so does 12.2.0, the version this framework declared in 12.0.x. 2.4.0 is covered by GHSA-q7qp-rjg7-q26m, so **this entry is load-bearing up to @nestjs/platform-express 12.2.0**. 12.3.2, the version this framework declares since 12.1.0, pins `2.5.0`: there the entry is inert. A direct `multer` dependency does not move the pin: you get both copies, and FileInterceptor uses the vulnerable one |
+
+**Status since 12.1.0** (verified 2026-10-29): with the `@nestjs/*` versions this framework declares, **no
+entry is needed**. `@nestjs/platform-express` 12.3.2 pins `multer` 2.5.0 and `@nestjs/graphql` 14.1.0 pins
+`@graphql-tools/utils` 12.1.0, both past their advisories, and nest-server's own `overrides:` block is empty:
+a fresh resolve of its tree with and without the two entries below yields the same packages and the same
+audit. Raise your project's `@nestjs/*` pins to the framework's (`pnpm run update` does it), then remove both
+entries — an inert entry is not insurance, `pnpm audit` reports a regression the day it happens. Keep them
+only while your project still pins `@nestjs/platform-express` below 12.3.2 or `@nestjs/graphql` below 14.1.0.
 
 **Status since 12.0.0** (`@nestjs/*` 12, verified 2026-10-24): `multer` is load-bearing again
 (GHSA-q7qp-rjg7-q26m covers the `2.4.0` that `@nestjs/platform-express` 12.2.0 pins) and so is
@@ -54,8 +62,9 @@ entries. None of them is optional in practice.
 ## The fix
 
 Add this to your project's `pnpm-workspace.yaml` (pnpm 11+; in pnpm 10 and earlier it lives under
-`pnpm.overrides` in `package.json`). On nest-server **12.x** these two entries are all it takes — a fresh
-resolve of nest-server 12.0.0's own tree with and without every other former entry audits identically:
+`pnpm.overrides` in `package.json`). On nest-server **12.0.x** these two entries are all it takes — a fresh
+resolve of nest-server 12.0.0's own tree with and without every other former entry audits identically. On
+**12.1.x** neither is needed once your `@nestjs/*` pins match the framework's (see "Status since 12.1.0"):
 
 ```yaml
 overrides:
@@ -63,7 +72,7 @@ overrides:
   # patched >=2.3.0), 2.4.0 in 11.2.6 / 11.2.7 / 12.2.0 — GHSA-q7qp-rjg7-q26m (high, patched >=2.5.0).
   # LOAD-BEARING again since nest-server 12.0.0: the key must reach the exact 2.4.0 pin.
   # Keep the target in LOCKSTEP with the multer version @lenne.tech/nest-server declares (2.5.0 since 12.0.0).
-  # Remove once @nestjs/platform-express pins >=2.5.0 itself.
+  # Remove once @nestjs/platform-express pins >=2.5.0 itself — 12.3.2 does (nest-server 12.1.0).
   'multer@>=2.0.0 <2.5.0': '2.5.0'
 
   # @nestjs/graphql exact-pins @graphql-tools/utils — 13.4.5: 12.0.0 (GHSA-7mx3-vvmw-hjmv, high, patched
@@ -76,7 +85,7 @@ overrides:
   # below 22.15 has no patched utils at all — raise Node.
   # Does NOT reach a utils 11.x pulled in by an older @graphql-tools/schema 10.0.x — refresh that one instead:
   #   pnpm update --depth Infinity @graphql-tools/schema @graphql-tools/merge
-  # Remove once @nestjs/graphql pins >=12.0.2 in the major you use.
+  # Remove once @nestjs/graphql pins >=12.0.2 in the major you use — 14.1.0 does (nest-server 12.1.0).
   '@graphql-tools/utils@>=12.0.0 <12.1.0': '12.1.0'
 ```
 

package/migration-guides/12.0.x-to-12.1.x.md

@@ -0,0 +1,255 @@
+# Migration Guide: 12.0.x → 12.1.x
+
+## This MINOR contains breaking changes
+
+Per `.claude/rules/versioning.md` the MAJOR digit mirrors NestJS, so a breaking change ships as a MINOR. 12.1.0 is
+one: **`mongoose`, `@nestjs/mongoose` and `mongodb` become optional peer dependencies** (§2). A MongoDB project keeps
+working once it declares them itself — which a starter-based project already does for two of the three.
+
+12.1.0 makes the framework **database-agnostic**: a project keeps its data in MongoDB (the default, unchanged), in
+**PostgreSQL**, in **MySQL 8.4 / MariaDB 11.8** (§7), or in several of them, model by model. The framework's own
+modules — users, Better-Auth, tenants, API tokens, the AI module, file metadata, locks, migrations, health check, Hub —
+run on MongoDB and PostgreSQL behind one `CrudService` and one security pipeline, and the whole e2e suite runs on both;
+on MySQL and MariaDB everything but Better-Auth runs, proven by the parity matrices. A project that stays on MongoDB changes nothing but
+its dependency list.
+
+## Overview
+
+| Category | Details |
+|---|---|
+| **Breaking Changes** | `mongoose`, `@nestjs/mongoose`, `mongodb` are optional peers — declare them (§2). `CorePersistenceModule.forFeature()` provides the model tokens itself instead of importing `MongooseModule` (§6). A `database` URL without explicit `mongoose` config no longer opens the fallback MongoDB connection (§5). `graphql-upload` 17.1.0: an import of `graphql-upload/*.js` in project code stops working (§8) |
+| **New Features** | PostgreSQL data sources with TypeORM, Kysely or Drizzle (§3); MySQL 8.4 / MariaDB 11.8 data sources on the same three engines (§7); per-model routing (`database.models`, `@PersistedModel`); the data store port (`DataStore`, `@InjectStore()`); Better-Auth on PostgreSQL; framework-owned schema evolution and SQL migrations (§4); model decorators usable without MongoDB (`Schema`, `Prop`, `SchemaFactory`, `InjectModel` from `@lenne.tech/nest-server`) (§2); `findAndCount({ samples })` on SQL |
+| **Bugfixes** | Found while making every suite pass on both databases, all fixed on MongoDB too: a legacy logout kept the device's refresh token; with legacy JWTs and `multiTenancy` the tenant guard answered every tenant route with 401; the passkey challenge cookie was looked up under the wrong name; the system-setup refusal log names the claim's real location. Also: the legacy REST rate limit counted `/auth/signin?n=1`, `?n=2`, … in separate buckets and never stopped password guessing; it is keyed on the route handler now (also in 11.43.4). The fixes for `distinct()` over ObjectId fields and for first/last names lost at an IAM sign-in ship with this release too |
+| **Migration Effort** | MongoDB project: add three dependencies and raise the `@nestjs/*` pins (§8). PostgreSQL: a new project or a data move — see §3 |
+
+## Quick Migration (a MongoDB project)
+
+```bash
+# npm mode: raise the framework and declare MongoDB's libraries yourself
+pnpm add @lenne.tech/nest-server@12.1.0 mongoose@9.11.4 @nestjs/mongoose@12.0.0 mongodb@7.7.0
+
+# raise the @nestjs/* pins to the ones this release is tested with (§8); a starter-based project: pnpm run update
+pnpm run build
+pnpm test
+```
+
+Use the versions this release's `package.json` lists under `devDependencies` — they are the ones it is tested with.
+
+**Vendor mode** (`src/core/` copied into the project): the vendored core names every SQL package in an `import()`,
+which TypeScript resolves whatever database the project uses. Declare them, at least as `devDependencies`, or the
+build fails with TS2307 — `mysql2` is new in this release:
+
+```bash
+pnpm add -D pg@8.23.1 @types/pg@8.23.1 mysql2@3.24.6 typeorm@1.1.2 kysely@0.29.7 drizzle-orm@1.0.0-rc.5
+```
+
+A starter-based project already declares `mongoose` and `@nestjs/mongoose` in `dependencies`; **move `mongodb` from
+`devDependencies` to `dependencies`**, because Better-Auth's MongoDB adapter loads it at runtime.
+
+## 1. What changes for a MongoDB project
+
+Nothing in behaviour. Every MongoDB code path is the one 12.0 ran: Mongoose models, the five Mongoose plugins, GridFS,
+the 12.0 lock documents (an old and a new replica share them in a rolling deploy), the native collections. The new
+security layer below the plugins — the **tenant row check**, which refuses a read result containing another tenant's
+row with 403 — only refuses rows the tenant filter would already have removed, so a correct path never meets it.
+
+## 2. MongoDB's libraries are optional peers
+
+`@lenne.tech/nest-server` no longer installs `mongoose`, `@nestjs/mongoose` and `mongodb`. A project that keeps data in
+MongoDB declares them (Quick Migration above); one on PostgreSQL alone installs none of them, and the framework loads,
+boots and runs without them — proven on every release by `pnpm run check:without-mongodb` against the build. A
+vendor-mode project on PostgreSQL keeps the three as `devDependencies`: the vendored core is compiled as the project's
+own source and imports their types, so `tsc` needs them, while the running server loads none of them.
+
+What a missing package looks like: a named `MongoPackagesMissingError` at boot, saying which feature needs MongoDB
+(the `mongoose` configuration, GridFS, Better-Auth on MongoDB, a MongoDB migration) and what to install. Only one of
+`mongoose` / `@nestjs/mongoose` installed is refused the same way.
+
+**Model files.** A project that wants its models to work on either database imports the decorators from the framework
+instead of `@nestjs/mongoose` — same names, same options:
+
+```typescript
+// Before (MongoDB only)
+import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
+// After (MongoDB and PostgreSQL)
+import { Prop, Schema, SchemaFactory } from '@lenne.tech/nest-server';
+```
+
+Where Mongoose is installed they apply `@nestjs/mongoose`'s decorators exactly as before; where it is not, they record
+the declaration, and the framework builds the same model description from it. Also available: `InjectModel`,
+`InjectConnection`, `getModelToken`, `getConnectionToken`, `raw`, `createSchema` (an inline schema), `objectIdType()`
+(the ObjectId field type), `newObjectId()`, `isValidObjectId()`. Free-form fields are declared `{ type: Object }`
+(Mongoose stores that as `Mixed`) rather than `Schema.Types.Mixed`.
+
+`@InjectConnection()` receives `null` where no MongoDB is configured.
+
+## 3. PostgreSQL
+
+```typescript
+// config.env.ts
+database: {
+  url: 'postgres://app_role@db/project',      // the application role: owns nothing, no BYPASSRLS
+  ownerUrl: 'postgres://owner_role@db/project', // owns the schema, migrates it at boot
+  sqlEngine: 'typeorm',                         // or 'kysely' / 'drizzle'
+},
+```
+
+```bash
+pnpm add pg typeorm   # or kysely / drizzle-orm@1.0.0-rc.5 — optional peers
+```
+
+- **Only models registered with `CorePersistenceModule.forFeature()` are routed.** The framework's own models are; a
+  project's models move by replacing `MongooseModule.forFeature([...])` with `CorePersistenceModule.forFeature([...])`
+  (same definitions). A model registered with `MongooseModule.forFeature()` stays on MongoDB.
+- **Per-model routing:** `database.models: { Article: 'mongoose' }` keeps a model in the project's MongoDB (configure
+  `mongoose` explicitly — it becomes the source `mongoose`), `@PersistedModel({ dataSource })` declares it in code.
+- **Better-Auth follows the user model.** With the user model on PostgreSQL, Better-Auth runs there too: one `users`
+  row per user, its tables in snake_case. Nothing is copied from MongoDB — moving existing users is a data migration.
+- **Tenant isolation in the database.** Every tenant-scoped table gets forced row-level security; a query without a
+  tenant scope fails (403) instead of reading every tenant. The application role must not be superuser, have
+  `BYPASSRLS`, own a framework table or be allowed to `TRUNCATE` one — the boot refuses it.
+- **PostgreSQL 15+** (unique indexes are `NULLS NOT DISTINCT`, as MongoDB treats missing values).
+- **Health check:** with `healthCheck.configs.database` every SQL source answers as `<key>:<source>`.
+- **Hub:** a Persistence panel shows each model's source; the Migrations panel reads `lt_migrations`.
+
+Choosing between the databases: `docs/choosing-a-database.md`.
+
+## 4. Schema evolution and SQL migrations
+
+The framework creates and evolves the tables from the model descriptions at boot, as the owner role: new tables,
+columns, indexes and grants are applied automatically. A change that could lose or reject data — a type change, a new
+unique index, a rename collision, a table losing tenant isolation — stops the boot with the suggested statements:
+
+```bash
+migrate create <name> --sql      # a migration that runs SQL (runSqlMigration())
+```
+
+`@UnifiedField({ renamedFrom: 'oldName' })` declares a renamed field. The migration state lives in `lt_migrations`
+(`createMigrationStore(<owner URL>)`); the Hub refuses to run migrations while that table is empty and the MongoDB
+collection still lists applied ones (a `migrate.js` still writing MongoDB).
+
+## 5. A `database` URL without `mongoose` configuration opens no MongoDB
+
+Until 12.0, `CoreModule.forRoot()` merged a fallback `mongoose.uri` (`mongodb://localhost/nest-server-default`) into
+every configuration and connected to it, whatever `database` said. Since 12.1.0 MongoDB is connected only when a source
+uses it: `mongoose` configured explicitly, or `database` naming MongoDB, or `database` absent (today's single MongoDB).
+A project that set `database` to PostgreSQL **and relied on the implicit fallback** for models registered with
+`MongooseModule.forFeature()` configures `mongoose` explicitly — those models were on a database nobody configured.
+
+## 6. `CorePersistenceModule.forFeature()` provides the model tokens itself
+
+It used to import `MongooseModule.forFeature()`. It now registers the same providers itself (the shape `@nestjs/mongoose`
+uses: `connection.model(name, schema, collection)`, discriminators included) and exports `getModelToken(name)` plus the
+store token. `@InjectModel()` keeps resolving. Without a MongoDB connection the model token is a stand-in whose data
+methods refuse with a named error — a `CrudService` runs on the routed store either way. A test module that relied on
+the re-exported `MongooseModule` imports `MongooseModule.forRoot()` itself, as before.
+
+## 7. MySQL and MariaDB
+
+```typescript
+// config.env.ts — the scheme names the server the URL reaches: mysql:// or mariadb://
+database: {
+  url: 'mysql://app_account@db/project',      // the application account: SELECT, INSERT, UPDATE, DELETE only
+  ownerUrl: 'mysql://owner_account@db/project', // creates and migrates the schema, grants the application account
+  sqlEngine: 'typeorm',                         // or 'kysely' / 'drizzle'
+},
+```
+
+```bash
+pnpm add mysql2 typeorm   # or kysely / drizzle-orm@1.0.0-rc.5 — optional peers
+```
+
+The same models, routing and store as on PostgreSQL (§3, §4). What differs, and belongs in the project's own
+documentation:
+
+- **No row-level security.** Tenant isolation is the store's (the before-layer and the row check after every read).
+  A query through `store.native()`, `store.raw()` or a connection of the project's own reaches every tenant's rows
+  unless it filters by `tenantId` itself; the boot warns once per source.
+- **Better-Auth is refused at boot** while the user model (`users`) lives on MySQL / MariaDB. Keep it on PostgreSQL or
+  MongoDB (`database.models: { User: '<source>' }`), or sign in through the legacy endpoints only.
+- **An indexed text field holds at most 255 characters** (a longer value answers 400). Indexing an existing text field
+  later is a type change — a reviewed SQL migration. A lookup index over four or more text fields indexes a prefix of
+  each; such a unique index is refused.
+- **Updates:** two operators on one path, or on a path and a path inside it, are refused — MongoDB's own rule.
+- **Unique indexes:** a missing value counts as a value, as on MongoDB; a sparse unique index (or a partial one on
+  "field exists") lets records without the value through. Any other partial unique index stops the boot — MySQL has
+  no partial indexes, and a uniqueness checked nowhere must not look like one that holds.
+- **Schema runs are not transactional:** MySQL commits every DDL statement on its own. A failed change leaves the
+  statements before it applied and names the one that failed; the next boot completes the rest. The same holds for
+  `runSqlMigration()` — write such a migration so it can run again.
+- **The application account** may only read and write rows; the boot refuses one that may alter, drop, index, trigger
+  or grant, a server older than MySQL 8.4 / MariaDB 11.8, and a scheme that names the other server.
+- Leases, migration state (`createMigrationStore(<owner URL>)`), the expiry sweep, health check and Hub work as on
+  PostgreSQL.
+
+## 8. Dependency pins, graphql-upload 17, overrides that can go
+
+**Pins.** A project pins the NestJS packages exactly, so raise the ones this release is tested with. In a
+starter-based project `pnpm run update` does it; it raises pins the project already declares and adds none.
+
+| Section | Package | Version |
+|---|---|---|
+| `dependencies` | `@nestjs/common`, `@nestjs/core`, `@nestjs/platform-express` | 12.3.2 |
+| `dependencies` | `@nestjs/graphql` | 14.1.0 |
+| `dependencies` | `@nestjs/apollo` (if the project declares it) | 14.1.1 |
+| `dependencies` | `@nestjs/swagger` | 12.0.5 |
+| `devDependencies` | `@nestjs/testing` (must match `@nestjs/common`) | 12.3.2 |
+| `devDependencies` | `@nestjs/cli` | 12.0.11 |
+| `devDependencies` | `@nestjs/schematics` | 12.0.12 |
+
+**graphql-upload 17.1.0** (from 15.0.2, as the 12.0 guide announced). graphql-upload 16+ is an ES module that
+exports only `.mjs` deep paths. A project that takes the scalar from the framework
+(`import { GraphQLUpload } from '@lenne.tech/nest-server'`, 12.0 guide §13) changes nothing. One that still
+imports `graphql-upload/GraphQLUpload.js` from a `graphql-upload` dependency of its own switches to the framework
+export now and removes that dependency: with two copies, the scalar refuses every upload as `Upload value invalid.`
+In **vendor mode** the core imports `graphql-upload/GraphQLUpload.mjs` and `graphql-upload/graphqlUploadExpress.mjs`,
+so the project's `graphql-upload` dependency must be 17.1.0, and the core's `graphql-upload.d.ts` declares only those
+two paths.
+
+**Overrides that can go.** 12.0 asked projects to mirror two security overrides (`docs/security-overrides.md`):
+`@graphql-tools/utils` and `multer`. `@nestjs/graphql` 14.1.0 and `@nestjs/platform-express` 12.3.2 pin the patched
+versions themselves, so once the pins above are raised both entries change nothing; remove them and confirm with
+`pnpm audit`. Keep them only while the project pins `@nestjs/graphql` below 14.1.0 or `@nestjs/platform-express`
+below 12.3.2. A `peerDependencyRules.allowedVersions` entry for `@types/express` under graphql-upload goes too:
+graphql-upload 17 accepts `@types/express` 4 and 5.
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---|---|
+| Services extending `CrudService` with `@InjectModel()` | Compatible — the service follows its model's store |
+| Direct `this.mainDbModel.find(…)` on a model routed to SQL | Refused with a named error; use `this.dataStore` |
+| `Model.create()` / `findByIdAndUpdate().lean()` in hot paths (MongoDB) | Compatible; the store (`this.dataStore.insert()` / `updateById()`) is the neutral fast path |
+| `getNativeCollection(reason)` / `getNativeConnection(reason)` | MongoDB only; on SQL `store.native(reason)` / `store.raw(reason)` (RLS still binds) |
+| Custom Mongoose plugins on the connection | MongoDB only; their logic does not run on a SQL store |
+| GridFS (`file.storage: 'gridfs'`) | MongoDB only; on a SQL default source the derived driver is `filesystem` (or `s3`) |
+| `@nestjs/mongoose` decorators in project models | Compatible on MongoDB; switch to the framework's exports for PostgreSQL |
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `MongoPackagesMissingError: … needs MongoDB, and its libraries are not installed` | A MongoDB feature is configured, the peers are missing | Install `mongoose`, `@nestjs/mongoose`, `mongodb` (Quick Migration) |
+| `SchemaMigrationRequiredError` at boot | A schema change needs review | Write the suggested statements into `migrate create <name> --sql`, run it |
+| Boot refuses the application role | Superuser, `BYPASSRLS`, owner of a framework table, or `TRUNCATE` right | Use a role that owns nothing; the owner goes into `ownerUrl` |
+| `X.find() reaches MongoDB, but X is stored on postgres` | Code calls the Mongoose model of a model routed to SQL | Use `this.dataStore` / `@InjectStore()` |
+| 403 on a tenant read on PostgreSQL | No tenant scope for a tenant-scoped table (RLS) | Run inside a request with a tenant, or as system work (`RequestContext.runWithBypassTenantGuard()`) |
+| `Better-Auth cannot run on MySQL yet` at boot | The user model is routed to a MySQL / MariaDB source | Route `User` to PostgreSQL or MongoDB, or switch Better-Auth off |
+| `The application account … holds ALTER, …` at boot | `database.url` connects as an account with schema rights | Connect as a DML-only account; the owner goes into `ownerUrl` |
+| `Updating the path "…" would create a conflict` on MySQL | Two update operators on one path | One operator per path, as on MongoDB |
+| 400 `a value is longer than its column allows` on MySQL | A text field in an index got more than 255 characters | Shorten the value, or leave the field out of the index |
+| `ERR_PACKAGE_PATH_NOT_EXPORTED: … './GraphQLUpload.js'` (or TS2307 on that path) | Project code imports `graphql-upload/*.js` and reached the framework's graphql-upload, now 17 | `import { GraphQLUpload } from '@lenne.tech/nest-server'` (§8) |
+
+## Module Documentation
+
+- `docs/choosing-a-database.md` — which database, which engine
+- `.claude/rules/persistence.md` — code rules (store, native tiers, optional MongoDB, hot paths)
+- `.claude/rules/configurable-features.md` — row "Data Sources" (every option)
+- `.claude/rules/better-auth.md` §11 — Better-Auth on a SQL source
+- `src/core/modules/migrate/README.md` — SQL migrations and the state store
+- `src/core/modules/system-setup/README.md` — the setup claim on PostgreSQL
+
+## References
+
+- Plan and decisions: `.claude/plans/db-agnostic/PLAN.md` (framework repository)
+- Reference project: [nest-server-starter](https://github.com/lenneTech/nest-server-starter)