@zerotal/orm 1.15.0 → 1.15.2

package/CHANGELOG.md

@@ -8,6 +8,88 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.15.2] — 2026-10-23
+
+### Fixed
+
+- **The ORM runs on Bun 1.4.4.** Every statement it assembled from a runtime string — the
+  string form of `DB.raw()`, the query builder, schema and migration DDL, the `SAVEPOINT`
+  a nested transaction issues, the validator's `unique` and `exists` rules — reached Bun's
+  `sql` function as a template object built with `Object.assign(parts, { raw: parts })`,
+  whose `raw` is enumerable. Bun 1.4.4 refuses that ("has an enumerable 'raw' property, so
+  it is not a template object"), so on that version and later none of those statements ran:
+  the package's own suite failed 288 tests and then hung. Earlier Bun accepted it, which is
+  why nothing noticed until the CI job that runs on the latest Bun did.
+
+  All of them now take the object from one helper, `_templateStrings()`, which defines
+  `raw` the way a real template object has it and freezes the result. `@zerotal/notifications`
+  and `@zerotal/testing` had built the same object by hand and use it too. One test runs the
+  ORM's paths through a connection that rejects an enumerable `raw`; another fails if any
+  package's source builds one again.
+
+## [1.15.1] — 2026-09-13
+
+### Fixed
+
+- **A model with a primary key other than `id` could not be updated, deleted or
+  reloaded.** `static primaryKey = "uuid"` (and the `@(table("…").primaryKey("…"))` chain)
+  configured the column name everywhere the key was written into SQL, but the value bound
+  against it came from `this.id` — a property such a model never has. Every statement
+  therefore went out as `WHERE uuid = NULL`: `save()` on a loaded instance and `delete()`
+  each matched zero rows and returned as though they had written, `refresh()` and `fresh()`
+  threw `ModelNotFoundError` for a row that was sitting in the table, and `increment()`,
+  `decrement()`, `loadCount()` and the relation aggregate loads no-opped or reported zero.
+
+  The insert was worse than a silent no-op. It wrote the row correctly, then read it back
+  by `last_insert_rowid()` / `LAST_INSERT_ID()`, which answer with a rowid that no `TEXT`
+  key ever equals — so the re-read matched nothing and the instance came back with no
+  timestamps, no database defaults, and still marked as not yet resident. The next `save()`
+  on it was a second INSERT and a duplicate-key error rather than the UPDATE the caller
+  asked for.
+
+  Every one of those paths now reads the key by its declared name, preferring the loaded
+  value so reassigning a key updates the row it was read from. An insert whose key the app
+  minted skips the generated-id round-trip and reads the row back by the key it just wrote.
+  `replicate()` drops the declared key instead of only `id`, so the copy is insertable.
+  A write against an instance whose key is genuinely absent — a row hydrated by
+  `select("title")`, say — now throws `E_NO_PRIMARY_KEY` instead of binding NULL and
+  looking like a success.
+
+- **A primary key the app mints was stripped from the INSERT.** `id` was treated as
+  database-generated unconditionally, so a table whose key is a `TEXT id` the application
+  supplies took the value on the instance, dropped it from the statement, and stored NULL
+  while the in-memory model went on holding the value it thought it had written. The key is
+  now omitted only when it has no value, which is what leaves AUTOINCREMENT to the database.
+
+- **Hardening: a MySQL adapter that offers `reserve()` may still refuse it.**
+  `LAST_INSERT_ID()` is scoped per connection, so a MySQL insert pins its INSERT and the
+  SELECT that reads the id to one connection, reserving one where the adapter supports it
+  and falling back to a short transaction where it does not. The check was
+  `typeof conn.reserve === "function"`, and presence is not support — an adapter can expose
+  the method and throw `"This adapter doesn't support connection reservation"` when it is
+  called, which is what Bun's SQLite adapter does.
+
+  The reservation is now attempted and the transaction path used when it refuses. Only the
+  acquisition is guarded: a failure inside the insert is a real error and is not retried
+  against a second connection. `try`/`catch` rather than `.catch()`, since an adapter that
+  refuses may throw synchronously.
+
+  No released version was affected — this path was only reachable through a test that had
+  leaked a dialect (see below). Changed because the detection was wrong either way.
+
+- **A dialect-coverage test left the ORM in MySQL mode for the rest of the process.**
+  `server.smoke.test.ts` sets four globals in `beforeAll` and restored three — the
+  BaseModel dialect stayed on whatever server it had just tested. Every later file in that
+  process then took the MySQL insert branch, which reads the new row's id with
+  `LAST_INSERT_ID()`; against the SQLite connection those tests actually use, that is
+  `no such function`.
+
+  Test-only, and it never reached a release: the leak needs `ZT_MYSQL_URL` set, which
+  happens in one CI job. Postgres hid it for months — its branch uses `RETURNING`, which
+  SQLite also supports — so only the MySQL job could go red, and only when the file order
+  put the smoke test first. Bun walks test files in directory order, which is arbitrary on
+  Linux, so "when" was a coin flip on every run.
+
 ## [1.15.0] — 2026-09-04
 
 ### Changed — **BREAKING**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/orm",
-  "version": "1.15.0",
+  "version": "1.15.2",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -31,8 +31,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.15.0",
-    "@zerotal/validator": "1.15.0"
+    "@zerotal/core": "1.15.2",
+    "@zerotal/validator": "1.15.2"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/db/DB.ts

@@ -17,6 +17,7 @@ import {
   allowNPlusOne as _allowNPlusOne,
   type NPlusOneOptions,
 } from "./NPlusOneDetector.ts";
+import { _templateStrings } from "./templateStrings.ts";
 
 // Test-override escape hatch — set by _setDbConnection() in test files.
 // Production code resolves the connection from the container instead.
@@ -140,7 +141,7 @@ let _savepointCounter = 0;
 
 /** Run a raw, parameter-less statement on a specific connection (SAVEPOINT, etc.). */
 function _runRaw(conn: SQLInstance, sql: string): Promise<unknown> {
-  const arr = Object.assign([sql], { raw: [sql] }) as unknown as TemplateStringsArray;
+  const arr = _templateStrings([sql]);
   return conn(arr);
 }
 
@@ -160,7 +161,7 @@ export function _rawStatement(sql: string): Promise<unknown> {
 /** Run a parameterised statement (`?` placeholders) on a specific connection. */
 function _runParams(conn: SQLInstance, sql: string, params: unknown[]): Promise<unknown> {
   const parts = sql.split("?");
-  const tpl = Object.assign(parts, { raw: parts }) as unknown as TemplateStringsArray;
+  const tpl = _templateStrings(parts);
   return conn(tpl, ...params);
 }
 
@@ -246,7 +247,7 @@ export const DB = {
     if (typeof sql === "string") {
       const bindings: unknown[] = Array.isArray(rest[0]) ? (rest[0] as unknown[]) : rest;
       const parts = sql.split("?");
-      const tpl = Object.assign(parts, { raw: parts }) as unknown as TemplateStringsArray;
+      const tpl = _templateStrings(parts);
       const rows = await conn<T>(tpl, ...bindings);
       FrameworkEvents.emit(
         new QueryExecuted(

package/src/db/QueryBuilder.ts

@@ -20,6 +20,7 @@ import type {
   SimplePaginateResult,
 } from "./types.ts";
 import { withPaginationHelpers, withSimplePaginationHelpers } from "./types.ts";
+import { _templateStrings } from "./templateStrings.ts";
 
 /**
  * The comparison operators accepted in a value-comparison slot. Exported so
@@ -204,8 +205,7 @@ function _getCachedTemplate(strings: string[]): TemplateStringsArray {
   const key = strings.join("\x00");
   let tpl = _tplCache.get(key);
   if (!tpl) {
-    const arr = [...strings];
-    tpl = Object.assign(arr, { raw: arr }) as TemplateStringsArray;
+    tpl = _templateStrings(strings);
     if (_tplCache.size >= _TPL_CACHE_MAX) {
       // FIFO eviction: drop the oldest interned shape.
       const oldest = _tplCache.keys().next().value;

package/src/db/templateStrings.ts

@@ -0,0 +1,19 @@
+/**
+ * Build the `strings` argument for a Bun SQL tagged-template call from plain strings.
+ *
+ * Bun's `sql` function wants what the language hands a tag: a frozen array whose `raw`
+ * is a property you cannot see when you enumerate it. `Object.assign(parts, { raw: parts })`
+ * makes the property enumerable, and Bun 1.4.4 refuses that with "has an enumerable 'raw'
+ * property, so it is not a template object" — every statement built from a runtime-assembled
+ * string failed, which is nearly everything the ORM sends. `defineProperty` leaves `raw`
+ * non-enumerable, as a real template object has it.
+ *
+ * Copies its input, so the caller's array is neither frozen nor given a `raw`.
+ *
+ * @internal Shared by the ORM and by the packages that issue SQL of their own.
+ */
+export function _templateStrings(parts: readonly string[]): TemplateStringsArray {
+  const strings = [...parts];
+  Object.defineProperty(strings, "raw", { value: strings });
+  return Object.freeze(strings) as TemplateStringsArray;
+}

package/src/index.ts

@@ -97,6 +97,7 @@ export type { InsertPayload, UpdatePayload } from "./model/payload.ts";
 export { ModelQueryBuilder, _globalScopeRegistry } from "./model/ModelQueryBuilder.ts";
 export type { GlobalScopeCallback, RelationConstraint } from "./model/ModelQueryBuilder.ts";
 export { DB } from "./db/DB.ts";
+export { _templateStrings } from "./db/templateStrings.ts";
 export {
   _getConnection,
   _setDbConnection,

package/src/model/BaseModel.ts

@@ -1,6 +1,6 @@
 import type { SQLInstance } from "../db/sql-types.ts";
 import type { PaginateResult } from "../db/types.ts";
-import { RequestContext, FrameworkEvents } from "@zerotal/core";
+import { RequestContext, FrameworkEvents, ZerotalError } from "@zerotal/core";
 import { ModelChanged } from "../events.ts";
 import { Carbon } from "@zerotal/core/carbon";
 import { toCamelKey as toCamel, toSnakeColumn as toSnake } from "../support/identifiers.ts";
@@ -923,6 +923,10 @@ export class BaseModel {
    * Primary-key value. Populated after {@link save} inserts a new row, or when
    * the instance is hydrated from the database.
    *
+   * A model that overrides {@link primaryKey} carries its key under that name
+   * instead (`uuid`, `user_id`, …) and leaves this one unset — every persistence
+   * method reads the declared key, not this property.
+   *
    * @category Attributes & mass assignment
    */
   id!: number;
@@ -955,6 +959,51 @@ export class BaseModel {
    */
   updatedAt?: Carbon;
 
+  /**
+   * The value every `WHERE <primary key> = …` this instance issues is keyed on:
+   * update, delete, refresh, fresh, increment/decrement and the relation
+   * aggregate loads.
+   *
+   * Reads the property named by {@link primaryKey} rather than `id`, because a
+   * model that overrides the key has no `id` — these all used `this.id`, so an
+   * `uuid`-keyed model issued `WHERE uuid = NULL`: an update and a delete both
+   * reported success having touched no row, and `refresh()` threw
+   * {@link ModelNotFoundError} for a row that was sitting right there.
+   *
+   * Prefers the loaded snapshot so reassigning the key updates the row it was
+   * read from (`SET uuid = new WHERE uuid = old`) instead of a row that does not
+   * exist yet.
+   *
+   * @internal
+   */
+  private get _keyValue(): unknown {
+    const pk = toCamel((this.constructor as typeof BaseModel).primaryKey);
+    const loaded = (this._original as Record<string, unknown>)[pk];
+    return loaded !== undefined ? loaded : (this as unknown as Record<string, unknown>)[pk];
+  }
+
+  /**
+   * Throw rather than build a `WHERE <key> = NULL` that quietly matches nothing.
+   * Reached when a row was hydrated without its key column (`select("name")`),
+   * where the silent version of this looked exactly like a successful write.
+   *
+   * @internal
+   */
+  private _requireKey(operation: string): unknown {
+    const key = this._keyValue;
+    if (key === undefined || key === null) {
+      const ModelClass = this.constructor as typeof BaseModel;
+      throw new ZerotalError(
+        `Cannot ${operation} ${ModelClass.name}: its primary key "${ModelClass.primaryKey}" is not set. ` +
+          `Load the row including its key column, or set the key before saving.`,
+        "E_NO_PRIMARY_KEY",
+        500,
+        { model: ModelClass.name, primaryKey: ModelClass.primaryKey, operation },
+      );
+    }
+    return key;
+  }
+
   /** @internal Snapshot of attribute values at load/last-save, for dirty tracking. */
   private _original: Record<string, unknown> = {};
   /** @internal Keys force-marked dirty via {@link markDirty}. */
@@ -1762,13 +1811,25 @@ export class BaseModel {
     const colReg = columnsFor(ModelClass as unknown as ClassRef);
     const colKeys = _allColumnKeys(ModelClass as unknown as ClassRef);
 
+    const pkProp = toCamel(ModelClass.primaryKey);
+    const pkColumn = toSnake(ModelClass.primaryKey);
+
     if (!this._exists) {
       // ── INSERT ──
       await HookRegistry.run(ModelClass, "beforeCreate", this);
 
+      // The primary key is a system column only while the DATABASE mints it. When the
+      // app mints it — `static primaryKey = "uuid"`, or a TEXT `id` — it has to reach
+      // the INSERT, so drop it from the skip set here (it is added back explicitly
+      // below, since the key is often not `@column`-registered and `colKeys` would
+      // filter it out). An unset key is still omitted, so AUTOINCREMENT is untouched.
+      const insertSkip = SYSTEM_KEYS.has(pkProp)
+        ? new Set([...SYSTEM_KEYS].filter((k) => k !== pkProp))
+        : SYSTEM_KEYS;
+
       const row: Record<string, unknown> = _writeDialect.run(dialect, () => {
         const r: Record<string, unknown> = {};
-        for (const [key, val] of ownDataEntries(this, SYSTEM_KEYS, rels, colKeys)) {
+        for (const [key, val] of ownDataEntries(this, insertSkip, rels, colKeys)) {
           // A declared field that was never assigned is `undefined`, and writing that
           // as an explicit NULL made `@column({ default: … })` inert: the INSERT named
           // the column, so the database never applied its own default and a NOT NULL
@@ -1788,6 +1849,12 @@ export class BaseModel {
           }
           r[toSnake(key)] = _serializeForWrite(key, effective, casts, colReg, ModelClass.name);
         }
+        // An app-minted key that is not `@column`-registered (the common shape for a
+        // plain `id`) never reaches the loop above, so take it straight off the instance.
+        const minted = self[pkProp];
+        if (minted !== undefined && minted !== null && !(pkColumn in r)) {
+          r[pkColumn] = _serializeForWrite(pkProp, minted, casts, colReg, ModelClass.name);
+        }
         if (ModelClass.timestamps) {
           const now = _serializeDate(new Date());
           r["created_at"] = now;
@@ -1806,11 +1873,22 @@ export class BaseModel {
       });
       segs.push(")");
 
-      let newId: number;
-      if (dialect === "postgres") {
+      // The key to read the row back by. When the app minted it there is nothing to
+      // ask the database for — and asking was the bug: `last_insert_rowid()` /
+      // `LAST_INSERT_ID()` answer with a rowid, which no TEXT key ever equals, so the
+      // re-read below matched no row and left the instance with no timestamps, no
+      // database defaults and `_exists` still false — making the NEXT save() insert
+      // the same row a second time instead of updating it.
+      const mintedKey = pkColumn in row ? row[pkColumn] : undefined;
+
+      let newId: unknown;
+      if (mintedKey !== undefined && mintedKey !== null) {
+        await runSegs(conn, segs);
+        newId = mintedKey;
+      } else if (dialect === "postgres") {
         segs.push(` RETURNING ${ModelClass.primaryKey}`);
-        const [returning] = await runQuery<Record<string, number>>(conn, segs);
-        newId = returning![ModelClass.primaryKey as string] as number;
+        const [returning] = await runQuery<Record<string, unknown>>(conn, segs);
+        newId = returning![ModelClass.primaryKey as string];
       } else if (dialect === "mysql") {
         // LAST_INSERT_ID() is scoped per connection, so the INSERT and the
         // SELECT must be pinned to the SAME connection — under concurrency a
@@ -1833,15 +1911,33 @@ export class BaseModel {
         };
         if (inTx) {
           newId = await insertAndReadId(conn);
-        } else if (typeof reservable.reserve === "function") {
-          const pinned = await reservable.reserve();
-          try {
-            newId = await insertAndReadId(pinned);
-          } finally {
-            pinned.release();
-          }
         } else {
-          newId = await conn.begin((tx) => insertAndReadId(tx));
+          // Presence is not support. Bun's MySQL adapter now exposes `reserve()`
+          // and throws "This adapter doesn't support connection reservation" when
+          // it is called, so `typeof … === "function"` stopped distinguishing the
+          // two and every MySQL insert failed on a runtime that had merely been
+          // updated. Only the acquisition is guarded — a failure inside the insert
+          // is a real error and must not be retried against a second connection.
+          let pinned: (SQLInstance & { release(): void }) | undefined;
+          if (typeof reservable.reserve === "function") {
+            try {
+              // try/catch rather than `.catch()`: an adapter that refuses may throw
+              // synchronously, before there is a promise to attach a handler to.
+              pinned = await reservable.reserve();
+            } catch {
+              pinned = undefined;
+            }
+          }
+
+          if (pinned) {
+            try {
+              newId = await insertAndReadId(pinned);
+            } finally {
+              pinned.release();
+            }
+          } else {
+            newId = await conn.begin((tx) => insertAndReadId(tx));
+          }
         }
       } else {
         await runSegs(conn, segs);
@@ -1855,7 +1951,17 @@ export class BaseModel {
         `SELECT * FROM ${ModelClass.table} WHERE ${ModelClass.primaryKey} = `,
         { val: newId },
       ]);
-      if (rows[0]) _applyRow(this, rows[0]);
+      if (rows[0]) {
+        _applyRow(this, rows[0]);
+      } else {
+        // The INSERT succeeded, so the instance is resident whether or not the row came
+        // back (a trigger may have moved it, the target may be a view). Record that much
+        // instead of leaving `_exists` false, which turns the next save() into a second
+        // INSERT and a duplicate-key error rather than the UPDATE the caller asked for.
+        if (newId !== undefined && newId !== null) self[pkProp] = newId;
+        this._exists = true;
+        this._original = { ...this._original, [pkProp]: self[pkProp] };
+      }
 
       await HookRegistry.run(ModelClass, "afterCreate", this);
     } else {
@@ -1886,7 +1992,7 @@ export class BaseModel {
           segs.push({ val });
         });
         segs.push(` WHERE ${ModelClass.primaryKey} = `);
-        segs.push({ val: this.id });
+        segs.push({ val: this._requireKey("update") });
         await runSegs(conn, segs);
 
         const self = this as unknown as Record<string, unknown>;
@@ -1922,7 +2028,7 @@ export class BaseModel {
         `UPDATE ${ModelClass.table} SET deleted_at = `,
         { val: _writeDialect.run(dialect, () => _serializeDate(now.toDate())) },
         ` WHERE ${ModelClass.primaryKey} = `,
-        { val: this.id },
+        { val: this._requireKey("delete") },
       ]);
       // `deletedAt` lives on the SoftDeletes mixin; this branch only runs for models
       // that compose it (softDeletes === true). Carbon, to match what a reload of
@@ -1931,7 +2037,7 @@ export class BaseModel {
     } else {
       await runSegs(conn, [
         `DELETE FROM ${ModelClass.table} WHERE ${ModelClass.primaryKey} = `,
-        { val: this.id },
+        { val: this._requireKey("delete") },
       ]);
     }
 
@@ -1993,11 +2099,12 @@ export class BaseModel {
   async fresh(): Promise<this> {
     const ModelClass = this.constructor as typeof BaseModel;
     const conn = _resolveConn(ModelClass);
+    const key = this._requireKey("reload");
     const rows = await runQuery<Record<string, unknown>>(conn, [
       `SELECT * FROM ${ModelClass.table} WHERE ${ModelClass.primaryKey} = `,
-      { val: this.id },
+      { val: key },
     ]);
-    if (!rows[0]) throw new ModelNotFoundError(ModelClass.name, this.id);
+    if (!rows[0]) throw new ModelNotFoundError(ModelClass.name, key as number | string);
     return ModelClass.fromRow(rows[0]) as this;
   }
 
@@ -2011,11 +2118,12 @@ export class BaseModel {
   async refresh(): Promise<this> {
     const ModelClass = this.constructor as typeof BaseModel;
     const conn = _resolveConn(ModelClass);
+    const key = this._requireKey("reload");
     const rows = await runQuery<Record<string, unknown>>(conn, [
       `SELECT * FROM ${ModelClass.table} WHERE ${ModelClass.primaryKey} = `,
-      { val: this.id },
+      { val: key },
     ]);
-    if (!rows[0]) throw new ModelNotFoundError(ModelClass.name, this.id);
+    if (!rows[0]) throw new ModelNotFoundError(ModelClass.name, key as number | string);
     _applyRow(this, rows[0]);
     return this;
   }
@@ -2030,7 +2138,13 @@ export class BaseModel {
     const ModelClass = this.constructor as typeof BaseModel;
     const rels = relNames(ModelClass as unknown as ClassRef);
     const colKeys = _allColumnKeys(ModelClass as unknown as ClassRef);
-    const skip = new Set<string>([...SYSTEM_KEYS, ...(except ?? [])]);
+    // The declared key, not just `id` — copying a `uuid` forward produced a replica
+    // that could only ever fail on save with a duplicate-key error.
+    const skip = new Set<string>([
+      ...SYSTEM_KEYS,
+      toCamel(ModelClass.primaryKey),
+      ...(except ?? []),
+    ]);
     const inst = new (this.constructor as new () => this)();
     for (const [k, v] of ownDataEntries(this, skip, rels, colKeys)) {
       (inst as unknown as Record<string, unknown>)[k] = v;
@@ -2104,7 +2218,7 @@ export class BaseModel {
       `UPDATE ${ModelClass.table} SET ${col} = ${col} ${op} `,
       { val: Math.abs(delta) },
       ` WHERE ${ModelClass.primaryKey} = `,
-      { val: this.id },
+      { val: this._requireKey(delta >= 0 ? "increment" : "decrement") },
     ]);
     const self = this as unknown as Record<string, unknown>;
     const current = Number(self[column] ?? 0);
@@ -2122,7 +2236,7 @@ export class BaseModel {
     const rels = Array.isArray(relations) ? relations : [relations];
     const ModelClass = this.constructor as typeof BaseModel;
     const qb = new ModelQueryBuilder(ModelClass.table, _resolveConn(ModelClass), ModelClass);
-    qb.where(ModelClass.primaryKey, this.id);
+    qb.where(ModelClass.primaryKey, this._keyValue as number | string);
     for (const r of rels) qb.withCount(r);
     const fresh = (await qb.limit(1).get<BaseModel>())[0] ?? null;
     const src = fresh as unknown as Record<string, unknown> | null;
@@ -2153,15 +2267,18 @@ export class BaseModel {
   ): Promise<T[]> {
     if (models.length === 0) return models;
     const rels = Array.isArray(relations) ? relations : [relations];
-    const idOf = (m: T): unknown => (m as unknown as { id: unknown }).id;
+    // Read the declared key, not `id`: on a model that overrides `primaryKey` this
+    // collected a list of `undefined` and set every count to 0.
+    const keyProp = toCamel(this.primaryKey);
+    const idOf = (m: BaseModel): unknown => (m as unknown as Record<string, unknown>)[keyProp];
 
     const qb = new ModelQueryBuilder(this.table, _resolveConn(this), this);
-    qb.whereIn(this.primaryKey, models.map(idOf));
+    qb.whereIn(this.primaryKey, models.map(idOf) as (number | string)[]);
     for (const r of rels) qb.withCount(r);
     const fresh = await qb.get<BaseModel>();
 
     const byId = new Map<unknown, Record<string, unknown>>();
-    for (const f of fresh) byId.set((f as unknown as { id: unknown }).id, f as never);
+    for (const f of fresh) byId.set(idOf(f), f as never);
 
     for (const m of models) {
       const src = byId.get(idOf(m));
@@ -2182,7 +2299,7 @@ export class BaseModel {
   ): Promise<this> {
     const ModelClass = this.constructor as typeof BaseModel;
     const qb = new ModelQueryBuilder(ModelClass.table, _resolveConn(ModelClass), ModelClass);
-    qb.where(ModelClass.primaryKey, this.id);
+    qb.where(ModelClass.primaryKey, this._keyValue as number | string);
     (qb as unknown as Record<string, (r: string, c: string) => void>)[`with${fn}`]?.(
       relation,
       column,

package/src/provider/DatabaseProvider.ts

@@ -25,6 +25,7 @@ import {
   RUN_MIGRATIONS_PATH,
   _mintDiagnosisToken,
 } from "../diagnostics/runMigrationsEndpoint.ts";
+import { _templateStrings } from "../db/templateStrings.ts";
 
 // Extend the core container registry so 'db' is a typed binding.
 declare module "@zerotal/core" {
@@ -171,27 +172,17 @@ export class DatabaseProvider extends ServiceProvider {
           let rows: unknown[];
           if (ignoreId !== undefined) {
             const strs = [`SELECT 1 FROM ${table} WHERE ${column} = `, ` AND id != `, ` LIMIT 1`];
-            rows = await conn(
-              Object.assign(strs, { raw: strs }) as unknown as TemplateStringsArray,
-              value,
-              ignoreId,
-            );
+            rows = await conn(_templateStrings(strs), value, ignoreId);
           } else {
             const strs = [`SELECT 1 FROM ${table} WHERE ${column} = `, ` LIMIT 1`];
-            rows = await conn(
-              Object.assign(strs, { raw: strs }) as unknown as TemplateStringsArray,
-              value,
-            );
+            rows = await conn(_templateStrings(strs), value);
           }
           return rows.length === 0; // true = unique (no duplicate found)
         }
 
         // exists
         const strs = [`SELECT 1 FROM ${table} WHERE ${column} = `, ` LIMIT 1`];
-        const rows = await conn(
-          Object.assign(strs, { raw: strs }) as unknown as TemplateStringsArray,
-          value,
-        );
+        const rows = await conn(_templateStrings(strs), value);
         return rows.length > 0; // true = exists (row found)
       });
     } catch {

package/src/schema/MigrationRunner.ts

@@ -8,6 +8,7 @@ import { MigrationRan } from "../events.ts";
 import { dialectFor } from "../db/QueryBuilder.ts";
 import { getDialect } from "../db/dialects/index.ts";
 import { TransactionContext } from "../db/TransactionContext.ts";
+import { _templateStrings } from "../db/templateStrings.ts";
 
 // ── Public types ──────────────────────────────────────────────────────────────
 
@@ -375,9 +376,7 @@ export class MigrationRunner {
   /** Execute a DDL string with no parameters. */
   private async _ddl(sql: string): Promise<void> {
     const strings = [sql];
-    const tpl = Object.assign(strings, {
-      raw: strings,
-    }) as TemplateStringsArray;
+    const tpl = _templateStrings(strings);
     await this._active()(tpl);
   }
 
@@ -389,22 +388,20 @@ export class MigrationRunner {
   /** SELECT with exactly one bound parameter. */
   private async _selectParam<T>(sql: string, value: unknown): Promise<T[]> {
     const parts = sql.split("?");
-    const tpl = Object.assign(parts, { raw: parts }) as TemplateStringsArray;
+    const tpl = _templateStrings(parts);
     return this._active()<T>(tpl, value);
   }
 
   /** DML with N bound parameters. */
   private async _exec(sql: string, ...values: unknown[]): Promise<void> {
     const parts = sql.split("?");
-    const tpl = Object.assign(parts, { raw: parts }) as TemplateStringsArray;
+    const tpl = _templateStrings(parts);
     await this._active()(tpl, ...values);
   }
 
   private async _exec0<T>(sql: string): Promise<T[]> {
     const strings = [sql];
-    const tpl = Object.assign(strings, {
-      raw: strings,
-    }) as TemplateStringsArray;
+    const tpl = _templateStrings(strings);
     return this._active()<T>(tpl);
   }
 

package/src/schema/Schema.ts

@@ -2,6 +2,7 @@ import { _getScopedDbConnection } from "../db/DB.ts";
 import { _getDialect } from "../model/BaseModel.ts";
 import { getDialect } from "../db/dialects/index.ts";
 import { Blueprint } from "./Blueprint.ts";
+import { _templateStrings } from "../db/templateStrings.ts";
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
@@ -16,7 +17,7 @@ async function ddl(sql: string): Promise<void> {
   // migration runner's `begin()` wrapper decorative.
   const conn = _getScopedDbConnection();
   const strings = [sql];
-  const tpl = Object.assign(strings, { raw: strings }) as TemplateStringsArray;
+  const tpl = _templateStrings(strings);
   await conn(tpl);
 }
 
@@ -29,7 +30,7 @@ async function query<T = Record<string, unknown>>(sql: string, params: unknown[]
   // the tables that transaction has created, which a pooled connection cannot.
   const conn = _getScopedDbConnection();
   const parts = sql.split("?");
-  const tpl = Object.assign(parts, { raw: parts }) as TemplateStringsArray;
+  const tpl = _templateStrings(parts);
   return conn<T>(tpl, ...params);
 }
 

package/src/schema/SchemaInspector.ts

@@ -1,5 +1,6 @@
 import { _getDbConnection } from "../db/DB.ts";
 import { _getDialect } from "../model/BaseModel.ts";
+import { _templateStrings } from "../db/templateStrings.ts";
 
 // ── DB column descriptor (normalised across dialects) ─────────────────────────
 
@@ -23,7 +24,7 @@ export interface LiveTable {
 async function queryRaw<T>(sql: string): Promise<T[]> {
   const conn = _getDbConnection();
   const strings = [sql];
-  const tpl = Object.assign(strings, { raw: strings }) as TemplateStringsArray;
+  const tpl = _templateStrings(strings);
   return conn<T>(tpl);
 }
 
@@ -31,7 +32,7 @@ async function queryRaw<T>(sql: string): Promise<T[]> {
 async function queryParam<T>(sql: string, value: unknown): Promise<T[]> {
   const conn = _getDbConnection();
   const parts = sql.split("?");
-  const tpl = Object.assign(parts, { raw: parts }) as TemplateStringsArray;
+  const tpl = _templateStrings(parts);
   return conn<T>(tpl, value);
 }