tina4-nodejs 3.13.97 → 3.13.99

package/packages/orm/src/migration.ts

@@ -83,8 +83,12 @@ async function firebirdColumnExists(
 /**
  * If stmt is an ALTER TABLE ... ADD on Firebird and the column already exists,
  * returns a skip reason string. Returns null if the statement should execute normally.
+ *
+ * Exported (like its shouldSkipCreateTable sibling) so it can be driven
+ * directly against a REAL Firebird connection in
+ * test/migrationContract.test.ts -- no fake adapter needed.
  */
-async function shouldSkipForFirebird(
+export async function shouldSkipForFirebird(
   db: DatabaseAdapter,
   stmt: string,
 ): Promise<string | null> {
@@ -278,6 +282,24 @@ function buildAddColumnSql(
  */
 const MIGRATION_TABLE = "tina4_migration";
 
+/**
+ * The tracking-table identifier, quoted for the CALLING adapter's engine.
+ *
+ * SQLite, PostgreSQL, MSSQL and Firebird all accept ANSI double-quoted
+ * identifiers, but MySQL's default sql_mode (no ANSI_QUOTES — the stock
+ * `mysql:8` image never sets it) parses `"..."` as a STRING LITERAL, not an
+ * identifier. `CREATE TABLE "tina4_migration" (...)` on a database where the
+ * table does not already exist fails: "You have an error in your SQL syntax
+ * ... near '"tina4_migration" ('" — MEASURED against a real fresh MySQL 8
+ * container (a long-lived dev database that already has the table masks this
+ * completely, which is exactly why it only ever surfaced on CI's ephemeral
+ * one). Backticks are MySQL's identifier quote and are accepted in every
+ * sql_mode, so they are always correct there.
+ */
+function mt(db: DatabaseAdapter): string {
+  return engineOf(db) === "mysql" ? `\`${MIGRATION_TABLE}\`` : `"${MIGRATION_TABLE}"`;
+}
+
 /**
  * Derive a human-readable description from a migration name, matching the
  * Python master: strip a leading numeric/timestamp prefix and turn `_` into
@@ -291,8 +313,8 @@ function deriveDescription(name: string): string {
  * Build an `ALTER TABLE ... ADD` statement for the tracking table. Firebird
  * uses `ADD <col>` (no COLUMN keyword); every other engine uses `ADD COLUMN`.
  */
-function migrationAddColumnSql(fb: boolean, col: string, type: string, extra = ""): string {
-  return `ALTER TABLE "${MIGRATION_TABLE}" ADD ${fb ? "" : "COLUMN "}${col} ${type}${extra}`;
+function migrationAddColumnSql(db: DatabaseAdapter, col: string, type: string, extra = ""): string {
+  return `ALTER TABLE ${mt(db)} ADD ${isFirebirdAdapter(db) ? "" : "COLUMN "}${col} ${type}${extra}`;
 }
 
 /**
@@ -321,7 +343,7 @@ async function ensureMigrationTableOn(db: DatabaseAdapter): Promise<void> {
       } catch {
         // Generator may already exist
       }
-      await adapterExecute(db, `CREATE TABLE "${MIGRATION_TABLE}" (
+      await adapterExecute(db, `CREATE TABLE ${mt(db)} (
         id INTEGER NOT NULL PRIMARY KEY,
         migration_name VARCHAR(500) NOT NULL UNIQUE,
         description VARCHAR(500),
@@ -340,7 +362,7 @@ async function ensureMigrationTableOn(db: DatabaseAdapter): Promise<void> {
       const idCol = migrationIdColumn(db);
       const engine = engineOf(db);
       const ifNotExists = engine === "mssql" ? "" : "IF NOT EXISTS ";
-      await adapterExecute(db, `CREATE TABLE ${ifNotExists}"${MIGRATION_TABLE}" (
+      await adapterExecute(db, `CREATE TABLE ${ifNotExists}${mt(db)} (
         ${idCol},
         migration_name VARCHAR(500) NOT NULL UNIQUE,
         description VARCHAR(500),
@@ -387,17 +409,17 @@ async function upgradeMigrationTable(db: DatabaseAdapter): Promise<void> {
       try { await adapterExecute(db, sql); } catch { /* column may already exist */ }
     };
 
-    await tryExec(migrationAddColumnSql(fb, "migration_name", nameType));
-    if (!cols.has("description")) await tryExec(migrationAddColumnSql(fb, "description", nameType));
-    if (!cols.has("passed")) await tryExec(migrationAddColumnSql(fb, "passed", "INTEGER", " DEFAULT 1"));
-    if (!cols.has("executed_at")) await tryExec(migrationAddColumnSql(fb, "executed_at", tsType));
-    if (!cols.has("batch")) await tryExec(migrationAddColumnSql(fb, "batch", "INTEGER", " DEFAULT 1"));
+    await tryExec(migrationAddColumnSql(db, "migration_name", nameType));
+    if (!cols.has("description")) await tryExec(migrationAddColumnSql(db, "description", nameType));
+    if (!cols.has("passed")) await tryExec(migrationAddColumnSql(db, "passed", "INTEGER", " DEFAULT 1"));
+    if (!cols.has("executed_at")) await tryExec(migrationAddColumnSql(db, "executed_at", tsType));
+    if (!cols.has("batch")) await tryExec(migrationAddColumnSql(db, "batch", "INTEGER", " DEFAULT 1"));
 
     // Copy legacy values across so applied migrations remain applied.
-    await tryExec(`UPDATE "${MIGRATION_TABLE}" SET migration_name = name WHERE migration_name IS NULL`);
-    await tryExec(`UPDATE "${MIGRATION_TABLE}" SET passed = 1 WHERE passed IS NULL`);
+    await tryExec(`UPDATE ${mt(db)} SET migration_name = name WHERE migration_name IS NULL`);
+    await tryExec(`UPDATE ${mt(db)} SET passed = 1 WHERE passed IS NULL`);
     if (cols.has("applied_at")) {
-      await tryExec(`UPDATE "${MIGRATION_TABLE}" SET executed_at = applied_at WHERE executed_at IS NULL`);
+      await tryExec(`UPDATE ${mt(db)} SET executed_at = applied_at WHERE executed_at IS NULL`);
     }
     return;
   }
@@ -405,7 +427,7 @@ async function upgradeMigrationTable(db: DatabaseAdapter): Promise<void> {
   // Any other legacy shape: just ensure the batch column exists (prior behaviour).
   if (!cols.has("batch")) {
     try {
-      await adapterExecute(db, migrationAddColumnSql(fb, "batch", "INTEGER", " NOT NULL DEFAULT 1"));
+      await adapterExecute(db, migrationAddColumnSql(db, "batch", "INTEGER", " NOT NULL DEFAULT 1"));
     } catch {
       // ignore — column may already exist
     }
@@ -426,7 +448,7 @@ export async function ensureMigrationTable(): Promise<void> {
 export async function getNextBatch(): Promise<number> {
   const adapter = getAdapter();
   const rows = await adapterQuery<{ max_batch: number | null }>(adapter,
-    `SELECT MAX(batch) as max_batch FROM "${MIGRATION_TABLE}" WHERE passed = 1`,
+    `SELECT MAX(batch) as max_batch FROM ${mt(adapter)} WHERE passed = 1`,
   );
   return (rows[0]?.max_batch ?? 0) + 1;
 }
@@ -437,7 +459,7 @@ export async function getNextBatch(): Promise<number> {
 export async function isMigrationApplied(name: string): Promise<boolean> {
   const adapter = getAdapter();
   const rows = await adapterQuery(adapter,
-    `SELECT id FROM "${MIGRATION_TABLE}" WHERE migration_name = ? AND passed = 1`,
+    `SELECT id FROM ${mt(adapter)} WHERE migration_name = ? AND passed = 1`,
     [name],
   );
   return rows.length > 0;
@@ -474,7 +496,7 @@ async function recordApplied(
   // Delete-before-insert: supersede any leftover row for this migration_name so
   // the INSERT below never collides on the UNIQUE migration_name.
   await adapterExecute(db,
-    `DELETE FROM "${MIGRATION_TABLE}" WHERE migration_name = ?`,
+    `DELETE FROM ${mt(db)} WHERE migration_name = ?`,
     [name],
   );
   // Build the column list from the columns that ACTUALLY exist on the table, so
@@ -504,7 +526,7 @@ async function recordApplied(
 
   const placeholders = insertCols.map(() => "?").join(", ");
   await adapterExecute(db,
-    `INSERT INTO "${MIGRATION_TABLE}" (${insertCols.join(", ")}) VALUES (${placeholders})`,
+    `INSERT INTO ${mt(db)} (${insertCols.join(", ")}) VALUES (${placeholders})`,
     values,
   );
 }
@@ -564,13 +586,13 @@ export async function applyMigration(
 export async function getLastBatchMigrations(): Promise<Array<{ id: number; migration_name: string; batch: number }>> {
   const adapter = getAdapter();
   const rows = await adapterQuery<{ max_batch: number | null }>(adapter,
-    `SELECT MAX(batch) as max_batch FROM "${MIGRATION_TABLE}" WHERE passed = 1`,
+    `SELECT MAX(batch) as max_batch FROM ${mt(adapter)} WHERE passed = 1`,
   );
   const lastBatch = rows[0]?.max_batch;
   if (lastBatch === null || lastBatch === undefined) return [];
 
   return adapterQuery<{ id: number; migration_name: string; batch: number }>(adapter,
-    `SELECT id, migration_name, batch FROM "${MIGRATION_TABLE}" WHERE batch = ? AND passed = 1 ORDER BY id DESC`,
+    `SELECT id, migration_name, batch FROM ${mt(adapter)} WHERE batch = ? AND passed = 1 ORDER BY id DESC`,
     [lastBatch],
   );
 }
@@ -581,7 +603,7 @@ export async function getLastBatchMigrations(): Promise<Array<{ id: number; migr
 export async function removeMigrationRecord(name: string): Promise<void> {
   const adapter = getAdapter();
   await adapterExecute(adapter,
-    `DELETE FROM "${MIGRATION_TABLE}" WHERE migration_name = ?`,
+    `DELETE FROM ${mt(adapter)} WHERE migration_name = ?`,
     [name],
   );
 }
@@ -589,17 +611,26 @@ export async function removeMigrationRecord(name: string): Promise<void> {
 /**
  * Rollback the last batch of migrations using .down.sql files.
  *
- * For each migration in the last batch (in reverse order):
- * 1. Looks for a corresponding .down.sql file on disk
- * 2. If found, reads and executes the SQL statements
- * 3. If not found, logs a warning
- * 4. Deletes the tracking record either way
+ * FAIL-SAFE (MIG-DEC-02, reuses the Python reference model): for each
+ * migration in the last batch (in reverse order), the down artifact must
+ * actually run before the tracking record is removed. A MISSING .down.sql
+ * (or, on the legacy Map API, no registered down function) or a FAILING down
+ * statement now THROWS instead of logging a warning/error and still deleting
+ * the record — the old behaviour was the exact MIG-ROLLBACK-DROPS-LEDGER bug:
+ * the schema stayed applied but the ledger row vanished, silently untracked.
+ * The DELETE runs inside the SAME transaction as the down statements, so a
+ * partially-executed down (some statements ran, a later one failed) rolls
+ * back too — no half-reversed schema left behind either.
  *
  * @param migrationsDir - Directory containing migration files (default: "migrations")
  * @param delimiter - SQL statement delimiter (default: ";")
  * @returns Array of the down-migration files that were run, e.g.
  *   "000001_create_users.down.sql". (The legacy down-FUNCTION Map API returns the
  *   bare migration name instead, since no .down.sql file is involved there.)
+ * @throws When a migration in the batch has no down artifact, or its down
+ *   statement(s) fail — the batch stops at that migration; earlier
+ *   migrations in the SAME call that already rolled back stay rolled back
+ *   (each is its own transaction).
  *
  * NOTE on return form (intentional, cross-framework): migration return values reflect
  * WHAT each method acted on, so the forms differ by method and that is by design (not
@@ -620,9 +651,12 @@ export async function rollback(
     const rolledBack: string[] = [];
     for (const migration of migrations) {
       const down = downFunctions.get(migration.migration_name);
-      if (down) {
-        await down();
+      if (!down) {
+        throw new Error(
+          `Cannot rollback ${migration.migration_name}: no down function registered`,
+        );
       }
+      await down();
       await removeMigrationRecord(migration.migration_name);
       // Legacy down-FUNCTION API: no .down.sql file is involved here, so return the
       // bare migration name (the file-based path below returns "name.down.sql").
@@ -642,32 +676,41 @@ export async function rollback(
     const downFile = `${migration.migration_name}.down.sql`;
     const downPath = join(dir, downFile);
 
-    if (existsSync(downPath)) {
-      const sqlContent = readFileSync(downPath, "utf-8").trim();
-      if (sqlContent) {
-        const statements = splitStatements(sqlContent, delim);
+    if (!existsSync(downPath)) {
+      throw new Error(
+        `Cannot rollback ${migration.migration_name}: no .down.sql file found`,
+      );
+    }
+
+    const sqlContent = readFileSync(downPath, "utf-8").trim();
+    if (sqlContent) {
+      const statements = splitStatements(sqlContent, delim);
+      try {
+        await adapterStartTransaction(db);
+        for (const stmt of statements) {
+          await adapterExecute(db, stmt);
+        }
+        // Remove the tracking record INSIDE the same transaction as the down
+        // statements, so a failure below rolls back the DDL too, not just the
+        // record removal.
+        await removeMigrationRecord(migration.migration_name);
+        await adapterCommit(db);
+      } catch (err) {
         try {
-          await adapterStartTransaction(db);
-          for (const stmt of statements) {
-            await adapterExecute(db, stmt);
-          }
-          await adapterCommit(db);
-        } catch (err) {
-          try {
-            await adapterRollback(db);
-          } catch {
-            // rollback may fail if auto-rolled-back
-          }
-          const msg = err instanceof Error ? err.message : String(err);
-          console.error(`  Rollback failed for ${migration.migration_name}: ${msg}`);
-          // Still remove the record so the migration can be re-applied
+          await adapterRollback(db);
+        } catch {
+          // rollback may fail if auto-rolled-back
         }
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Rollback failed: ${migration.migration_name} — ${msg}`);
       }
     } else {
-      console.warn(`  Warning: No .down.sql file found for ${migration.migration_name} — skipping SQL execution`);
+      // An EXISTING but empty/comment-only .down.sql (0 statements) is a
+      // deliberate no-op success — matches the Python reference
+      // (createMigration scaffolds an empty .down.sql by default).
+      await removeMigrationRecord(migration.migration_name);
     }
 
-    await removeMigrationRecord(migration.migration_name);
     // Return the down-migration file that was run (e.g. "name.down.sql"), matching
     // the Python master's rollback return form.
     rolledBack.push(`${migration.migration_name}.down.sql`);
@@ -682,7 +725,7 @@ export async function rollback(
 export async function getAppliedMigrations(): Promise<Array<{ id: number; migration_name: string; description: string; batch: number; executed_at: string; passed: number }>> {
   const adapter = getAdapter();
   return adapterQuery<{ id: number; migration_name: string; description: string; batch: number; executed_at: string; passed: number }>(adapter,
-    `SELECT * FROM "${MIGRATION_TABLE}" WHERE passed = 1 ORDER BY id ASC`,
+    `SELECT * FROM ${mt(adapter)} WHERE passed = 1 ORDER BY id ASC`,
   );
 }
 
@@ -1007,7 +1050,7 @@ export async function migrate(
   let currentBatch = 1;
   try {
     const batchRows = await adapterQuery<{ max_batch: number | null }>(db,
-      `SELECT MAX(batch) as max_batch FROM "${MIGRATION_TABLE}" WHERE passed = 1`,
+      `SELECT MAX(batch) as max_batch FROM ${mt(db)} WHERE passed = 1`,
     );
     currentBatch = (batchRows[0]?.max_batch ?? 0) + 1;
   } catch {
@@ -1023,7 +1066,7 @@ export async function migrate(
     let alreadyApplied = false;
     try {
       const existing = await adapterQuery<{ id: number }>(db,
-        `SELECT id FROM "${MIGRATION_TABLE}" WHERE migration_name = ? AND passed = 1`,
+        `SELECT id FROM ${mt(db)} WHERE migration_name = ? AND passed = 1`,
         [migrationId],
       );
       alreadyApplied = existing.length > 0;
@@ -1136,7 +1179,7 @@ export async function status(
   const appliedNames = new Set<string>();
   try {
     const rows = await adapterQuery<{ migration_name: string }>(db,
-      `SELECT migration_name FROM "${MIGRATION_TABLE}" WHERE passed = 1`,
+      `SELECT migration_name FROM ${mt(db)} WHERE passed = 1`,
     );
     for (const row of rows) {
       if (row.migration_name) appliedNames.add(row.migration_name);

package/packages/orm/src/query.ts

@@ -1,4 +1,5 @@
 import type { QueryOptions } from "./types.js";
+import { DEFAULT_ROW_CAP } from "./database.js";
 
 export interface ParsedQuery {
   where: string;
@@ -12,7 +13,7 @@ export function buildQuery(
   tableName: string,
   options: QueryOptions,
   extraConditions?: string[],
-): { sql: string; countSql: string; params: unknown[] } {
+): { sql: string; countSql: string; params: unknown[]; limit: number; offset: number; page: number } {
   const conditions: string[] = [];
   const params: unknown[] = [];
 
@@ -57,9 +58,17 @@ export function buildQuery(
     orderClause = `ORDER BY ${parts.join(", ")}`;
   }
 
-  // Pagination
-  const limit = options.limit ?? 100;
-  const page = options.page ?? 1;
+  // Pagination — PAGE-DEC-01: clamp page >= 1 BEFORE deriving offset, so
+  // offset=(page-1)*limit can never go negative (a page=0/negative request used
+  // to hand the driver a negative OFFSET - a hard error on PostgreSQL and a
+  // silent-wrong result on SQLite), and cap the per-page size at DEFAULT_ROW_CAP
+  // (100 - the same row cap Database.fetch()/BaseModel.all() already share) so a
+  // client cannot request the whole table in one query. Returning the clamped
+  // limit/offset/page (not just using them locally) lets the caller build the
+  // REST envelope from the values the SQL actually used, instead of recomputing
+  // the same arithmetic a second time from the raw, unclamped query params.
+  const limit = Math.min(options.limit ?? DEFAULT_ROW_CAP, DEFAULT_ROW_CAP);
+  const page = Math.max(options.page ?? 1, 1);
   const offset = (page - 1) * limit;
 
   const sql = `SELECT * FROM "${tableName}" ${whereClause} ${orderClause} LIMIT ? OFFSET ?`;
@@ -69,6 +78,9 @@ export function buildQuery(
     sql,
     countSql,
     params: [...params, limit, offset],
+    limit,
+    offset,
+    page,
   };
 }
 

package/packages/orm/src/seeder.ts

@@ -14,7 +14,7 @@
 //         real parent PKs, and warns on clear type mismatches.
 
 import { FakeData } from "./fakeData.js";
-import { adapterExecute, adapterFetch, adapterColumns } from "./database.js";
+import { adapterExecute, adapterFetch, adapterColumns, adapterInsert } from "./database.js";
 import { Log } from "../../core/src/index.js";
 import type { DatabaseAdapter, FieldDefinition, FieldType } from "./types.js";
 
@@ -37,7 +37,18 @@ export interface SeedOptions {
   overrides?: Record<string, unknown>;
   /** Delete every existing row in the target before seeding (P2). */
   clear?: boolean;
-  /** PRNG seed for reproducible FakeData output (P3). */
+  /**
+   * PRNG seed for reproducible FakeData output (P3). Honoured by seedOrm and
+   * seedModels, which build and seed their own FakeData internally.
+   *
+   * NOT honoured by seedTable (SEED-TABLE-SEED-INERT, SEED-DEC-01, ratified
+   * 2026-08-11 — same principle as the no-op ForeignKeyField on_delete):
+   * seedTable has no generators of its own to seed — fieldMap callables are
+   * opaque — so this used to be a silent no-op there. Passing it to seedTable
+   * now THROWS instead. Build your own `new FakeData(seed)` and close over it
+   * in fieldMap: `const fake = new FakeData(42); seedTable(db, table, count,
+   * { name: () => fake.name() })`.
+   */
   seed?: number;
   /** Re-raise on the first failed row instead of skipping it (P1). */
   strict?: boolean;
@@ -51,14 +62,13 @@ export interface SeedOptions {
 function normaliseOptions(
   overrides?: Record<string, unknown>,
   opts?: SeedOptions,
-): Required<Pick<SeedOptions, "clear" | "strict">> & { overrides?: Record<string, unknown>; seed?: number } {
+): Required<Pick<SeedOptions, "clear" | "strict">> & { overrides?: Record<string, unknown> } {
   const merged: SeedOptions = { ...(opts ?? {}) };
   // The new `opts.overrides` takes precedence if both are supplied.
   const effectiveOverrides = merged.overrides ?? overrides;
   return {
     overrides: effectiveOverrides,
     clear: merged.clear ?? false,
-    seed: merged.seed,
     strict: merged.strict ?? false,
   };
 }
@@ -154,8 +164,10 @@ export async function autoFieldMap(
  *                   (or a static value). If not provided, no rows are inserted.
  * @param overrides - (legacy positional) Static values applied to every row.
  *                   Prefer `opts.overrides`.
- * @param opts - Seed options: `{ overrides, clear, seed, strict }`.
+ * @param opts - Seed options: `{ overrides, clear, strict }`. `opts.seed` is
+ *   NOT honoured here (see {@link SeedOptions.seed}) and throws if supplied.
  * @returns A SeedSummary `{ seeded, failed, errors }`.
+ * @throws {Error} If `opts.seed` is defined (SEED-TABLE-SEED-INERT removal).
  *
  * @example
  *   const fake = new FakeData();
@@ -172,6 +184,15 @@ export async function seedTable(
   overrides?: Record<string, unknown>,
   opts?: SeedOptions,
 ): Promise<SeedSummary> {
+  if (opts?.seed !== undefined) {
+    throw new Error(
+      "seedTable() no longer accepts opts.seed: it has no generators of its own to seed " +
+        "(fieldMap callables are opaque). Build a seeded FakeData yourself and close over it " +
+        "in fieldMap, e.g. const fake = new FakeData(42); seedTable(db, table, count, " +
+        "{ name: () => fake.name() }).",
+    );
+  }
+
   const { overrides: effectiveOverrides, clear, strict } = normaliseOptions(overrides, opts);
 
   if (!fieldMap || Object.keys(fieldMap).length === 0) {
@@ -202,18 +223,19 @@ export async function seedTable(
         }
       }
 
-      // Build INSERT SQL
-      const columns = Object.keys(row);
-      const colList = columns.map((c) => `"${c}"`).join(", ");
-      const placeholders = columns.map(() => "?").join(", ");
-      const values = columns.map((c) => row[c]);
-
-      // adapterExecute() RAISES on a constraint/SQL error since v3.13.x — the
+      // Route through the adapter's OWN native insert path (feature 3's
+      // shared buildInsert()/Dialect) instead of hand-built SQL with a fixed
+      // quote style. A hardcoded double-quote works on PostgreSQL/MSSQL/
+      // SQLite but breaks Firebird: an unquoted CREATE TABLE folds the name
+      // to UPPERCASE, so a quoted lower-case INSERT target is a DIFFERENT,
+      // unfindable identifier ("Table unknown" -204) — the SAME class of
+      // engine-portability bug as PHP's old backtick-quoted seed_table.
+      // adapterInsert() RAISES on a constraint/SQL error since v3.13.x — the
       // try/except is what turns that into a counted, logged, skipped failure.
-      await adapterExecute(
+      await adapterInsert(
         db,
-        `INSERT INTO "${tableName}" (${colList}) VALUES (${placeholders})`,
-        values,
+        tableName,
+        row,
       );
       seeded++;
     } catch (e) {
@@ -410,16 +432,12 @@ export async function seedOrm(
       }
       validateTypes(fields, attrs, modelName);
 
-      const columns = Object.keys(attrs);
-      const colList = columns.map((c) => `"${c}"`).join(", ");
-      const placeholders = columns.map(() => "?").join(", ");
-      const values = columns.map((c) => attrs[c]);
-
-      await adapterExecute(
-        db,
-        `INSERT INTO "${ormClass.tableName}" (${colList}) VALUES (${placeholders})`,
-        values,
-      );
+      // Route through the adapter's OWN native insert path (feature 3's
+      // shared buildInsert()/Dialect) — see the identical note in seedTable()
+      // above. A hand-built, unconditionally double-quoted INSERT breaks
+      // Firebird (asymmetric case-folding: an unquoted CREATE TABLE stores
+      // UPPERCASE, so a quoted lower-case INSERT target is unfindable).
+      await adapterInsert(db, ormClass.tableName, attrs);
       seeded++;
     } catch (e) {
       const message = (e as Error).message ?? String(e);

package/packages/orm/src/sqlTranslator.ts

@@ -67,37 +67,119 @@ export class SQLTranslator {
     return sql;
   }
 
+  // ── Literal-safe rewriting ──────────────────────────────────────
+  //
+  // A dialect rewrite (|| -> CONCAT, TRUE -> 1, ILIKE -> LOWER LIKE) must NEVER
+  // touch text inside a string literal, a quoted identifier or a comment: a
+  // column value of 'a||b', a label 'TRUE', or a LIKE pattern that mentions
+  // ILIKE is DATA, not SQL. Each transform masks every literal/identifier/comment
+  // to an opaque token, rewrites the masked SQL, then restores the tokens, so the
+  // rewrite only ever sees real SQL structure.
+
+  /** Replace string literals, quoted identifiers and comments with opaque
+   * `\x00N\x00` tokens (doubled-quote escapes handled). */
+  private static maskLiterals(sql: string): { masked: string; literals: string[] } {
+    const literals: string[] = [];
+    let out = "";
+    let i = 0;
+    const n = sql.length;
+    while (i < n) {
+      const c = sql[i];
+      const next = sql[i + 1];
+      if (c === "'" || c === '"' || c === "`") {
+        const start = i;
+        i++;
+        while (i < n) {
+          if (sql[i] === c) {
+            if (sql[i + 1] === c) { i += 2; continue; }
+            i++;
+            break;
+          }
+          i++;
+        }
+        out += `\x00${literals.length}\x00`;
+        literals.push(sql.slice(start, i));
+        continue;
+      }
+      if (c === "-" && next === "-") {
+        const start = i;
+        while (i < n && sql[i] !== "\n") i++;
+        out += `\x00${literals.length}\x00`;
+        literals.push(sql.slice(start, i));
+        continue;
+      }
+      if (c === "/" && next === "*") {
+        const start = i;
+        i += 2;
+        while (i < n && !(sql[i] === "*" && sql[i + 1] === "/")) i++;
+        i = Math.min(i + 2, n);
+        out += `\x00${literals.length}\x00`;
+        literals.push(sql.slice(start, i));
+        continue;
+      }
+      out += c;
+      i++;
+    }
+    return { masked: out, literals };
+  }
+
+  /** Inverse of maskLiterals. */
+  private static restoreLiterals(masked: string, literals: string[]): string {
+    return masked.replace(/\x00(\d+)\x00/g, (_m, idx) => literals[Number(idx)]);
+  }
+
+  // A concat/ilike operand: a masked literal-or-identifier token, a simple
+  // function call, a (qualified) identifier, a placeholder, or a number. The
+  // function-call args exclude `|` so a nested `||` never splits the chain.
+  private static readonly PRIMARY =
+    "(?:\\x00\\d+\\x00|[A-Za-z_][\\w$]*\\s*\\([^()|]*\\)|[A-Za-z_][\\w$]*(?:\\.[A-Za-z_][\\w$]*)*|:[A-Za-z_]\\w*|\\$\\d+|\\?|%s|\\d+(?:\\.\\d+)?)";
+
   /**
-   * Convert || concatenation to CONCAT() for MySQL/MSSQL.
+   * Convert `||` string concatenation to `CONCAT(...)` for MySQL/MSSQL.
    *
-   * 'a' || 'b' || 'c'  →  CONCAT('a', 'b', 'c')
+   * Rewrites ONLY `||` operators joining expression operands OUTSIDE any string
+   * literal or comment, and only the operand chain — never the whole statement:
+   *   SELECT a || b FROM t   ->  SELECT CONCAT(a, b) FROM t
+   *   WHERE data = 'a||b'    ->  WHERE data = 'a||b'   (literal untouched)
    */
   static concatPipesToFunc(sql: string): string {
     if (!sql.includes("||")) return sql;
-    const parts = sql.split("||");
-    if (parts.length > 1) {
-      return "CONCAT(" + parts.map((p) => p.trim()).join(", ") + ")";
-    }
-    return sql;
+    const { masked, literals } = SQLTranslator.maskLiterals(sql);
+    if (!masked.includes("||")) return sql; // every || was inside a literal/comment
+    const chain = new RegExp(
+      `${SQLTranslator.PRIMARY}(?:\\s*\\|\\|\\s*${SQLTranslator.PRIMARY})+`,
+      "g",
+    );
+    const rewritten = masked.replace(chain, (m) => "CONCAT(" + m.split(/\s*\|\|\s*/).join(", ") + ")");
+    return SQLTranslator.restoreLiterals(rewritten, literals);
   }
 
   /**
-   * Convert TRUE/FALSE to 1/0 for engines without boolean type (Firebird).
+   * Convert bare TRUE/FALSE to 1/0 for engines without a boolean type. A
+   * TRUE/FALSE INSIDE a string literal is data and is left untouched
+   * (`WHERE label = 'TRUE'` is preserved).
    */
   static booleanToInt(sql: string): string {
-    sql = sql.replace(/\bTRUE\b/gi, "1");
-    sql = sql.replace(/\bFALSE\b/gi, "0");
-    return sql;
+    if (!/\b(?:TRUE|FALSE)\b/i.test(sql)) return sql;
+    const { masked, literals } = SQLTranslator.maskLiterals(sql);
+    const rewritten = masked.replace(/\bTRUE\b/gi, "1").replace(/\bFALSE\b/gi, "0");
+    return SQLTranslator.restoreLiterals(rewritten, literals);
   }
 
   /**
-   * Convert ILIKE to LOWER() LIKE LOWER() for engines without ILIKE.
+   * Convert `col ILIKE pattern` to `LOWER(col) LIKE LOWER(pattern)` for engines
+   * without ILIKE. The pattern operand is captured whole (a multi-word
+   * `'%two words%'` survives) and an ILIKE INSIDE a string literal is untouched.
    */
   static ilikeToLike(sql: string): string {
-    return sql.replace(
-      /(\S+)\s+ILIKE\s+(\S+)/gi,
-      (_match, col: string, val: string) => `LOWER(${col.trim()}) LIKE LOWER(${val.trim()})`,
+    if (!/ilike/i.test(sql)) return sql;
+    const { masked, literals } = SQLTranslator.maskLiterals(sql);
+    const re = new RegExp(
+      `(${SQLTranslator.PRIMARY})\\s+ILIKE\\s+(${SQLTranslator.PRIMARY})`,
+      "gi",
     );
+    const rewritten = masked.replace(re, (_m, col: string, val: string) => `LOWER(${col}) LIKE LOWER(${val})`);
+    return SQLTranslator.restoreLiterals(rewritten, literals);
   }
 
   /**
@@ -108,10 +190,13 @@ export class SQLTranslator {
       case "mysql":
         return sql.replace(/AUTOINCREMENT/gi, "AUTO_INCREMENT");
       case "postgresql":
-        return sql.replace(
-          /INTEGER\s+PRIMARY\s+KEY\s+AUTOINCREMENT/gi,
-          "SERIAL PRIMARY KEY",
-        );
+        // BIGINT PRIMARY KEY AUTOINCREMENT -> BIGSERIAL (a real 64-bit sequence);
+        // INTEGER PRIMARY KEY AUTOINCREMENT -> SERIAL. A plain BIGINT with the
+        // keyword merely stripped has no sequence and cannot auto-increment.
+        return sql
+          .replace(/\bBIGINT\s+PRIMARY\s+KEY\s+AUTOINCREMENT\b/gi, "BIGSERIAL PRIMARY KEY")
+          .replace(/\bINTEGER\s+PRIMARY\s+KEY\s+AUTOINCREMENT\b/gi, "SERIAL PRIMARY KEY")
+          .replace(/\s*\bAUTOINCREMENT\b/gi, "");
       case "mssql":
         return sql.replace(/AUTOINCREMENT/gi, "IDENTITY(1,1)");
       case "firebird":