@lenne.tech/nest-server 12.1.0 → 12.2.0

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

@@ -0,0 +1,154 @@
+# Migration Guide: 12.1.x → 12.2.x
+
+## No breaking change
+
+12.2.0 adds **offline sync**: mobile apps (React Native, Capacitor) with SQLite, web apps and PWAs with IndexedDB, and
+desktop or Node clients read and write while disconnected and reconcile with the server afterwards. It is opt-in in
+two places — the `sync` configuration and a declaration per model — and **without both nothing changes**: no field,
+index, route or code path is added, and a project's test suite stays as it is (protocol §13). It is a MINOR because of
+its size, not because anything existing moves.
+
+## Overview
+
+| Category | Details |
+|---|---|
+| **Breaking Changes** | None |
+| **New Features** | Synchronized models: `version`, tombstones, live-only unique indexes, a change order on every database (§2). The sync module: `GET/POST /sync/{model}` with cursor pull, idempotent push, conflict strategies, client ids, resync (§3). Change hints over SSE and GraphQL, tombstone purge, the `syncUpdate` migration helper (§4). `ServiceOptions.expectedVersion` for conditional changes of a synchronized model (§2) |
+| **Bugfixes** | None that change existing behaviour |
+| **Migration Effort** | None for an update. Offering a model to offline clients: about an hour per model, plus the client (§5) |
+
+## Quick Migration
+
+```bash
+pnpm add @lenne.tech/nest-server@12.2.0
+pnpm run build
+pnpm test
+```
+
+No dependency of a project changes. **Vendor mode**: run `/lt-dev:backend:update-nest-server-core` as usual; the new
+module is `src/core/modules/sync/`.
+
+## 1. What changes for an existing project
+
+Nothing, unless it switches offline sync on. The framework's own models are not synchronized, the `CrudService` keeps
+its behaviour for every model that does not declare `sync`, and no route is registered without the `sync`
+configuration.
+
+## 2. Synchronized models
+
+A model takes part in offline sync when it is declared with `sync` and registered with
+`CorePersistenceModule.forFeature()`:
+
+```typescript
+@PersistedModel({
+  sync: {
+    roles: { create: [RoleEnum.S_USER], delete: [RoleEnum.S_CREATOR], pull: [RoleEnum.S_USER], update: [RoleEnum.S_CREATOR] },
+    strategy: 'merge',
+  },
+})
+@Schema({ timestamps: true })
+@ObjectType()
+export class Note extends CorePersistenceModel { … }
+```
+
+The store then keeps three system fields on every write path — `version`, `deletedAt` and the change position
+(`syncSeq` on SQL, `syncAt` on MongoDB) — never settable through an input:
+
+- **Deletes leave tombstones**: `CrudService.delete()` and every port delete keep the record as a tombstone without
+  content, so clients learn of the deletion. Reads leave tombstones out.
+- **Unique indexes apply to live records only**, so delete-then-recreate with the same value works.
+- **Conditional changes**: `ServiceOptions.expectedVersion` on `update()` / `delete()` is one statement with the
+  version as its condition; another version answers `409` (`VersionConflictError`). Only a synchronized model has a
+  `version`: on any other model `expectedVersion` throws `UnsupportedCapabilityError`.
+
+**Making an EXISTING model synchronized is a migration** on every database — the boot refuses with the statements to
+run (SQL: the new column and live-only indexes; MongoDB: `SyncMigrationRequiredError`, dropping the old unique indexes
+and stamping every document). Details: `.claude/rules/persistence.md` → "Synchronized models".
+
+## 3. The sync module
+
+```typescript
+// config.env.ts
+sync: {
+  cursorSecret: process.env.SYNC_CURSOR_SECRET, // else SECRETS_ENCRYPTION_KEY; required in production/staging
+},
+```
+
+```typescript
+@SyncService({ createInput: NoteCreateInput, model: Note, updateInput: NoteInput })
+@Injectable()
+export class NoteService extends CrudService<Note, NoteCreateInput, NoteInput> { … }
+```
+
+- `GET /sync/{model}`: one page of changes after an opaque, signed cursor; `410` with a reason when the client must
+  resync (`invalid`, `horizon`, `access`).
+- `POST /sync/{model}`: items processed in order, each atomic; idempotent through mutation ids; client-generated ids
+  (ObjectId-hex with a random tail, or uuidv7 for new models); strategies `reject`, `lww`, `merge` (`@SyncField()` for
+  fields), `custom` (`resolveSyncConflict()` on the service).
+- Every pull and push runs through the model's `CrudService` with the roles from `sync.roles` — the roles of the
+  project's own routes do not apply here, and an operation without roles is ADMIN only.
+- Without `X-Tenant-Id` a request spans every tenant the caller belongs to.
+
+The protocol for client authors: `docs/offline-sync-protocol.md`. The module: `src/core/modules/sync/README.md`.
+
+## 4. Hints, purge, data migrations
+
+- **Hints**: `GET /sync/hints` (Server-Sent Events, event `change`) and the GraphQL subscription `syncHint(models)` tell
+  a client "pull now" — `{ model, at }` only, to callers with the pull roles and access to the tenant. With `redis`
+  every replica's subscribers receive them. `sync.hints: false` switches them off.
+- **Purge**: tombstones older than `sync.retention.tombstonesDays` (90) are deleted every hour on one replica, after
+  the retention horizon moved past them; a client behind it resyncs.
+- **Data migrations** of a synchronized SQL table: `runSqlMigration(ownerUrl, [{ syncUpdate: { table, set, where } }])`
+  raises `version` and numbers the rows like a store write. A bare `UPDATE` would let a stale client overwrite the
+  migrated value without a conflict.
+- **Writes past the CrudService** (data store, native API) call `CoreSyncService.notifyChange()` for hints and
+  `bumpAccessEpoch()` when a record changes tenant or owner.
+
+## 5. Offering a model to offline clients — checklist
+
+Follow `src/core/modules/sync/INTEGRATION-CHECKLIST.md`. In short:
+
+1. Declare `@PersistedModel({ sync: { roles, strategy } })` and register the model with `CorePersistenceModule.forFeature()`.
+2. Put `@SyncService({ model, createInput, updateInput })` on its `CrudService`.
+3. Add `sync: {}` (with a `cursorSecret` for deployed stages) to the configuration.
+4. Give the client its duties: delete every local record, cursor and unsent change on logout and on an account switch
+   (`src/core/modules/sync/SECURITY.md`).
+
+The reference model is `src/server/modules/sync-note/`; the framework's own test clients (a PWA on IndexedDB and a Node
+client on SQLite, `tests/clients/` in the framework repository) show a complete client in a few hundred lines.
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---|---|
+| Project without `sync` configuration | Unchanged |
+| Model without `sync` in a project with `sync` | Unchanged; not reachable under `/sync` |
+| `CrudService.delete()` on a synchronized model | Leaves a tombstone; a hard delete is the purge's alone |
+| Project controller extending `CoreSyncController` | Fine — the hint route is `CoreSyncHintsController`'s, registered first, so re-declaring `pull()` cannot shadow it |
+| TTL index on a synchronized model | Refused at registration — an expired record would vanish without a tombstone |
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Boot fails: `cursorSecret` missing | Production / staging without `sync.cursorSecret` or `SECRETS_ENCRYPTION_KEY` | Set one of them |
+| Boot fails with SQL statements or `SyncMigrationRequiredError` | An existing model was declared `sync` | Run the printed migration (§2) |
+| Warning "declares no sync roles" | `sync.roles` missing an operation | Declare roles per operation; otherwise ADMIN only |
+| `400` on a push | `Content-Type` is not `application/json` | Send JSON |
+| `403` on a cookie push | `Sec-Fetch-Site: cross-site` or an untrusted `Origin` | Push from a trusted origin (`appUrl`, `baseUrl`, `cors.allowedOrigins`) |
+| Every cursor answers `410 invalid` | `cursorSecret` changed | Expected: clients resync once |
+| Boot fails on MySQL / MariaDB with error 1419 (`You do not have the SUPER privilege and binary logging is enabled`) once a model is declared `sync` | The change-order triggers are created by the owner account (`database.ownerUrl`); with binary logging on (the MySQL 8.4 default) that needs `SUPER` or `log_bin_trust_function_creators=1` | Set `log_bin_trust_function_creators=1` on the server (the parameter group on managed MySQL), or grant the owner `SUPER`. The application account needs neither |
+| A client keeps records after its user left a tenant | The client treats only `410 access` as access loss | A pull answering `403` (pull roles withdrawn, or `X-Tenant-Id` naming a left tenant) is access loss too: drop that model's local records and cursor (`SECURITY.md`) |
+| Hints only on one replica | No `redis` configured | Configure `redis`; hints are never a correctness signal |
+
+## Module Documentation
+
+- `src/core/modules/sync/README.md` — module overview, configuration, security model, hints, purge
+- `src/core/modules/sync/INTEGRATION-CHECKLIST.md` — integration steps
+- `src/core/modules/sync/SECURITY.md` — what the server enforces, what a client must do
+- `docs/offline-sync-protocol.md` — the client contract
+- `src/server/modules/sync-note/` — reference model
+
+## References
+
+- nest-server-starter: unaffected (it declares no synchronized model)

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "12.1.0",
+  "version": "12.2.0",
   "type": "module",
-  "description": "Server framework in TypeScript on top of NestJS: GraphQL and REST APIs on MongoDB, PostgreSQL, MySQL or MariaDB, with authentication, field-level permissions, multi-tenancy and an AI assistant.",
+  "description": "Server framework in TypeScript on top of NestJS: GraphQL and REST APIs on MongoDB, PostgreSQL, MySQL or MariaDB, with authentication, field-level permissions, multi-tenancy, offline sync and an AI assistant.",
   "keywords": [
     "node",
     "nest",
@@ -15,6 +15,7 @@
     "graphql",
     "rest",
     "multi-tenancy",
+    "offline-sync",
     "typescript"
   ],
   "author": "lenne.Tech <info@lenne.tech> (https://lenne.tech)",
@@ -136,7 +137,7 @@
     "lodash": "4.18.1",
     "multer": "2.5.0",
     "node-mailjet": "6.0.11",
-    "nodemailer": "10.2.1",
+    "nodemailer": "10.3.0",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
@@ -225,9 +226,9 @@
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "3.1158.0",
-    "@aws-sdk/lib-storage": "3.1158.0",
-    "@aws-sdk/s3-request-presigner": "3.1158.0",
+    "@aws-sdk/client-s3": "3.1159.0",
+    "@aws-sdk/lib-storage": "3.1159.0",
+    "@aws-sdk/s3-request-presigner": "3.1159.0",
     "@better-auth/core": "1.7.14",
     "@better-auth/passkey": "1.7.14",
     "@compodoc/compodoc": "2.0.0",
@@ -244,12 +245,12 @@
     "@types/express": "5.0.6",
     "@types/lodash": "4.17.27",
     "@types/multer": "2.3.0",
-    "@types/node": "26.6.5",
+    "@types/node": "26.6.6",
     "@types/passport": "1.0.17",
     "@types/pg": "8.23.1",
     "@vitest/coverage-v8": "5.0.5",
     "better-auth": "1.7.14",
-    "bullmq": "6.5.0",
+    "bullmq": "6.5.1",
     "cross-env": "10.1.0",
     "drizzle-orm": "1.0.0-rc.5",
     "ioredis": "6.0.0",
@@ -263,6 +264,7 @@
     "oxlint": "1.90.0",
     "oxlint-tsgolint": "7.0.2005",
     "pg": "8.23.1",
+    "playwright-core": "1.64.1",
     "rimraf": "6.1.3",
     "smtp-server": "3.21.1",
     "tsx": "4.23.15",

package/src/core/common/helpers/file.helper.ts

@@ -281,15 +281,17 @@ export function multerFileToUpload(file: {
 
 /**
  * Get function to generate a random file name for multer with a certain
- * number of digits
+ * number of hexadecimal digits
+ *
+ * The digits come from `randomBytes()`: where the upload directory is served,
+ * a name from `Math.random()` could be predicted (DEV-3897).
  */
 export function multerRandomFileName(numberOfDigits = 32) {
   return (req, file, cb) => {
     // Generating a random string
-    const randomName = Array(numberOfDigits)
-      .fill(null)
-      .map(() => Math.round(Math.random() * 16).toString(16))
-      .join('');
+    const randomName = randomBytes(Math.ceil(numberOfDigits / 2))
+      .toString('hex')
+      .slice(0, numberOfDigits);
 
     // Calling the callback passing the random name generated with the
     // original extension name

package/src/core/common/helpers/graphql-ws-connection.helper.ts

@@ -355,8 +355,9 @@ function markStale(connection: WsConnection): void {
 
 /**
  * Re-check, at once, every open connection of a user — after a membership, role or credential change.
- * Answers the number of connections affected. Process-local: the tenant guard's Redis broadcast is
- * what carries a membership invalidation to the other replicas.
+ * Answers the number of connections affected. Process-local: the Redis broadcasts of the tenant guard
+ * (memberships) and of the Better-Auth user mapper (roles, verification) carry an invalidation to the
+ * other replicas.
  */
 export function revalidateWsConnectionsOf(identity: IWsConnectionIdentity): number {
   const userId = identity?.userId !== undefined && identity?.userId !== null ? String(identity.userId) : undefined;

package/src/core/common/interfaces/cron-job-config.interface.ts

@@ -27,7 +27,8 @@ export interface CronJobConfig<OC extends CronOnCompleteCommand | null = null, C
    * Whether the job is deduplicated across replicas in multi-replica deployments.
    *
    * When enabled, only ONE replica executes each tick: via BullMQ job schedulers when
-   * Redis is configured, otherwise via a MongoDB lease per tick. The lease is BEST EFFORT —
+   * Redis is configured, otherwise via a lease per tick (Redis, the SQL default source, or
+   * MongoDB), keyed on the tick's SCHEDULED instant. The lease is BEST EFFORT —
    * an unreachable lease store runs the tick everywhere rather than stopping all scheduled
    * work, because a silent fleet-wide outage of every cron job is the worse failure.
    *
@@ -52,8 +53,12 @@ export interface CronJobConfig<OC extends CronOnCompleteCommand | null = null, C
 
   /**
    * Depending on how long the execution of a job takes, it may happen that several executions take place at the
-   * same time. This can be prevented with `runParallel = false`.This option is set to `true` by default.
+   * same time. This can be prevented with `runParallel = false`. This option is set to `true` by default.
    * If a number is specified, it is used as the number of maximum parallel executions.
+   *
+   * For a `distributed` job, `false` (or `1`) holds across replicas too: the run holds a lease, renewed while it
+   * runs and released at its end, so another replica skips its tick instead of starting the job in parallel
+   * (12.1.1+). A larger number limits each process on its own.
    */
   runParallel?: boolean | number;
 

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

@@ -3509,6 +3509,16 @@ export interface IServerOptions {
     path?: string;
   };
 
+  /**
+   * Offline sync (`docs/offline-sync-protocol.md`): `GET/POST /sync/{model}` for the models whose service carries
+   * `@SyncService()` and whose model is declared with `@PersistedModel({ sync })`. Presence implies enabled — `true`
+   * or `{}` enables it with the defaults, `{ enabled: false }` pre-configures without enabling. Absent: no route, no
+   * store, no code path.
+   *
+   * @since 12.2.0
+   */
+  sync?: boolean | ISync;
+
   /**
    * System setup configuration for initial admin creation.
    *
@@ -3831,6 +3841,125 @@ export interface IS3Config {
   stagingBucket?: string;
 }
 
+/**
+ * Offline sync (`sync`, presence implies enabled). See `src/core/modules/sync/README.md`.
+ *
+ * @since 12.2.0
+ */
+export interface ISync {
+  /**
+   * Secret the pull cursors are signed with (HMAC; the key is derived from it). Falls back to the
+   * `SECRETS_ENCRYPTION_KEY` environment variable. REQUIRED in `production` / `staging` — the boot fails without it;
+   * elsewhere an insecure development default is used with a warning. Changing it answers every client's next pull
+   * with a full resync (`410 invalid`).
+   */
+  cursorSecret?: string;
+
+  /**
+   * Pre-configure without enabling.
+   * @default true (when the object is present)
+   */
+  enabled?: boolean;
+
+  /**
+   * Hints that a synchronized model changed (protocol §9): SSE `GET /sync/hints` and the GraphQL subscription
+   * `syncHint`, carrying `{ model, at }` only, to callers with the model's pull roles and — on a tenant-scoped model —
+   * for changes in their own tenants. A hint only means "pull now": a client works without them. `false` switches both
+   * channels off; with `redis` a hint reaches the subscribers of every replica.
+   * @default on (both channels)
+   */
+  hints?:
+    | boolean
+    | {
+        /**
+         * At most one hint per model and tenant within this many milliseconds — a burst of writes is one hint.
+         * @default 250
+         */
+        debounceMs?: number;
+        /** @default true (when the object is present) */
+        enabled?: boolean;
+        /**
+         * The GraphQL subscription `syncHint` (only where GraphQL is enabled).
+         * @default true
+         */
+        graphql?: boolean;
+        /**
+         * The SSE stream `GET /sync/hints`.
+         * @default true
+         */
+        sse?: boolean;
+      };
+
+  /**
+   * Route prefix of the sync endpoints.
+   * @default 'sync'
+   */
+  path?: string;
+
+  pull?: {
+    /**
+     * Records per page when the client sends no `limit`.
+     * @default 200
+     */
+    defaultLimit?: number;
+    /**
+     * Upper bound of the serialized size of one page; a page ends before it would exceed it (it always holds at least
+     * one item when one is pending).
+     * @default 1048576 (1 MiB)
+     */
+    maxBytes?: number;
+    /**
+     * Highest `limit` a client may ask for (at most 1000).
+     * @default 1000
+     */
+    maxLimit?: number;
+    /**
+     * MongoDB only: the window W a pull run re-reads below its previous start (plan §3.4). Changes stamped within W
+     * before a run started may be repeated; a write that takes longer than W from its stamp until it is visible would
+     * be missed, so W must cover the longest such write.
+     * @default replica set / sharded: the server's `transactionLifetimeLimitSeconds` (60 when unreadable) + 30;
+     *   standalone: 30
+     */
+    windowSeconds?: number;
+  };
+
+  push?: {
+    /**
+     * Items per push request; more answer 400.
+     * @default 100
+     */
+    maxItems?: number;
+  };
+
+  /**
+   * Per-user rate limits of pull and push (fixed window; exact across replicas when `redis` is configured). `false`
+   * switches both off, `{ pull: false }` one of them.
+   * @default pull 120 / 60 s, push 60 / 60 s
+   */
+  rateLimit?:
+    | false
+    | {
+        pull?: false | { max?: number; windowSeconds?: number };
+        push?: false | { max?: number; windowSeconds?: number };
+      };
+
+  retention?: {
+    /**
+     * How long the outcome of a pushed mutation is kept, so a repeat is answered with it (protocol §6.5).
+     * @default 30
+     */
+    mutationsDays?: number;
+    /**
+     * How long a tombstone is kept. Every hour (on one replica, under a lease) the purge first moves the model's
+     * horizon to this age, then deletes the older tombstones for good; a client whose cursor is older than the horizon
+     * answers its next pull with a full resync (`410 horizon`). `false` keeps tombstones for ever; an invalid value
+     * (zero, negative, not a number) falls back to the default — never to "purge everything".
+     * @default 90
+     */
+    tombstonesDays?: false | number;
+  };
+}
+
 export interface ISystemSetup {
   /**
    * Whether system setup is enabled.
@@ -4831,6 +4960,26 @@ export interface ICoreModuleOverrides {
     service?: Type<any>;
   };
 
+  /**
+   * Override the offline sync endpoints, the hint subscription and their service (`sync` config).
+   *
+   * - `controller` must extend `CoreSyncController` (e.g. to release a sync scope to API tokens)
+   * - `hintsController` must extend `CoreSyncHintsController` (`GET /sync/hints`, e.g. for API tokens there too)
+   * - `resolver` must extend `CoreSyncResolver` (the `syncHint` subscription)
+   * - `service` must extend `CoreSyncService`
+   *
+   * @example
+   * ```typescript
+   * { sync: { controller: SyncController } }
+   * ```
+   */
+  sync?: {
+    controller?: Type<any>;
+    hintsController?: Type<any>;
+    resolver?: Type<any>;
+    service?: Type<any>;
+  };
+
   /**
    * Override AI module collaborators with project-specific subclasses.
    *

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

@@ -32,6 +32,11 @@ export interface ServiceOptions {
   // If truly: create mode is activated
   create?: boolean;
 
+  // The id `create()` gives the new record: on a synchronized model the id a client chose offline, in the model's
+  // format (refused otherwise), on any other model a 24-character hex id. Passed beside the input because an input
+  // class keeps only the fields it declares: an `id` inside the input is lost the moment `inputType` maps it
+  createId?: string;
+
   // Current user to set ownership, check rights and other things
   currentUser?: {
     [key: string]: any;
@@ -42,9 +47,19 @@ export interface ServiceOptions {
   // Field selection for results (will be overwritten by populate if populate was set)
   fieldSelection?: FieldSelection;
 
+  // Conditional change of a synchronized model (`@PersistedModel({ sync })`): `update()` and `delete()` apply only
+  // when the stored record still has this version, in one atomic statement, and throw a 409 (`VersionConflictError`)
+  // otherwise. Refused on a model that is not synchronized
+  expectedVersion?: number;
+
   // Determines whether all restrictions are ignored
   force?: boolean;
 
+  // Read a synchronized model's tombstones too — its deleted records, which every other read leaves out (get, find,
+  // findOne, findAndCount, distinct). Reads only: update() and delete() never touch a tombstone and answer 404 for one.
+  // Applies to the main model only: a populated reference to a tombstone stays empty
+  includeTombstones?: boolean;
+
   // Overwrites type of input (array items)
   inputType?: new (...params: any[]) => any;
 

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

@@ -4,8 +4,15 @@ import { getConnectionToken, getModelToken } from './mongo/mongoose-compat.js';
 import type { Model } from 'mongoose';
 
 import { registerModelSchema } from './model-metadata.registry.js';
+import { isDeclaredSchema } from './mongo/model-declarations.js';
+import { applySyncSchema, assertSyncCollectionReady } from './mongo/sync-schema.plugin.js';
 import { MongooseDataStore } from './mongoose-data-store.js';
-import { getPersistedModelOptions, getPersistedModelOptionsByName } from './persisted-model.decorator.js';
+import {
+  getPersistedModelOptions,
+  getPersistedModelOptionsByName,
+  getPersistedSyncByName,
+} from './persisted-model.decorator.js';
+import { resolveSyncOptions } from './sync-model.js';
 import {
   bindStoreToModel,
   getPersistenceRuntime,
@@ -46,7 +53,15 @@ export interface PersistenceModelDefinition extends ModelDefinition {
 export class CorePersistenceModule {
   static forFeature(models: PersistenceModelDefinition[]): DynamicModule {
     for (const model of models) {
-      registerModelSchema(model.name, model.schema);
+      const sync = resolveSyncOptions(
+        model.model ? getPersistedModelOptions(model.model)?.sync : getPersistedSyncByName(model.name),
+        model.name,
+      );
+      // Described as declared first, then prepared: the descriptor must not see the Mongoose sync paths
+      registerModelSchema(model.name, model.schema, sync);
+      if (sync && !isDeclaredSchema(model.schema)) {
+        applySyncSchema(model.schema, sync);
+      }
       registerPersistedModel({
         declaredSource:
           model.dataSource ??
@@ -88,6 +103,10 @@ export class CorePersistenceModule {
             ? // 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);
+        // A synchronized model on MongoDB: the collection must hold nothing from before it was synchronized
+        if (store.capabilities.mongoosePopulate && store.capabilities.changeOrder) {
+          await assertSyncCollectionReady(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

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

@@ -13,6 +13,7 @@ import {
 } from './data-source.config.js';
 import type { ModelDescriptor } from './model-descriptor.interface.js';
 import { getModelDescriptor } from './model-metadata.registry.js';
+import { withSequenceField } from './sync-model.js';
 import { MongooseDataStore } from './mongoose-data-store.js';
 import {
   getPersistedModels,
@@ -20,8 +21,6 @@ import {
   type PersistenceOverview,
   type PersistenceRuntime,
 } from './persistence-runtime.registry.js';
-import { grantStatement } from './sql/postgres/postgres-schema.compiler.js';
-import { assertSafeApplicationRole, SCHEMA_LOCK_SQL } from './sql/postgres/postgres-schema.migrator.js';
 import { type SqlDialect, sqlDialect } from './sql/sql-dialect.js';
 import { createSqlExecutor } from './sql/sql-executor.factory.js';
 import type { SqlExecutor } from './sql/sql-executor.interface.js';
@@ -120,19 +119,16 @@ export class DataSourceRuntime implements PersistenceRuntime {
     if (!registration || !source || source.driver === 'mongodb') {
       return undefined;
     }
-    if (source.driver !== 'postgres') {
-      throw new Error(
-        `Better-Auth cannot run on ${this.dialect(source).label} yet: the user model (table ${USERS_TABLE}) is routed to ` +
-          `the source "${source.name}". Keep the user model on PostgreSQL or MongoDB (database.models), or switch Better-Auth off.`,
-      );
-    }
     // Opening the store brings `users` up to date first: Better-Auth only adds its columns to the table the user model
-    // defines, never the other way round
+    // defines, never the other way round — and on MySQL / MariaDB that run also grants the application account its
+    // rights on the database, which then cover Better-Auth's tables
     const users = await this.resolveStore(registration.name, undefined);
     const app = await this.executor(source);
     return {
       applySchema: (migrate, tables) => this.applyForeignSchema(source, app, migrate, tables),
-      pool: app.driverPool,
+      driver: source.driver as IamSqlStorage['driver'],
+      pool: this.dialect(source).foreignPool(app),
+      query: queryOn(app),
       source: source.name,
       users,
     };
@@ -195,10 +191,12 @@ export class DataSourceRuntime implements PersistenceRuntime {
   }
 
   private async openStore(source: ResolvedDataSource, name: string): Promise<DataStore<any>> {
-    const model = getModelDescriptor(name);
-    if (!model) {
+    const declared = getModelDescriptor(name);
+    if (!declared) {
       throw new Error(`No descriptor for model "${name}" — register it with CorePersistenceModule.forFeature()`);
     }
+    // A synchronized model's table also carries its commit-ordered change position (offline-sync plan §3.4)
+    const model = withSequenceField(declared);
     const app = await this.executor(source);
     const dialect = this.dialect(source);
     let changes: SchemaChange[];
@@ -270,11 +268,12 @@ export class DataSourceRuntime implements PersistenceRuntime {
   private async applyForeignSchema(
     source: ResolvedDataSource,
     app: SqlExecutor,
-    migrate: (pool: unknown, asOwner: boolean) => Promise<void>,
+    migrate: Parameters<IamSqlStorage['applySchema']>[0],
     tables: string[],
   ): Promise<void> {
+    const dialect = this.dialect(source);
     if (!source.ownerUrl) {
-      await migrate(app.driverPool, false);
+      await migrate(dialect.foreignPool(app), false, queryOn(app));
     } else {
       const connect = (maxConnections: number) =>
         createSqlExecutor({
@@ -284,20 +283,15 @@ export class DataSourceRuntime implements PersistenceRuntime {
           url: source.ownerUrl,
         });
       const [lock, migrator] = await Promise.all([connect(1), connect(2)]);
-      const appRole = decodeURIComponent(new URL(source.url).username);
       try {
-        await lock.transaction(async (tx) => {
-          await tx.run({ params: [], text: SCHEMA_LOCK_SQL }, SYSTEM);
-          await migrate(migrator.driverPool, true);
-          for (const table of tables) {
-            await tx.run({ params: [], text: grantStatement(table, appRole) }, SYSTEM);
-          }
-        });
+        await dialect.withForeignSchemaLock(lock, tables, () =>
+          migrate(dialect.foreignPool(migrator), true, queryOn(migrator)),
+        );
       } finally {
         await Promise.all([lock.close(), migrator.close()]);
       }
     }
-    await assertSafeApplicationRole(app, tables);
+    await dialect.assertSafeApplication(app, tables);
   }
 
   private dialect(source: ResolvedDataSource): SqlDialect {
@@ -346,6 +340,11 @@ const USERS_TABLE = 'users';
 
 const SYSTEM = { kind: 'system' } as const;
 
+/** One statement on an executor as system work, `$1`-numbered parameters, its rows back */
+function queryOn(executor: SqlExecutor): IamSqlStorage['query'] {
+  return async (text, params = []) => ({ rows: (await executor.run({ params, text }, SYSTEM)).rows });
+}
+
 async function closeExecutor(pending: Promise<SqlExecutor>): Promise<void> {
   await (await pending.catch(() => undefined))?.close();
 }